mirror of
https://github.com/baketnk/frame-yap.git
synced 2026-10-06 06:00:04 +02:00
docs: align release scope and track remaining device acceptance gates
This commit is contained in:
baketnk committed
1 parent
4498ef5d04
commit
1321ca8316
9 files changed
+622
-527
No files matched your search
+73
-99
@@ -1,108 +1,82 @@
|
||||
# Installation and distribution goal
|
||||
# Installation goal and current boundary
|
||||
|
||||
**User goal:** install from GitHub with a `curl … | bash`-style command, without a
|
||||
Steam store AppID. An idempotent archive installer and native-only local artifacts
|
||||
are now implemented/tested; no public release is published. A bundled-ASR
|
||||
experience is not yet offered. This document retains the target
|
||||
design; see [current packaging](packaging.md) and [third-party notes](third-party.md).
|
||||
Planned installer work (binary-or-source choice, flag-driven operation) is in
|
||||
[TODO.md](../TODO.md).
|
||||
Goal: a one-command, pinned GitHub release install for Steam Frame without a Steam
|
||||
store AppID, sudo or end-user compiler. **No public archive or verified clean
|
||||
install is published. Do not advertise a `curl | sh` command as functional.**
|
||||
The local installer has binary-archive and explicitly provisioned source-build
|
||||
modes, machine-readable plans/results and an attended TTY path. The current
|
||||
native-only artifact does not include or pip-install an ASR runtime; it is not
|
||||
a one-command voice-typing experience. See [packaging](packaging.md) for exact
|
||||
flags and [third-party inventory](third-party.md) for open license/ABI audits.
|
||||
|
||||
The read-only `scripts/install-preflight.sh` checks whether a host appears suitable
|
||||
for the **proposed** Linux ARM64 glibc package format and has the expected basic
|
||||
bootstrap utilities. It reports system Python, Git and uv, but none is required
|
||||
for the intended bundled release. A read-only check on one Frame observed
|
||||
Python 3.12.3 and Git, but not uv; availability may change. This script
|
||||
is not an installer or a model/runtime compatibility test; it has no downloads,
|
||||
registration, SteamVR initialization or persistent changes. No glibc minimum can
|
||||
be certified until release artifacts are chosen and tested.
|
||||
`scripts/install-preflight.sh` is a read-only Linux ARM64/glibc/bootstrap check;
|
||||
`--source` adds toolchain/library checks. It does not download, install, register,
|
||||
or certify model/runtime compatibility or a minimum libc version. Its report of
|
||||
Python/Git/uv availability is not a runtime guarantee: `install.sh` currently
|
||||
needs Python 3.12+ **for its bootstrap**, while native-only voice inference needs
|
||||
a separately provisioned compatible CPU Python environment and pinned weights.
|
||||
|
||||
## Non-Steam overlay identity
|
||||
## OpenVR identity
|
||||
|
||||
OpenVR overlay applications do not require a Steam store AppID or Steamworks.
|
||||
The native executable initializes as `VRApplication_Overlay`. For discoverability
|
||||
and optional autolaunch, register an OpenVR application manifest with a stable,
|
||||
project-owned **string application key** (proposed: `local.frameyap.overlay`).
|
||||
That key is not a numeric Steam AppID. No purchase/store listing or non-Steam Steam
|
||||
library shortcut should be necessary for the normal route.
|
||||
`local.frameyap.overlay` is a string OpenVR application key, **not** a Steam
|
||||
store AppID. The installer creates a manifest/desktop launcher user-locally but
|
||||
does not register/launch the app by default. Explicit `frameyap --register
|
||||
/absolute/manifest/path` uses the OpenVR registration API; registration alone
|
||||
did not reveal a launcher in the first checked dashboard menu. On one Frame the
|
||||
user opened the panel from the **Non-Steam** section and quit; shortcut discovery
|
||||
and persistence after a normal restart are still unverified. Optional
|
||||
`--autolaunch`/`--no-autolaunch` on the installer explicitly request OpenVR
|
||||
registration/autolaunch choices; no SteamVR settings or sessions are changed
|
||||
without that request. Unregister explicitly before uninstall. SteamVR must
|
||||
already be available for registration; never start/restart it for installation.
|
||||
|
||||
The manifest identifies the installed executable; the installer/registration
|
||||
helper should use `IVRApplications::AddApplicationManifest` and the corresponding
|
||||
remove operation, not hand-edit Steam's internal JSON. Autolaunch uses the OpenVR
|
||||
application setting only when explicitly requested. Validate the exact manifest,
|
||||
launch behaviour, registration persistence and uninstall on native Frame before
|
||||
claiming this route works end to end. Existing probes established overlay client
|
||||
initialization, not manifest installation.
|
||||
## Installation workflows
|
||||
|
||||
SteamVR/OpenVR must already be installed and usable. If registration needs a
|
||||
running runtime, defer it to the first explicit launch rather than starting or
|
||||
restarting SteamVR behind the user's back.
|
||||
- **Binary mode** (no compiler): verify a locally supplied ARM64 archive digest,
|
||||
or, after a vetted release actually exists, explicitly approve retrieval of
|
||||
a pinned `v0.1.YYYYMMDDHHMM` GitHub tag and checksum. No moving `latest` tag.
|
||||
`--mode binary --archive FILE --sha256 HASH --version 0.1.YYYYMMDDHHMM`
|
||||
selects the local-artifact path.
|
||||
- **Source mode**: requires explicit local source, SDK, SDL/OpenVR libraries and
|
||||
their notices, CMake/C++20, native build dependencies and a version. It builds,
|
||||
stages, packages and continues through local installation; it does **not**
|
||||
provision ASR packages or bypass producer license obligations. See
|
||||
[packaging](packaging.md) for all flags.
|
||||
- **Model**: only an explicit `--install-model --backend redux --yes` fetches
|
||||
pinned public files for the *already installed* backend. Inspect the read-only
|
||||
`--print-plan --json` first; it includes model size, attribution and license
|
||||
metadata from `assets/backends/redux.json`. `--expected-manifest-sha256 HASH`
|
||||
binds consent to the exact installed manifest bytes and fails before model
|
||||
directory creation/network if they changed. The local in-panel chooser shows
|
||||
source, size, license text, attribution and manifest digest, then requires a
|
||||
second **Confirm Install** click; the installed/native UI route still needs
|
||||
clean-target and headset acceptance. `--without-model` permits an
|
||||
archive install without bundled model files. Neither operation installs Torch,
|
||||
moondream, Kestrel or an interpreter. Launch paths to an independently
|
||||
authorized runtime/model can be set in `paths.conf`.
|
||||
- **Noninteractive**: supply flags and `--yes` for network/model consent.
|
||||
`--print-plan` is read-only; `--json` provides structured results/errors and
|
||||
progress events for a model download. No prompt reads stdin in a pipe. An
|
||||
empty TTY invocation offers a local menu and prints equivalent flags.
|
||||
|
||||
## Intended user experience
|
||||
Installation is user-local under XDG data/config paths with a managed launcher,
|
||||
retained rollback, SHA-256/path validation, foreign-file refusal and a lock
|
||||
shared with the app. No OS package changes, udev rule, root service, Steam store
|
||||
listing, unrelated application dependency, microphone recording, input injection
|
||||
or automatic update daemon. Hashes detect accidental/unauthorized alteration
|
||||
of a downloaded artifact but do not authenticate a compromised publisher;
|
||||
release metadata needs independent trust. No installer operation silently runs
|
||||
pip or launches inference. Native-only archives support overlay checks but need
|
||||
an externally provisioned runtime/weights before voice typing. Selecting an
|
||||
uninstalled backend does not authorize a download or supply its inference engine.
|
||||
|
||||
1. Run one documented command from the eventual GitHub repository/release.
|
||||
2. Installer identifies native Linux ARM64 Frame, resolves a pinned release and
|
||||
explains/downloads the application, compatible CPU runtime and pinned model.
|
||||
3. User-local installation provides a simple `frameyap` launcher, desktop
|
||||
entry where supported, and an OpenVR manifest. No compiler, engine checkout,
|
||||
Python dependency troubleshooting or separate ASR server for ordinary users.
|
||||
4. The user explicitly launches/enables dictation. No installation-time microphone
|
||||
recording, input injection, inference benchmark or overlay takeover.
|
||||
## Gate before publishing the goal as fulfilled
|
||||
|
||||
Illustrative command shape only; `OWNER`, `REPO` and `VERSION` are placeholders:
|
||||
|
||||
```sh
|
||||
curl --fail --silent --show-error --location \
|
||||
https://raw.githubusercontent.com/OWNER/REPO/VERSION/install.sh | bash
|
||||
```
|
||||
|
||||
Also document a download-inspect-run path for users who do not want to pipe remote
|
||||
code into a shell. Pin a release/tag instead of executing a moving branch by default.
|
||||
Offer explicit version selection and noninteractive flags; do not read interactive
|
||||
confirmation from stdin while the installer itself is arriving through that pipe.
|
||||
|
||||
## Packaging boundary
|
||||
|
||||
- Prebuilt ARM64 executable plus a known-compatible, isolated CPU inference runtime;
|
||||
no external application libraries/assets and no system Python modification.
|
||||
- Model fetched during explicit installation/setup, with pinned revision/hash and
|
||||
attribution. A documented `--without-model` option can defer the large download.
|
||||
No surprise first-utterance downloads. Runtime components are installed from
|
||||
their own package index rather than redistributed in our tarball.
|
||||
- Install under `$XDG_DATA_HOME/frameyap` (default `~/.local/share/...`),
|
||||
configuration under `$XDG_CONFIG_HOME/frameyap`, optional launcher in
|
||||
`~/.local/bin`; transient audio stays in a private `$XDG_RUNTIME_DIR` directory.
|
||||
- No sudo, OS read-only-root changes, package-manager installs, udev changes,
|
||||
`/dev/uinput` permission changes or modifications to unrelated launchers.
|
||||
- No Steam store AppID, Steamworks SDK, root service or network ASR dependency.
|
||||
- Third-party notices for everything we redistribute must be included with a release.
|
||||
|
||||
## Installer lifecycle and safety
|
||||
|
||||
- Detect architecture, libc and prerequisites first. Unsupported hosts fail with a
|
||||
clear explanation; never install an x86 payload silently on ARM64.
|
||||
- Download to a staging directory, check versioned SHA-256 manifests and archive
|
||||
paths, then atomically select the completed version. HTTPS/checksums alone do not
|
||||
authenticate a compromised publisher; use signed release metadata if provided.
|
||||
- Keep configuration across upgrades; retain the previous version for rollback.
|
||||
Refuse or defer replacement while this application's process is running rather
|
||||
than killing arbitrary processes. Never touch SSH or unrelated sessions.
|
||||
- Autostart is opt-in (`--autostart` or explicit settings); do not enable a systemd
|
||||
service or SteamVR autolaunch by default. Do not enable overlay input overrides.
|
||||
- Uninstall removes only owned launcher, manifest registration and install files;
|
||||
model/config deletion is separately explicit. Preserve other SteamVR apps.
|
||||
- No update daemon initially. A deliberate rerun/update command is sufficient.
|
||||
|
||||
## Acceptance before advertising one-command installation
|
||||
|
||||
- Clean supported Frame: install without sudo/compiler/engine checkout/store AppID;
|
||||
launch overlay, load local Redux and type into an owned disposable target.
|
||||
- Normal use after installation needs no network connection or desktop ASR host.
|
||||
- Failed download/hash, unsupported architecture, low disk space and interrupted
|
||||
upgrades leave a usable previous install or a cleanly reported failure.
|
||||
- Reinstall, rollback and uninstall preserve unrelated data and SteamVR entries.
|
||||
- Noninteractive piped invocation never hangs on stdin; inspection-first path works.
|
||||
- Autolaunch remains off unless chosen; uninstall removes only our registration.
|
||||
- Hardware-free installer tests use temporary homes, mocked runtime registration
|
||||
and local fixture artifacts. Never exercise a real user's Steam configuration
|
||||
in ordinary CI/CTest.
|
||||
Vet the **exact** release closure/licenses, ARM64 symbol versions/loader,
|
||||
model attribution and compatible CPU Python environment; establish a tested
|
||||
libc/runtime floor, then publish and authenticate a checksummed archive from a
|
||||
clean tag. On a clean supported Frame, install without a compiler/sudo/store ID,
|
||||
load Redux, type into a disposable owned target and validate rollback/uninstall,
|
||||
foreign-file failures, autolaunch off, and no unintended session changes. Separately
|
||||
validate microphone → review → delivered input and headset comfort. Offline
|
||||
installer fixture tests and a local native build are not those acceptance gates.
|
||||
Reference in new issue
Block a user