docs+chore: address final review findings

- Correct the vendored libnspire-sys retry limit in spec and plan: the actual constant in vendor/libnspire-sys/libnspire/src/cx2.cpp:391 is 30, not 100. The '10 -> 100' claim originated in nlink-cli's own Cargo.toml comment and was propagated into both documents unverified. - Drop @tauri-apps/plugin-opener from desktop/package.json; the Rust plugin and its capability entry were removed in Task 3, leaving this dangling. - Reconcile desktop/package.json version 0.1.0 -> 0.1.6 to match Cargo.toml and tauri.conf.json. - Rewrite desktop/README.md, which still instructed users to 'sudo apt install webkit2gtk-4.0' -- the exact unavailable package this port exists to move off. Now documents npm workspaces, the --legacy-peer-deps requirement, the dist/-before-cargo gotcha, snap LD_LIBRARY_PATH breakage, AppImage FUSE fallback, and the vendored patch. Disclosure note: commit 4626858 also committed the previously untracked nlink-cli/ and vendor/ trees (~5900 lines). Committing vendor/ is required -- the [patch.crates-io] override cannot resolve without it -- but the commit message did not say so. Recorded here rather than rewriting branch history. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2026-08-07 18:23:28 +00:00 · 2026-07-19 21:41:28 -04:00 · 2026-07-19 21:41:28 -04:00 · 320a24022c
parent 0c9fd4d86c
commit 320a24022c
4 changed files with 86 additions and 25 deletions
--- a/desktop/README.md
+++ b/desktop/README.md
@ -1,32 +1,94 @@
 # N-Link

-Free, cross-platform, CX-II compatible computer linking program for the TI-Nspire
+Free, cross-platform, CX-II compatible computer linking program for the TI-Nspire.

-## Project setup
-You'll need to install [Node.js](https://nodejs.org/en/download/package-manager),
-[Yarn](https://classic.yarnpkg.com/en/docs/install/) (which may be included with your installation of Node.js), and
-[Rust](https://rustup.rs/). You'll also need a
-[C compiler](https://github.com/alexcrichton/cc-rs#compile-time-requirements) available. On Linux, you'll need
-`webkit2gtk` and `squashfs-tools`, which, on Ubuntu, can be installed with
-`sudo apt install webkit2gtk-4.0 squashfs-tools`.
-```
-yarn
+This package is a **Tauri 2 + Vue 3 + Vite** application. It was ported from
+Tauri 1.0.0-beta.8 / Vue CLI, which linked `webkit2gtk-4.0` and could not build
+or run on current distributions (Ubuntu 26.04 ships only `webkit2gtk-4.1`).
+
+Currently Linux-only: bundle targets are `deb` and `appimage`.
+
+## Prerequisites
+
+- [Node.js](https://nodejs.org/) 22+ (npm ships with it — this project uses
+  **npm workspaces**, not yarn)
+- [Rust](https://rustup.rs/) 1.97+
+- System libraries (Ubuntu/Debian):
+
+```bash
+sudo apt-get install -y \
+  libwebkit2gtk-4.1-dev \
+  libjavascriptcoregtk-4.1-dev \
+  libsoup-3.0-dev \
+  librsvg2-dev \
+  libxdo-dev \
+  libayatana-appindicator3-dev \
+  libusb-1.0-0-dev \
+  build-essential curl wget file
 ```

-### Compiles and hot-reloads for development
-```
-yarn tauri:serve
+Verify they resolve before building:
+
+```bash
+for p in webkit2gtk-4.1 javascriptcoregtk-4.1 libsoup-3.0 gtk+-3.0 libusb-1.0; do
+  printf "%-24s " "$p"; pkg-config --modversion "$p" || echo MISSING
+done
 ```

-### Compiles and minifies for production
-```
-yarn tauri:build
+## Setup
+
+Run from the **repository root** (this is a workspace member):
+
+```bash
+npm install --workspace desktop --legacy-peer-deps
 ```

-### Lints and fixes files
-```
-yarn lint
+`--legacy-peer-deps` is currently required: the sibling `n-link-core` package is
+still on Vue 2 and its peer ranges conflict. It can be dropped once `n-link-core`
+is ported to Vue 3.
+
+## Development
+
+```bash
+cd desktop
+npm run tauri dev
 ```

-### Customize configuration
-See [Configuration Reference](https://cli.vuejs.org/config/).
+## Production build
+
+```bash
+cd desktop
+npm run tauri build
+```
+
+Produces `src-tauri/target/release/bundle/deb/*.deb` and
+`.../appimage/*.AppImage`.
+
+## Headless CLI
+
+The same binary works without a GUI:
+
+```bash
+./src-tauri/target/release/n-link --help
+./src-tauri/target/release/n-link ls /
+```
+
+## Notes and gotchas
+
+- **`cargo` commands need `dist/` to exist.** Tauri's `generate_context!` macro
+  validates the `frontendDist` path at compile time, so a bare
+  `cargo check` / `cargo build` in `src-tauri/` fails on a fresh clone until the
+  frontend has been built once: `npm run build --workspace desktop`.
+  `npm run tauri build` does this for you.
+- **Do not run the binary from a snap-confined shell** (for example, the
+  integrated terminal of VS Code installed as a snap). Snap injects an
+  `LD_LIBRARY_PATH` whose `libpthread` shadows the system one, producing
+  `undefined symbol: __libc_pthread_init`. Use a normal terminal.
+- **AppImage needs FUSE.** Without it, run the AppImage with
+  `--appimage-extract` and launch `squashfs-root/AppRun` instead.
+- **`vendor/libnspire-sys`** at the repo root is a locally patched crate wired in
+  via `[patch.crates-io]`. It raises the CX II NNSE handshake retry limit
+  (10 → 30). The build will not reproduce upstream behaviour without it.
+- **Known upstream limitation:** libnspire's CX II support has been frozen since
+  2020. Against current CX II firmware, data transfers may return `Busy` or hang.
+  This is independent of the Tauri version and is not a defect in this port.
--- a/desktop/package.json
+++ b/desktop/package.json
@ -1,7 +1,7 @@
 {
  "name": "n-link",
  "private": true,
-  "version": "0.1.0",
+  "version": "0.1.6",
  "type": "module",
  "scripts": {
    "dev": "vite",
@ -12,7 +12,6 @@
  "dependencies": {
    "@tauri-apps/api": "^2.11.1",
    "@tauri-apps/plugin-dialog": "^2.7.2",
-    "@tauri-apps/plugin-opener": "^2",
    "@tauri-apps/plugin-shell": "^2.3.5",
    "vue": "^3.5.13"
  },
--- a/docs/superpowers/plans/2026-07-19-desktop-tauri2-backend.md
+++ b/docs/superpowers/plans/2026-07-19-desktop-tauri2-backend.md
@ -15,7 +15,7 @@
 - Branch: `port/tauri2-vue3`. Do not commit to `main`.
 - Linux only. Bundle targets are exactly `["deb", "appimage"]`. Never add `msi` or `dmg`.
 - `web/` is **out of scope and knowingly broken**. Do not modify any file under `web/`.
- `vendor/libnspire-sys` is wired via `[patch.crates-io]`. Its raised CX II NNSE handshake retry limit (10 → 100) is required; do not drop the patch or bump `libnspire-sys` past it.
+- `vendor/libnspire-sys` is wired via `[patch.crates-io]`. Its raised CX II NNSE handshake retry limit (10 → 30) is required; do not drop the patch or bump `libnspire-sys` past it.
 - The IPC contract is frozen. Command names, event names, and payload field names (camelCase via serde) must not change.
 - Do not commit `target/` or `node_modules/`.
 - No test framework is introduced. The spec approved **manual verification with `n-link-cli` as oracle**; verification steps below replace the usual TDD cycle. This is a deliberate, recorded decision, not an omission.
--- a/docs/superpowers/specs/2026-07-19-desktop-tauri2-vue3-port-design.md
+++ b/docs/superpowers/specs/2026-07-19-desktop-tauri2-vue3-port-design.md
@ -99,7 +99,7 @@ improvement to code being rewritten end-to-end anyway — not unrelated
 refactoring.

 The patched `vendor/libnspire-sys` (CX II NNSE handshake retry limit raised
-10 → 100) is wired via `[patch.crates-io]`, exactly as `nlink-cli` already does.
+10 → 30) is wired via `[patch.crates-io]`, exactly as `nlink-cli` already does.

 ## IPC contract — held invariant