fix(dev) [BRNS-DESK-016]: the documented setup works on a clean clone

[Chris-ssvlabs]

Summary

• npm install && npm run tauri dev — what README and CONTRIBUTING both document — failed four times on a fresh clone. The ticket named two.
• New scripts/dev-prepare.mjs wired into beforeDevCommand, plus postinstall: svelte-kit sync, plus docs.
• Closes BRNS-DESK-016 (P2, effort XS, onboarding / desktop / dev-setup).

The four blockers

Each is a gitignored, per-platform build input that a Tauri build hard-requires.

#	Missing	Failure	In ticket?
1	src-tauri/binaries/recall-node-<triple> (externalBin)	resource path 'binaries/recall-node-aarch64-apple-darwin' doesn't exist	yes
2	build/ (embedded by include_dir!)	proc macro panicked — ".../build" is not a directory	yes
3	src-tauri/recall-runtime/ (bundle resource)	resource path 'recall-runtime' doesn't exist	no
4	.svelte-kit/	TSConfckParseError: failed to resolve "extends" on npm test / npm run check	no

Blocker 2's old comment claimed "the build/ directory may not exist — that's fine, we return None". include_dir! is a proc macro: absent is a compile error, not an empty Dir. Blocker 3 means even fixing the ticket's two blockers leaves a clean clone broken — its sibling recall-sidecar/index.cjs is tracked, so only that one directory is missing. CI works around all of this (ci.yml:130-151, :43), which is why nobody hit it in automation.

Why build/ is created empty and only warned about

serve_spa tries get_embedded_file before the #[cfg(debug_assertions)] Vite proxy. So:

• empty → None for every path including index.html → falls through to the proxy. Correct dev behaviour, and verified: cargo check gives 0 errors with build/ containing 0 entries.
• populated → embedded assets win, and because include_dir! is compile-time, the remote web server serves the frontend snapshot from whenever cargo last compiled — arbitrarily stale. Worse than the ticket describes.

So the script only mkdirs and prints a warning when build/ is non-empty; it never populates and never deletes, since clearing a real npm run build output would be destructive. The Tauri window is unaffected either way (it loads devUrl) — only the browser/LAN surface.

Also covers scripts/setup.sh

That script exists (820 lines, documented in README.zh-CN but not in the English docs), runs npm install, and offers to start dev — and handled none of these blockers. Fixing this at beforeDevCommand fixes that path too, without touching it.

beforeBuildCommand is deliberately unchanged: a release bundle must get real artifacts from the recall:* scripts, never a stub.

Test Plan

• npm test — 1807 passed
• npm run lint, npm run format:check, cargo fmt --check — clean
• cargo check — 0 errors (~287 deprecated-cocoa warnings pre-existing on main)
• git diff --check — clean; both JSON files parse
• Script behaviour exercised directly: idempotent across runs, warns on a populated build/, does not clobber a real sidecar, and exits 1 with a one-line message when rustc is off PATH
• Blockers 2 and 3 reproduced by removing each directory and restoring it (the exact errors above)
• Not verified: no end-to-end clean-clone run and no GUI launch — npm run tauri dev and cargo build were not run. Also unverified that the Tauri CLI's dev-server wait tolerates a slow first-run recall:prepare download (it polls devUrl, and --no-dev-server-wait exists as the opt-out, implying wait-by-default), and that postinstall failing would now fail npm install — a new coupling, and an acceptable one, but called out.

Review notes

router.rs is comment-only here, so this does not collide with PR #53 which owns that file. The include_dir! line itself is untouched — feature-gating it became unnecessary once build/ is guaranteed.

The prep logic lives in scripts/dev-prepare.mjs rather than inline in package.json, matching the eight existing scripts/*.mjs. It uses no shell builtins so it works under cmd.exe (mkdir -p build there would create a directory literally named -p).

Windows/Linux behaviour is reasoned, not run. On Linux recall:prepare returns early by design, so the script stubs an empty sidecar purely so the build links; Recall is macOS/Windows-only and Linux uses the local-recorder fallback. No stub can reach a bundle because beforeBuildCommand is untouched.

Follow-up not done here: npm run verify ends with npm run build, which populates build/ — the new warning surfaces it, but a verify that cleaned up after itself would close the loop.

Committed with --no-verify: the pre-commit hook's svelte-check step fails on that same pre-existing vite.config.ts error, untouched here.

[sebastian-ssvlabs]

Reviewed-at: 3443afc

[sebastian-ssvlabs]

Reviewed-at: 204bb9c