2026-05-09: Fix missing Rust/Cargo prerequisite for Tauri desktop

Problem

npm run tauri:dev failed with:

failed to run 'cargo metadata' command to get workspace directory:
failed to run command cargo metadata --no-deps --format-version 1:
No such file or directory (os error 2)

Root cause: Rust/Cargo is not installed. Tauri requires Rust to compile the desktop shell. ~/.cargo, rustup, and cargo were all absent.

This is a system prerequisite, not a code bug. However, the scripts were producing a cryptic OS error instead of a clear “install Rust” message.

---

Changes

scripts/tauri-dev.sh and scripts/tauri-build.sh

Two improvements:

1. Source ~/.cargo/env — rustup installs Cargo to ~/.cargo/bin which is not on PATH in non-interactive shells (script shebangs). Sourcing the env file fixes this for users who installed Rust via rustup but haven’t updated their shell profile.

2. Pre-flight cargo check — if cargo is still not found after sourcing, print a clear error with the install command and exit cleanly instead of letting Tauri produce a cryptic No such file or directory OS error.

# Source rustup environment if available (cargo may not be on PATH in non-interactive shells)
if [[ -f "$HOME/.cargo/env" ]]; then
  source "$HOME/.cargo/env"
fi

# Verify cargo is available (Tauri requires Rust to build the desktop shell)
if ! command -v cargo &>/dev/null; then
  echo ""
  echo "❌  Rust/Cargo not found. Tauri requires Rust to build the desktop app."
  echo ""
  echo "   Install Rust with:"
  echo "   curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh"
  echo "   source ~/.cargo/env"
  echo ""
  echo "   Then re-run this script."
  exit 1
fi

scripts/check-prereqs.mjs

Added Rust/Cargo check so npm run setup catches this gap before the user tries to run the desktop app:

let cargoOk = false;
try { execSync('cargo --version', { stdio: 'ignore' }); cargoOk = true; } catch {}
check(
  'Rust/Cargo (required for Tauri desktop)',
  cargoOk,
  'Install: curl --proto=\'=https\' --tlsv1.2 -sSf https://sh.rustup.rs | sh\n      Then: source ~/.cargo/env',
);

docs/src/content/docs/dev-setup.md

Added a Tauri Desktop App section explaining Rust as a prerequisite and how to install it.

---

Execution Summary

Commit: 6696d98

Actual changes

File	Change
scripts/tauri-dev.sh	Source ~/.cargo/env + cargo pre-flight check before npx tauri dev
scripts/tauri-build.sh	Same before npx tauri build --bundles app
scripts/check-prereqs.mjs	Added cargo --version check with rustup install instructions
docs/src/content/docs/dev-setup.md	Added Step 5 — Tauri Desktop App with Rust prerequisites
docs/src/content/docs/plans/2026-05-09-fix-tauri-rust-prereq.md	This plan doc (new file)

Deviations from plan

None.

Test results

Gate	Result
Backend unit	⏭ skipped (scripts/docs only — no backend logic changed)
Backend e2e	⏭ skipped
Frontend unit	⏭ skipped
Frontend e2e	⏭ skipped
Manual verification	✅ Script exits cleanly with actionable error when cargo is missing

Key discoveries

• ~/.cargo/env sourcing is essential: rustup adds cargo to PATH via this file, but non-interactive bash scripts don’t source ~/.bashrc/~/.zshrc. Without it, a freshly-installed Rust via rustup would still fail.
• The check comes after ~/.cargo/env sourcing so both “not installed” and “installed but not on shell PATH” cases are handled.
• Rust still needs to be installed manually by the user — this fix only makes the error message clear and actionable. Once Rust is installed (curl ... | sh && source ~/.cargo/env), npm run tauri:dev will proceed to actually compile and launch the app.