temps-plugin

Temps Plugin Development

Build external plugins as standalone Rust binaries that Temps discovers, spawns, and proxies to.

Architecture Overview

Temps (main process)
  ├── Scans ~/.temps/plugins/ for binaries
  ├── Spawns each binary with --socket-path, --auth-secret, --data-dir
  ├── Reads JSON manifest from stdout (handshake phase 1)
  ├── Reads ready signal from stdout (handshake phase 2)
  ├── Opens WebSocket to plugin's /_temps/channel (bidirectional data access)
  ├── Proxies /api/x/{plugin_name}/* → Unix socket
  ├── Serves plugin UI at /api/x/{plugin_name}/ui/*
  └── Delivers platform events over the WebSocket channel

Plugins are self-contained binaries. They own their own HTTP routes (axum Router), optional React UI (embedded via include_dir), and SQLite database (via sea-orm in their data_dir).

Critical Rules

NEVER

• Register a /health route — the SDK runtime already provides one. Axum panics on Router::merge with duplicate routes.
• Use rt.block_on() directly inside router() — it deadlocks. Use tokio::task::block_in_place(|| Handle::current().block_on(...)) instead.
• Use #[tokio::main] — the SDK creates its own runtime via run_plugin().
• Access the Temps database directly — use ctx.temps() for platform data queries over the WebSocket channel.
• Use sea-orm with the main Temps database — plugins get their own SQLite in data_dir.
• Return anyhow::Result — use typed error enums with thiserror.
• Use .unwrap() or .expect() in production paths.

ALWAYS

• Use temps_plugin_sdk::main!(YourPlugin) as the entry point.
• Implement ExternalPlugin trait with manifest() and router() at minimum.
• Use block_in_place for any async initialization inside router().
• Embed the UI with include_dir!("$CARGO_MANIFEST_DIR/web/dist") and serve via own routes.
• Keep tests in the same file as the code they test (#[cfg(test)] mod tests).
• Run cargo check -p your-plugin after every modification.
• Run cargo test -p your-plugin to verify tests pass.