temps-plugin
Build external plugins for the Temps deployment platform. Use when the user wants to create, modify, or debug a Temps plugin binary — a standalone Rust process that communicates with Temps over a Unix domain socket. Also use when the user mentions "temps plugin", "external plugin", "plugin binary", "plugin for temps", "plugin UI", or asks about plugin architecture, plugin events, plugin manifest, or plugin SDK. Covers the full lifecycle: project scaffolding, manifest, router, events, SQLite persistence, embedded React UI, build.rs, testing, and deployment into the plugins directory.
gotempsh · AI review on file
Installation
Read the source and dependencies before running a command. Copying does not install or execute anything.
npx skills add gotempsh/temps --skill temps-pluginAbout this skill
name: temps-plugin description: > Build external plugins for the Temps deployment platform. Use when the user wants to create, modify, or debug a Temps plugin binary — a standalone Rust process that communicates with Temps over a Unix domain socket. Also use when the user mentions "temps plugin", "external plugin", "plugin binary", "plugin for temps", "plugin UI", or asks about plugin architecture, plugin events, plugin manifest, or plugin SDK. Covers the full lifecycle: project scaffolding, manifest, router, events, SQLite persistence, embedded React UI, build.rs, testing, and deployment into the plugins directory.
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
/healthroute — the SDK runtime already provides one. Axum panics onRouter::mergewith duplicate routes. - Use
rt.block_on()directly insiderouter()— it deadlocks. Usetokio::task::block_in_place(|| Handle::current().block_on(...))instead. - Use
#[tokio::main]— the SDK creates its own runtime viarun_plugin(). - Access the Temps database directly — use
ctx.temps()for platform data queries over the WebSocket channel. - Use
sea-ormwith the main Temps database — plugins get their own SQLite indata_dir. - Return
anyhow::Result— use typed error enums withthiserror. - Use
.unwrap()or.expect()in production paths.
ALWAYS
- Use
temps_plugin_sdk::main!(YourPlugin)as the entry point. - Implement
ExternalPlugintrait withmanifest()androuter()at minimum. - Use
block_in_placefor any async initialization insiderouter(). - 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-pluginafter every modification. - Run
cargo test -p your-pluginto verify tests pass.
Project Structure
examples/your-plugin/
├── Cargo.toml
├── build.rs # Builds web UI (bun + vite), creates fallback in debug
├── src/
│ ├── main.rs # Plugin struct, manifest, router, on_event, UI handlers, entry point
│ ├── db.rs # SQLite persistence (sea-orm entities + raw DDL migrations)
│ ├── types.rs # Shared types (Settings, API DTOs) — all serde(rename_all = "camelCase")
│ └── ... # Additional modules as needed
└── web/ # React UI (Vite + TypeScript)
├── package.json
├── vite.config.ts # base: "/api/x/{plugin_name}/ui/"
├── tsconfig.json
├── index.html
└── src/
├── main.tsx
├── App.tsx
├── api.ts # API_BASE = "/api/x/{plugin_name}"
├── types.ts
├── router.ts # Hash-based routing with useSyncExternalStore
├── styles.css
└── components/
Step-by-Step: Creating a New Plugin
1. Cargo.toml
[package]
name = "temps-your-plugin"
version = "0.1.0"
edition = "2021"
publish = false
[[bin]]
name = "temps-your-plugin"
path = "src/main.rs"
[dependencies]
temps-plugin-sdk = { path = "../../crates/temps-plugin-sdk" }
axum = { version = "0.8" }
sea-orm = { workspace = true }
serde = { version = "1", features = ["derive"] }
serde_json = "1"
tokio = { version = "1", features = ["full"] }
tracing = "0.1"
chrono = { version = "0.4", features = ["serde"] }
thiserror = { workspace = true }
include_dir = "0.7"
mime_guess = "2.0"
# Add reqwest, scraper, url, uuid etc. as needed
[dev-dependencies]
tempfile = "3"
Add the crate to the workspace Cargo.toml members list:
members = [
# ...existing...
"examples/your-plugin",
]
2. build.rs
Copy from the reference implementation. Key behavior:
- Debug mode (default): Skips web build, creates fallback
web/dist/index.htmlsoinclude_dir!doesn't fail. - Release mode (or
FORCE_WEB_BUILD=1): Runsbun install+bun run build.
use std::env;
use std::path::Path;
use std::process::Command;
fn main() {
let manifest_dir = env::var("CARGO_MANIFEST_DIR").unwrap();
let web_dir = Path::new(&manifest_dir).join("web");
let dist_dir = web_dir.join("dist");
println!("cargo:rerun-if-changed=web/src");
println!("cargo:rerun-if-changed=web/index.html");
println!("cargo:rerun-if-changed=web/vite.config.ts");
println!("cargo:rerun-if-changed=web/package.json");
println!("cargo:rerun-if-env-changed=FORCE_WEB_BUILD");
let profile = env::var("PROFILE").unwrap_or_default();
if profile == "debug" && env::var("FORCE_WEB_BUILD").is_err() {
println!("cargo:warning=Skipping plugin web build in debug mode (use FORCE_WEB_BUILD=1 to build)");
let _ = std::fs::create_dir_all(&dist_dir);
let fallback = dist_dir.join("index.html");
if !fallback.exists() {
let _ = std::fs::write(&fallback, r#"<!DOCTYPE html>
<html><head><meta charset="utf-8"><title>Plugin (dev)</title></head>
<body style="font-family:system-ui;padding:2rem;color:#a1a1aa;background:#09090b;text-align:center">
<h2>Plugin UI not built</h2>
<p>Run <code style="color:#3b82f6">cd examples/your-plugin/web && bun install && bun run build</code></p>
<p>
Read the complete source ↗