Dev loop¶

Two paths depending on whether you're touching Go, Svelte, or both.

Path 1: dev-watch.sh (Go + SPA, full rebuild)¶

scripts/dev-watch.sh polls source files every 2 seconds; on any change under server/ or web/src/ it runs make build and bounces the binary.

bash scripts/dev-watch.sh
tail -f /tmp/pluma.log              # in another pane

Single-instance locked at /tmp/pluma-dev-watch.lock — second invocation aborts so you don't get a bounce storm.

Flags:

Flag	Effect
`--no-browser`	Appends `-open=false` so rebuilds don't pop a new tab on every save. Same as `DEV_WATCH_NO_BROWSER=1`.

The script tails the binary's log to stderr if the process exits within 600 ms of start (catches malformed config.toml / port-already-taken failures that would otherwise look like "script returned immediately").

Path 2: vite + go in parallel (FE iteration)¶

When you're only touching the SPA and want HMR, run Vite separately:

# pane 1
make server-dev    # ./pluma on :8787 with -open=false
# pane 2
make web-dev       # vite on :5173, proxies /api to :8787

Open http://localhost:5173 — Vite serves the SPA, proxies API calls to the running Go server. Save a .svelte file, see the change without rebuilding the binary.

Logs¶

/tmp/pluma.log is where the binary's stderr lands when started via dev-watch.sh. It includes:

HTTP access log (gated on log_requests)
TTS / image / connection errors
Tailscale events (filtered to skip the every-5s auth-URL spam)

tail -f /tmp/pluma.log is the friend. grep -E '⚠|ERROR|FATAL' for the bad stuff.

Resetting state¶

Common dev resets:

# Clean rebuild
make clean && make build

# Reset config.toml to defaults (regenerates the commented seed)
rm ~/.config/pluma/config.toml

# Re-run the first-run wizard without losing data
sed -i '' 's/^setup_completed = true/setup_completed = false/' ~/.config/pluma/config.toml

# Nuclear: drop the whole data dir
rm -rf ~/.config/pluma

Working on docs¶

The MkDocs site rebuilds locally with the same workflow CI uses:

pip install mkdocs-material mkdocs-material-extensions pymdown-extensions
mkdocs serve
# open http://127.0.0.1:8000

Edit docs/*.md; the page auto-refreshes. mkdocs build --strict runs the same validation CI uses.

Hooks¶

No pre-commit hooks installed by default. CI runs make test + make check on every push; same locally before committing is the convention.