feat: ffmpeg is looked for on PATH, then in the Tools Directory, and wtsexporter only there (#1053)

[mbeisser1]

Feature Description

Step 2 of #1053: the desktop app and the server it starts look for ffmpeg and ffprobe in two places only, PATH and then the Tools Directory (~/message-crate/tools). wtsexporter is always the app's own copy in the Tools Directory. Settings → System → Media has nothing to type: it names the Tools Directory and shows one status line each for ffmpeg, ffprobe and wtsexporter, with the path found or that the program is missing.

The download (step 3) is not here, so on a computer without the programs every line reads "not found" until a person installs ffmpeg on PATH or puts the files in the Tools Directory by hand.

User Story

As a person running the desktop app, I want the app and its server to find ffmpeg and wtsexporter in one known place, so that the download in step 3 has one directory to fill and nothing in Settings asks me to type a path.

Implementation Details

• media crate (crates/libs/media/src/tools.rs). find_tool(name, search_path, tools_dir) searches each PATH directory, then the Tools Directory, and nowhere else. A file that does not answer -version is passed over. set_tools_dir names the Tools Directory for the whole process. The beside-the-program, lib/, parent lib/, MESSAGE_CRATE_BIN and bare-name lookups are gone. probe_ffmpeg_tools and FfmpegToolsProbe are replaced by ffmpeg_path(), ffprobe_path() and a public require_ffmpeg(), whose error names the missing tool and where it was looked for. For tests, testutil can replace PATH (set_search_path), so hide_ffmpeg still hides a real ffmpeg.
• wtsexporter (crates/exporters/whatsapp-exporter/src/wtsexporter.rs). The lookup reads only media::tools_dir(). The WTSEXPORTER variable, PATH, cli/ and MESSAGE_CRATE_BIN are no longer read. A missing copy is an error that names the Tools Directory. PINNED_HINT is unchanged, as WhatsApp replies link only once a fork release records full_key_id and reply_key_id #1936 asked; the lookup's error text still uses it.
• Server. serve --tools-dir <dir> sets ServerConfig::tools_dir, which is #[serde(skip)]. The config file has no key for it, and a tools_dir key is refused as an unknown key. A relative path resolves like --static-dir. server::run calls media::set_tools_dir before anything runs ffmpeg. The CLI reference is regenerated.
• Desktop (src-tauri). At start the app makes ~/message-crate/tools (app_directories::use_tools_dir_in) and names it to its own lookups. Launch carries it to the server as --tools-dir. commands/ffmpeg.rs (probe_ffmpeg_tools, set_ffmpeg_tools_dir) is deleted, which also covers the last part of Desktop commands write, delete, open and run what the window names, with guards whose root the window supplies #1127. The new tools_status command returns { toolsDir, ffmpeg, ffprobe, wtsexporter }, and each program is { state: "found", path } or { state: "missing" }. The status is tagged so that step 3 can add a downloading state and a failed state without changing these two.
• Web. SystemSection drops the field, its debounce and its localStorage key. lib/ffmpeg-tools.ts, which applied the saved directory at start, is deleted. The Import form's missing-ffmpeg check calls invokeToolsStatus. The Import review's line no longer points at the deleted field.

A decision the issue left open. Step 1, the Message Crate Directory with data/, staging/ and tools/, has not landed on main: no commit or PR builds it. This PR therefore defines the Tools Directory as {home}/message-crate/tools, the place the issue's layout decided, and makes only that directory. data/ and staging/ stay as they are for step 1. Step 1 as a whole is filed as #1999.

Key Files Changed

• crates/libs/media/src/tools.rs: the lookup cut to PATH, then the Tools Directory
• crates/exporters/whatsapp-exporter/src/wtsexporter.rs: wtsexporter from the Tools Directory only
• crates/server/server/src/{cli,config,server}.rs: serve --tools-dir
• src-tauri/src/app_directories.rs, main.rs, local_server.rs, commands/tools.rs (new), commands/ffmpeg.rs (deleted)
• web/src/screens/settings/SystemSection.tsx, web/src/lib/tauri.ts, web/src/screens/import/useImportJob.ts

HTTP API Changes

• None. No /v1 route changes. The server CLI gains serve --tools-dir.

Database Changes

• No schema changes
• schema/sql/*.sql changed (every database rebuilds empty and re-imports; the fingerprint is computed, nothing to bump)

How to Test

1. cargo test -p media: path_is_searched_before_the_tools_directory, the_tools_directory_is_searched_when_path_has_no_ffmpeg, a_tool_that_cannot_run_is_passed_over, message_crate_bin_is_not_searched, a_tool_that_arrives_later_is_found.
2. cargo test -p whatsapp-exporter wtsexporter_is, cargo test -p message-crate-server -- cli::tests::serve config::tests::a_config_cannot_name_a_tools_directory, cargo test --manifest-path src-tauri/Cargo.toml -- tools.
3. cd web && npx vitest run src/screens/settings/SystemSection.test.tsx src/screens/import.
4. Desktop: cargo tauri dev with nothing on 8080. Settings → System → Media shows ~/message-crate/tools and the three lines. ps shows the server started with --tools-dir. With ffmpeg uninstalled and copied into ~/message-crate/tools, Convert still works. Not run: the Convert run with ffmpeg only in the Tools Directory and the ps check of --tools-dir were not done for this PR.

Run here: ./scripts/check-pr.sh; cargo test for media, message-staging, message-crate-core, whatsapp-exporter, demo-seed and message-crate-server; the src-tauri tests; the full Vitest suite (2128 tests); and astro check in docs/. All pass.

Browser check with the Playwright MCP, Vite on 5173 against the server on 8080. In the browser, Settings → System shows the desktop-only stub, which now names "the media tools". With a stubbed __TAURI_INTERNALS__ that answers tools_status, the Media part shows the Tools Directory, Found ffmpeg - /usr/bin/ffmpeg, Found ffprobe - /usr/bin/ffprobe and wtsexporter not found, and has no input. A real desktop window was not opened. The src-tauri tests cover the command, the directory and the server flag.

Checklist

• Code follows the project's style guidelines
• Self-reviewed the code
• Added unit tests for new functionality
• Added integration tests where applicable
• Existing tests pass locally
• Updated documentation
• ./scripts/check-pr.sh passes and formatter rewrites are committed

Related Issues

Part of #1053 (step 2). Steps 3 to 5 remain, so this does not close it. It also removes the two commands that #1127's note asked step 2 to delete.

Left for step 5, as the brief limited the user-guide change to the System page:

• docs/src/content/docs/docs/user/import-sources/whatsapp.md:26 still says the program is found on PATH or through WTSEXPORTER.
• docs/src/content/docs/docs/user/features/messages/attachments-and-media.md:81 and :86, features/messages/import.md:234 and features/owner/troubleshooting.md:112 still name the ffmpeg directory field, and the old review line is quoted at :86.

The developer setup in AGENTS.md and contributing.md gains a link from the pipx wtsexporter into ~/message-crate/tools, so a developer's WhatsApp import still runs. #1936 moves that install to the fork's tag, and the two edits may conflict.

Screenshots / Demo

Settings → System → Media, with the desktop process stubbed: a "Tools directory" row with /home/demo/message-crate/tools, then three status lines. There are no inputs.

Deployment Notes

Upgrading: the MESSAGE_CRATE_BIN and WTSEXPORTER environment variables and the saved ffmpeg directory are no longer read. Docker is unchanged, because its image has ffmpeg on PATH.

🤖 Generated with Claude Code

https://claude.ai/code/session_017gbWRfTT5AEWW1D6hTNDr1

[mbeisser1]

Review of 547f8f7 (origin/main merged in; the merge review of the conflict resolution found nothing). Findings whose line is outside the diff follow; the rest are line comments.

• docs/src/content/docs/docs/user/import-sources/whatsapp.md — Spec · spec — whatsapp.md:27 says the app "finds the program when it is on the PATH the app was started with, or when the environment variable WTSEXPORTER holds the full path to it." After this PR both are false, and a reader who follows the page's pipx step gets a WhatsApp import that cannot find wtsexporter. Spec: "The WTSEXPORTER variable and the PATH search for it are deleted." Leaving it until step 5 is a broken instruction, not stale wording: replace the sentence with the Tools Directory and the link step contributing.md gained. Step 5 still removes the pipx step. (Standards reports the same page as a rule break.)
• CHANGELOG.md — Spec · spec — CHANGELOG.md:345 (#1936's Upgrading bullet, from main) says to install the fork "with the line on the guide's WhatsApp page". That line is a pipx install onto PATH, which this PR's bullet above it says is no longer searched. Add the link into ~/message-crate/tools, or point at the #1053 bullet.
• docs/src/content/docs/docs/user/features/messages/attachments-and-media.md — Spec · spec — attachments-and-media.md:81, features/owner/troubleshooting.md:112 and features/messages/import.md:234 still send the reader to the deleted ffmpeg directory field, and system.md:58 now links to attachments-and-media, which describes that field. Spec: "Deleted: the ffmpeg directory field in Settings → System". Step 5 names only the System page and the troubleshooting section, so change these lines here, or file an issue that names them. (Standards reports the same three pages as a rule break.)
• CHANGELOG.md — Spec · spec — Step 1 question: creating a lone ~/message-crate/tools is acceptable. The issue fixes where the Tools Directory is and says the programs sit beside data/, not inside it ("The programs stay where they are."), so steps 2 to 4 do not depend on data/, staging/ or --data-dir. But the issue's 2026-10-05 comment "Step 1 is done" is wrong: on main only the glossary and ADR record it. File a follow-up issue for step 1 as a whole (the data/ and staging/ directories, the server started with --data-dir ~/message-crate/data, the default Staging Directory moved, the button renamed) and link it from the PR body. Also, step 4 of the PR's "How to Test" (Convert with ffmpeg only in the Tools Directory, ps showing --tools-dir) was not run; the body should say so.

[mbeisser1]

Re-review of the fix commits (Standards and Correctness, step 4 of the review), pinned to 10a37c3. Every finding below is fixed in this push.

Correctness · bug web/src/screens/settings/SystemSection.tsx / ImportRunView.tsx: with ffmpeg on PATH and ffprobe nowhere, "Put it in the Tools Directory" led into the two-places state. Fixed in 84550e1, 08d1b88, 79aca07: the hint says to put it beside the other one, or both in the Tools Directory.
Correctness · bug crates/server/server/src/media_queue.rs: in the two-places state the server logged "ffmpeg was not found". Fixed in 1e84d88: tools_unavailable names the programs as not used with the lookup's reason, and names a missing program; two tests.
Correctness · bug crates/libs/media/src/tools.rs: only a complete pair was cached, so a missing or split state spawned -version per file and per asset. Fixed in d58d98a and 10a37c3: the stat-only search runs every call; a successful -version is cached per program by path and a stamp (mtime, size, mode, and on Unix ctime, inode, device); a failure is never cached, so a Gatekeeper approval, a missing library installed, or a passing failure is retried without a restart; a pair that moved from PATH to the Tools Directory is found on the next call. Tests for each.
Correctness · bug crates/libs/media/src/tools.rs (FileStamp): a cached "does not run" by mtime, size and mode alone stayed wrong after a Gatekeeper approval or a missing .so installed; a file replaced with cp -p kept a stale "runs". Fixed in 10a37c3 (above).
Correctness · bug crates/libs/media/src/tools.rs: the cached pair was never checked again, so a pair removed from PATH and copied into the Tools Directory kept returning the deleted paths. Fixed in 10a37c3 (above).
Standards · rule SystemSection.tsx: not used - reason joined clauses with a dash. Fixed in 401215c.
Standards · rule system.md:57: "ffmpeg not used" named the wrong program for the wtsexporter row. Fixed in 467b34c: <program> not used, one line per reason.
Standards · judgement exporters.rs:19: "shows which is missing" also covered the not-used case. Fixed in f03b015.
Standards · judgement ImportRunView.tsx: "ffmpeg or ffprobe" when both are unusable; "with the reason" wrong for a missing program. Fixed in 08d1b88.
Standards · judgement CHANGELOG.md:98: unclear subjects. Fixed in 53479e2.
Standards · judgement CHANGELOG.md:345: "as the bullet above says". Fixed in cc6e3a3.
Standards · judgement whatsapp.md:27: "points it at". Fixed in 8920b68.
Standards · judgement wtsexporter.rs:70: public executable_name says nothing about whose. Fixed in d95315e: wtsexporter_file_name.
Standards · judgement media/src/tools.rs:276: fn split. Fixed in 6ec0092: found_in_two_places_error.
Standards · judgement src-tauri/src/commands/tools.rs:139: repeated set_permissions helper. Fixed in b49002d: media::testutil::write_with_mode shared.

[mbeisser1]

Review summary for 10a37c3.

• Standards: 11 findings, 10 Fixed, 1 Declined (the shared Tools Directory setting read by the wtsexporter lookup; the thread has the reason).
• Spec: 5 findings, all Fixed. The step 1 question is answered with #1053 step 1 is not built: the Message Crate Directory #1999 (step 1 of The desktop app downloads ffmpeg and wtsexporter into the Tools Directory #1053 is not built), linked from the PR body, which also says which "How to Test" step was not run. The stale user-guide pages named in the review (WhatsApp, attachments and media, import, troubleshooting) and the WhatsApp replies link only once a fork release records full_key_id and reply_key_id #1936 Upgrading bullet were fixed here rather than left for step 5.
• Correctness: 4 findings, all Fixed. The macOS Dock PATH case keeps the lookup order the issue decided and fixes the messages and the guide; step 3's download is the real fix.
• Re-review of the fixes (Standards 10, Correctness 5): all Fixed, posted in the second review pinned to 10a37c3.
• Merges of the base: 547f8f7 merged origin/main with conflicts in AGENTS.md, CHANGELOG.md and crates/exporters/whatsapp-exporter/src/wtsexporter.rs (the WhatsApp replies link only once a fork release records full_key_id and reply_key_id #1936 install line against the Tools Directory lookup); its merge review found nothing.
• CI: the ci.yml run on 10a37c3 ended in success, with no commit needed for it. The separate audit.yml job "Audit npm deps" fails on the docs site for a new sharp advisory that this PR does not touch (no lockfile change): npm audit fails on the docs site: sharp below 0.35.5 (GHSA-wq5f-xc86-pv6w) #2000.
• No user thread is open.