[Bug] Dear David, I hope this finds you well and enables you to make your application run on other people computers ;)

[FantasticoFox]

Bug Description

Portability Issues — InterBrain Build & Runtime

Date: 2026-03-20
Scope: Build-time and runtime failures on non-developer hosts

---

Overview

The plugin currently builds and runs reliably on the original developer's machine but has several environmental assumptions that will cause failures on other hosts. Issues range from build-time breakage on Windows to silent runtime failures on fresh Linux installs.

---

Issues

1. Native Binary: sharp (High)

sharp ships pre-compiled C++ bindings. The binary from npm install is tied to the builder's OS, CPU architecture, and Node.js version. It will not load on a different platform.

Affected: All cross-platform distribution scenarios.
Fix: Run npm rebuild sharp on the target host, or replace sharp with a pure-JS alternative for the functionality used.

---

2. Plugin Points Into src/ Directory (Critical)

Multiple services construct runtime paths like:

vault/.obsidian/plugins/interbrain/src/features/realtime-transcription/scripts/

This assumes the plugin is installed as a symlink to the source tree (developer workflow). In a standard Obsidian plugin install, only main.js, styles.css, and manifest.json are present — no src/ directory exists.

Affected: Any non-developer install (end users, CI, testers).
Files: transcription-service.ts:52, web-link-analyzer-service.ts:56, main.ts:528.
Fix: Bundle Python scripts into dist/ and resolve paths relative to the plugin's actual install directory.

---

3. Python Venv Expected Inside src/ (High)

The transcription and web-link-analyzer features expect a pre-created virtual environment at:

src/features/realtime-transcription/scripts/venv/
src/features/web-link-analyzer/scripts/venv/

These are not committed to git. A fresh host has no way to get them without manually running setup.sh, which is undocumented in the main README.

Affected: Fresh installs, CI, new contributors.
Fix: Document setup steps prominently; consider shipping a first-run setup command from within the plugin settings UI.

---

4. Build Script Uses POSIX Shell Commands (High)

package.json build script:

cat styles.base.css dist/main.css > styles.css

This fails on Windows without WSL or Git Bash. Native cmd.exe or PowerShell do not have cat.

Affected: Windows hosts building from source.
Fix: Replace with a cross-platform Node.js script or use a build tool that handles file concatenation.

---

5. ffmpeg Probed at macOS-Specific Hardcoded Paths (Medium)

audio-trimming-service.ts probes a list of paths including:

/opt/homebrew/bin/ffmpeg   # Apple Silicon Homebrew
/usr/local/bin/ffmpeg      # Intel Mac Homebrew

While it also tries PATH first, Linux and Windows users who do not have ffmpeg installed get a silent failure with no guidance.

Affected: Non-Mac hosts, fresh installs.
Fix: On failure, surface a clear error message pointing users to install ffmpeg.

---

6. rad (Radicle) CLI Not Available on Windows (Medium)

The social-resonance-filter feature shells out to the rad CLI, which is macOS/Linux only. A GitHub fallback exists but relies on the correct branching logic firing. If that path is not fully tested, Windows users will hit unhandled shell errors.

Affected: Windows.
Fix: Ensure the Windows fallback path is covered by tests; add an explicit capability check at plugin load.

---

7. (app.vault.adapter as any).basePath — Private Obsidian API (Low–Medium)

Used in 10+ locations to resolve the vault's filesystem path. This is an undocumented internal property. Obsidian has changed adapter internals before; if basePath is removed or renamed, all path resolution breaks silently.

Affected: Future Obsidian versions.
Fix: Centralise the accessor in VaultService (already partially done) and add a defensive fallback. Avoid direct .basePath casts outside that service.

---

Priority Order

#	Issue	Severity
1	Plugin resolves paths into src/ at runtime	Critical
2	sharp native binary not portable	High
3	Build script requires POSIX shell	High
4	Python venv setup undocumented / missing	High
5	ffmpeg missing → silent failure	Medium
6	rad CLI Windows fallback untested	Medium
7	Private basePath API	Low–Medium

Steps to Reproduce

N/A

Expected Behavior

N/A

Actual Behavior

N/A

Operating System

macOS (Apple Silicon - M1/M2/M3/M4)

OS Version

Ubuntu

Obsidian Version

N/A

InterBrain Plugin Version

N/A

Console Logs or Screenshots

No response

Additional Context

No response

[FantasticoFox]

This was generated with Claude Code Anthropic 4.6