From 16bef50c90d8cca04fde4b87e18c50e8fe7c725a Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Sat, 26 Sep 2026 17:37:27 +0000
Subject: [PATCH] feat(project-runner): add popup package.json script runner

Lists the nearest package.json's scripts (file order, fuzzy filter) and runs
the chosen one via the detected package manager in a new tab or split.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01N3jnKVRN7yeC6muFFCaGLD
---
 Cargo.lock                               |  13 ++
 Cargo.toml                               |   2 +-
 README.md                                |  29 +++
 plugins/project-runner/Cargo.toml        |  15 ++
 plugins/project-runner/herdr-plugin.toml |  24 ++
 plugins/project-runner/src/app.rs        | 183 +++++++++++++++
 plugins/project-runner/src/launch.rs     | 126 +++++++++++
 plugins/project-runner/src/log.rs        |  34 +++
 plugins/project-runner/src/main.rs       | 130 +++++++++++
 plugins/project-runner/src/matcher.rs    | 105 +++++++++
 plugins/project-runner/src/project.rs    | 276 +++++++++++++++++++++++
 plugins/project-runner/src/render.rs     | 133 +++++++++++
 plugins/project-runner/src/testing.rs    |  50 ++++
 13 files changed, 1119 insertions(+), 1 deletion(-)
 create mode 100644 plugins/project-runner/Cargo.toml
 create mode 100644 plugins/project-runner/herdr-plugin.toml
 create mode 100644 plugins/project-runner/src/app.rs
 create mode 100644 plugins/project-runner/src/launch.rs
 create mode 100644 plugins/project-runner/src/log.rs
 create mode 100644 plugins/project-runner/src/main.rs
 create mode 100644 plugins/project-runner/src/matcher.rs
 create mode 100644 plugins/project-runner/src/project.rs
 create mode 100644 plugins/project-runner/src/render.rs
 create mode 100644 plugins/project-runner/src/testing.rs

diff --git a/Cargo.lock b/Cargo.lock
index 6547693..df5adbc 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -959,6 +959,19 @@ dependencies = [
  "unicode-ident",
 ]
 
+[[package]]
+name = "project-runner"
+version = "0.1.0"
+dependencies = [
+ "herdr-client",
+ "nucleo-matcher",
+ "ratatui",
+ "serde",
+ "serde_json",
+ "tempfile",
+ "unicode-segmentation",
+]
+
 [[package]]
 name = "quote"
 version = "1.0.47"
diff --git a/Cargo.toml b/Cargo.toml
index 26ddf93..2246716 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -2,7 +2,7 @@
 resolver = "3"
 # Rust plugins must be listed here. Plugins in other languages live under
 # plugins/ too but are not cargo members.
-members = ["crates/herdr-client", "plugins/command-palette", "plugins/git-glance"]
+members = ["crates/herdr-client", "plugins/command-palette", "plugins/git-glance", "plugins/project-runner"]
 
 [workspace.package]
 edition = "2024"
diff --git a/README.md b/README.md
index 5581aaa..d182ad5 100644
--- a/README.md
+++ b/README.md
@@ -121,3 +121,32 @@ no editor opens. A failed commit keeps your message in the prompt.
   never takes the index lock from an agent or editor working in the same repo.
 - Git errors show in the footer. The full text goes to
   `~/.local/state/herdr/plugins/jacob.git-glance/glance.log`.
+
+## Project runner (`plugins/project-runner`)
+
+Popup picker for the `package.json` scripts of the focused pane's project.
+Pick one and it runs in a new tab (or split) as `<pm> run <script>`, so output
+stays visible and `ctrl-c` stops it.
+
+- Walks up from the focused pane's cwd to the repo root; the nearest
+  `package.json` **with scripts** wins, so a pane deep in an nx lib still finds
+  the root's helper scripts.
+- Package manager: `packageManager` field, else lockfile (pnpm, yarn, bun,
+  npm), else npm.
+- Scripts keep their `package.json` order; typing fuzzy-filters names and
+  commands (`serve api` finds `"start:api": "nx serve api"`).
+
+### Keybinding
+
+```toml
+[[keys.command]]
+key = "cmd+r"
+type = "plugin_action"
+command = "jacob.project-runner.open"
+description = "run project script"
+```
+
+### Keys
+
+`↑`/`↓` or `ctrl-p`/`ctrl-n` move · `enter` runs in a new tab · `ctrl-v` split
+right · `ctrl-x` split down · `esc` closes · `ctrl-u` clears.
diff --git a/plugins/project-runner/Cargo.toml b/plugins/project-runner/Cargo.toml
new file mode 100644
index 0000000..196b1c0
--- /dev/null
+++ b/plugins/project-runner/Cargo.toml
@@ -0,0 +1,15 @@
+[package]
+name = "project-runner"
+version = "0.1.0"
+edition.workspace = true
+
+[dependencies]
+herdr-client.workspace = true
+nucleo-matcher.workspace = true
+ratatui.workspace = true
+serde.workspace = true
+serde_json.workspace = true
+unicode-segmentation.workspace = true
+
+[dev-dependencies]
+tempfile.workspace = true
diff --git a/plugins/project-runner/herdr-plugin.toml b/plugins/project-runner/herdr-plugin.toml
new file mode 100644
index 0000000..cf5da88
--- /dev/null
+++ b/plugins/project-runner/herdr-plugin.toml
@@ -0,0 +1,24 @@
+id = "jacob.project-runner"
+name = "Project Runner"
+version = "0.1.0"
+min_herdr_version = "0.9.0"
+description = "Popup picker for package.json scripts; runs the chosen one in a new tab or split"
+platforms = ["macos", "linux"]
+
+[[build]]
+command = ["cargo", "build", "--release", "--target-dir", "target"]
+
+# Keybindings target actions, not panes, so this action opens the popup.
+[[actions]]
+id = "open"
+title = "Run a project script"
+contexts = ["workspace"]
+command = ["sh", "-c", "exec \"$HERDR_BIN_PATH\" plugin pane open --plugin jacob.project-runner --entrypoint runner"]
+
+[[panes]]
+id = "runner"
+title = "Project Runner"
+placement = "popup"
+width = "60%"
+height = "50%"
+command = ["target/release/project-runner", "ui"]
diff --git a/plugins/project-runner/src/app.rs b/plugins/project-runner/src/app.rs
new file mode 100644
index 0000000..29863ae
--- /dev/null
+++ b/plugins/project-runner/src/app.rs
@@ -0,0 +1,183 @@
+//! Runner state and key handling, independent of the terminal.
+
+use ratatui::crossterm::event::{KeyCode, KeyEvent, KeyModifiers};
+
+use crate::launch::Target;
+use crate::matcher::{Ranked, ScriptMatcher};
+use crate::project::Project;
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum Command {
+    Continue,
+    Quit,
+    /// Run `project.scripts[script]` in `target`.
+    Run {
+        script: usize,
+        target: Target,
+    },
+}
+
+pub struct App {
+    pub project: Project,
+    pub query: String,
+    pub ranked: Vec<Ranked>,
+    /// Index into `ranked`.
+    pub selected: usize,
+    pub error: Option<String>,
+    matcher: ScriptMatcher,
+}
+
+impl App {
+    pub fn new(project: Project) -> Self {
+        let mut app = Self {
+            project,
+            query: String::new(),
+            ranked: Vec::new(),
+            selected: 0,
+            error: None,
+            matcher: ScriptMatcher::default(),
+        };
+        app.refilter();
+        app
+    }
+
+    pub fn handle_key(&mut self, key: KeyEvent) -> Command {
+        let ctrl = key.modifiers.contains(KeyModifiers::CONTROL);
+        match key.code {
+            KeyCode::Esc => return Command::Quit,
+            KeyCode::Char('c') if ctrl => return Command::Quit,
+            KeyCode::Enter => return self.run(Target::Tab),
+            KeyCode::Char('v') if ctrl => return self.run(Target::SplitRight),
+            KeyCode::Char('x') if ctrl => return self.run(Target::SplitDown),
+            KeyCode::Up => self.move_selection(-1),
+            KeyCode::Down => self.move_selection(1),
+            KeyCode::Char('p') if ctrl => self.move_selection(-1),
+            KeyCode::Char('n') if ctrl => self.move_selection(1),
+            KeyCode::Char('u') if ctrl => self.edit(String::clear),
+            KeyCode::Backspace => self.edit(|q| {
+                q.pop();
+            }),
+            KeyCode::Char(c) if !ctrl => self.edit(|q| q.push(c)),
+            _ => {}
+        }
+        Command::Continue
+    }
+
+    pub fn fail(&mut self, message: String) {
+        self.error = Some(message);
+    }
+
+    fn run(&self, target: Target) -> Command {
+        match self.ranked.get(self.selected) {
+            Some(ranked) => Command::Run { script: ranked.index, target },
+            None => Command::Continue,
+        }
+    }
+
+    fn edit(&mut self, change: impl FnOnce(&mut String)) {
+        change(&mut self.query);
+        self.error = None;
+        self.refilter();
+    }
+
+    fn refilter(&mut self) {
+        self.ranked = self.matcher.rank(&self.query, &self.project.scripts);
+        self.selected = 0;
+    }
+
+    /// Wraps around at either end.
+    fn move_selection(&mut self, delta: isize) {
+        let len = self.ranked.len();
+        if len > 0 {
+            self.selected = (self.selected as isize + delta).rem_euclid(len as isize) as usize;
+        }
+    }
+}
+
+#[cfg(test)]
+pub(crate) mod tests {
+    use super::*;
+    use crate::project::{Manager, Script};
+    use std::path::PathBuf;
+
+    pub fn project() -> Project {
+        let scripts = [("start:web", "nx serve web"), ("start:api", "nx serve api"), ("lint", "nx run-many -t lint")];
+        Project {
+            dir: PathBuf::from("/repo"),
+            name: "mono".into(),
+            manager: Manager::Pnpm,
+            scripts: scripts.iter().map(|(n, c)| Script { name: n.to_string(), command: c.to_string() }).collect(),
+        }
+    }
+
+    fn key(code: KeyCode) -> KeyEvent {
+        KeyEvent::new(code, KeyModifiers::NONE)
+    }
+
+    fn ctrl(c: char) -> KeyEvent {
+        KeyEvent::new(KeyCode::Char(c), KeyModifiers::CONTROL)
+    }
+
+    fn type_str(app: &mut App, text: &str) {
+        for c in text.chars() {
+            app.handle_key(key(KeyCode::Char(c)));
+        }
+    }
+
+    #[test]
+    fn enter_runs_the_selected_script_in_a_tab() {
+        let mut app = App::new(project());
+        assert_eq!(app.handle_key(key(KeyCode::Enter)), Command::Run { script: 0, target: Target::Tab });
+    }
+
+    #[test]
+    fn ctrl_v_and_ctrl_x_run_in_splits() {
+        let mut app = App::new(project());
+        app.handle_key(key(KeyCode::Down));
+        assert_eq!(app.handle_key(ctrl('v')), Command::Run { script: 1, target: Target::SplitRight });
+        assert_eq!(app.handle_key(ctrl('x')), Command::Run { script: 1, target: Target::SplitDown });
+    }
+
+    #[test]
+    fn typing_filters_and_resets_selection() {
+        let mut app = App::new(project());
+        app.handle_key(key(KeyCode::Down));
+        type_str(&mut app, "lint");
+        assert_eq!(app.selected, 0);
+        assert_eq!(app.handle_key(key(KeyCode::Enter)), Command::Run { script: 2, target: Target::Tab });
+    }
+
+    #[test]
+    fn selection_wraps() {
+        let mut app = App::new(project());
+        app.handle_key(key(KeyCode::Up));
+        assert_eq!(app.selected, 2);
+        app.handle_key(ctrl('n'));
+        assert_eq!(app.selected, 0);
+    }
+
+    #[test]
+    fn no_matches_makes_enter_a_no_op() {
+        let mut app = App::new(project());
+        type_str(&mut app, "zzzz");
+        assert_eq!(app.handle_key(key(KeyCode::Enter)), Command::Continue);
+    }
+
+    #[test]
+    fn editing_clears_the_error_and_ctrl_u_clears_the_query() {
+        let mut app = App::new(project());
+        type_str(&mut app, "ap");
+        app.fail("boom".into());
+        app.handle_key(key(KeyCode::Backspace));
+        assert_eq!((app.query.as_str(), app.error.as_deref()), ("a", None));
+        app.handle_key(ctrl('u'));
+        assert_eq!(app.ranked.len(), 3);
+    }
+
+    #[test]
+    fn esc_and_ctrl_c_quit() {
+        let mut app = App::new(project());
+        assert_eq!(app.handle_key(key(KeyCode::Esc)), Command::Quit);
+        assert_eq!(app.handle_key(ctrl('c')), Command::Quit);
+    }
+}
diff --git a/plugins/project-runner/src/launch.rs b/plugins/project-runner/src/launch.rs
new file mode 100644
index 0000000..70affa7
--- /dev/null
+++ b/plugins/project-runner/src/launch.rs
@@ -0,0 +1,126 @@
+//! Opens a pane for the chosen script and types its run line into it, so the
+//! script runs in a normal shell: output stays visible, ctrl-c stops it, and
+//! the shell history has the command for re-runs.
+
+use std::path::Path;
+
+use herdr_client::{Api, PluginContext};
+use serde_json::{Value, json};
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum Target {
+    Tab,
+    SplitRight,
+    SplitDown,
+}
+
+/// `label` names the new tab; `line` is what the shell runs.
+pub fn launch(
+    api: &dyn Api,
+    ctx: &PluginContext,
+    target: Target,
+    dir: &Path,
+    label: &str,
+    line: &str,
+) -> Result<(), String> {
+    let call = |method: &str, params: Value| api.request(method, params).map_err(|e| e.to_string());
+    let cwd = dir.to_string_lossy();
+    let pane_id = match target {
+        Target::Tab => {
+            let workspace = need(&ctx.workspace_id, "workspace")?;
+            let result =
+                call("tab.create", json!({"workspace_id": workspace, "cwd": cwd, "label": label, "focus": true}))?;
+            pane_id(&result, "/root_pane/pane_id", "tab.create")?
+        }
+        Target::SplitRight | Target::SplitDown => {
+            let direction = if target == Target::SplitRight { "right" } else { "down" };
+            let pane = need(&ctx.focused_pane_id, "pane")?;
+            let result =
+                call("pane.split", json!({"target_pane_id": pane, "direction": direction, "cwd": cwd, "focus": true}))?;
+            pane_id(&result, "/pane/pane_id", "pane.split")?
+        }
+    };
+    call("pane.send_input", json!({"pane_id": pane_id, "text": line, "keys": ["Enter"]})).map(drop)
+}
+
+fn need<'a>(value: &'a Option<String>, what: &str) -> Result<&'a str, String> {
+    value.as_deref().ok_or_else(|| format!("no focused {what}"))
+}
+
+fn pane_id(result: &Value, pointer: &str, method: &str) -> Result<String, String> {
+    result
+        .pointer(pointer)
+        .and_then(Value::as_str)
+        .map(str::to_string)
+        .ok_or_else(|| format!("{method}: response has no {pointer}"))
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::testing::FakeApi;
+
+    fn ctx() -> PluginContext {
+        PluginContext { workspace_id: Some("w1".into()), focused_pane_id: Some("w1:p1".into()), ..Default::default() }
+    }
+
+    fn send(pane: &str) -> (String, Value) {
+        ("pane.send_input".into(), json!({"pane_id": pane, "text": "pnpm run dev", "keys": ["Enter"]}))
+    }
+
+    #[test]
+    fn tab_target_creates_a_labelled_tab_and_types_the_line() {
+        let api = FakeApi::new()
+            .ok("tab.create", json!({"tab": {"tab_id": "w1:t4"}, "root_pane": {"pane_id": "w1:p9"}}))
+            .ok("pane.send_input", json!({}));
+        launch(&api, &ctx(), Target::Tab, Path::new("/repo"), "dev", "pnpm run dev").unwrap();
+        assert_eq!(
+            api.calls(),
+            [
+                ("tab.create".into(), json!({"workspace_id": "w1", "cwd": "/repo", "label": "dev", "focus": true})),
+                send("w1:p9"),
+            ]
+        );
+    }
+
+    #[test]
+    fn split_targets_split_the_focused_pane() {
+        for (target, direction) in [(Target::SplitRight, "right"), (Target::SplitDown, "down")] {
+            let api =
+                FakeApi::new().ok("pane.split", json!({"pane": {"pane_id": "w1:p2"}})).ok("pane.send_input", json!({}));
+            launch(&api, &ctx(), target, Path::new("/repo"), "dev", "pnpm run dev").unwrap();
+            assert_eq!(
+                api.calls(),
+                [
+                    (
+                        "pane.split".into(),
+                        json!({"target_pane_id": "w1:p1", "direction": direction, "cwd": "/repo", "focus": true})
+                    ),
+                    send("w1:p2"),
+                ]
+            );
+        }
+    }
+
+    #[test]
+    fn missing_context_skips_the_socket() {
+        let api = FakeApi::new();
+        let err = launch(&api, &PluginContext::default(), Target::Tab, Path::new("/r"), "a", "b").unwrap_err();
+        assert_eq!(err, "no focused workspace");
+        assert!(api.calls().is_empty());
+    }
+
+    #[test]
+    fn unexpected_response_shape_is_an_error() {
+        let api = FakeApi::new().ok("pane.split", json!({}));
+        let err = launch(&api, &ctx(), Target::SplitDown, Path::new("/r"), "a", "b").unwrap_err();
+        assert_eq!(err, "pane.split: response has no /pane/pane_id");
+    }
+
+    #[test]
+    fn api_errors_are_returned_as_text() {
+        let api = FakeApi::new().err("tab.create", "workspace_not_found", "gone");
+        let err = launch(&api, &ctx(), Target::Tab, Path::new("/r"), "a", "b").unwrap_err();
+        assert_eq!(err, "tab.create: gone (workspace_not_found)");
+    }
+}
diff --git a/plugins/project-runner/src/log.rs b/plugins/project-runner/src/log.rs
new file mode 100644
index 0000000..34685f4
--- /dev/null
+++ b/plugins/project-runner/src/log.rs
@@ -0,0 +1,34 @@
+//! Diagnostics go to a file: the runner owns the terminal while it runs.
+
+use std::io::Write;
+use std::path::Path;
+use std::time::{SystemTime, UNIX_EPOCH};
+
+/// Best effort: logging must never break the runner.
+pub fn append(dir: &Path, message: &str) {
+    let write = || -> std::io::Result<()> {
+        std::fs::create_dir_all(dir)?;
+        let mut file = std::fs::OpenOptions::new().create(true).append(true).open(dir.join("runner.log"))?;
+        let now = SystemTime::now().duration_since(UNIX_EPOCH).map_or(0, |d| d.as_secs());
+        writeln!(file, "{now} {message}")
+    };
+    let _ = write();
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn appends_timestamped_lines_creating_the_directory() {
+        let dir = tempfile::tempdir().unwrap();
+        let state = dir.path().join("state");
+        append(&state, "first");
+        append(&state, "second");
+        let log = std::fs::read_to_string(state.join("runner.log")).unwrap();
+        let lines: Vec<_> = log.lines().collect();
+        assert_eq!(lines.len(), 2);
+        assert!(lines[0].ends_with(" first"));
+        assert!(lines[1].ends_with(" second"));
+    }
+}
diff --git a/plugins/project-runner/src/main.rs b/plugins/project-runner/src/main.rs
new file mode 100644
index 0000000..3adcc95
--- /dev/null
+++ b/plugins/project-runner/src/main.rs
@@ -0,0 +1,130 @@
+mod app;
+mod launch;
+mod log;
+mod matcher;
+mod project;
+mod render;
+#[cfg(test)]
+mod testing;
+
+use std::path::{Path, PathBuf};
+use std::process::ExitCode;
+
+use herdr_client::{Client, PluginContext};
+use ratatui::DefaultTerminal;
+use ratatui::crossterm::event::{self, Event, KeyEventKind};
+use ratatui::text::{Line, Text};
+use ratatui::widgets::{Paragraph, Wrap};
+
+use app::{App, Command};
+use project::Project;
+
+fn main() -> ExitCode {
+    match std::env::args().nth(1).as_deref() {
+        Some("ui") => match run_ui() {
+            Ok(()) => ExitCode::SUCCESS,
+            Err(err) => {
+                eprintln!("project-runner: {err}");
+                ExitCode::FAILURE
+            }
+        },
+        _ => {
+            eprintln!("usage: project-runner ui");
+            ExitCode::from(2)
+        }
+    }
+}
+
+/// The focused pane's directory is the one the user means; the workspace
+/// root and the process cwd are fallbacks for panes that don't report one.
+fn target_dir(ctx: &PluginContext) -> PathBuf {
+    ctx.focused_pane_cwd
+        .as_deref()
+        .or(ctx.workspace_cwd.as_deref())
+        .map(PathBuf::from)
+        .or_else(|| std::env::current_dir().ok())
+        .unwrap_or_else(|| PathBuf::from("."))
+}
+
+fn run_ui() -> std::io::Result<()> {
+    let ctx = PluginContext::from_env();
+    let state_dir = std::env::var_os("HERDR_PLUGIN_STATE_DIR")
+        .map(PathBuf::from)
+        .unwrap_or_else(|| std::env::temp_dir().join("herdr-project-runner"));
+    let discovered = Project::discover(&target_dir(&ctx));
+    let mut terminal = ratatui::init();
+    let result = match discovered {
+        Ok(project) => event_loop(&mut terminal, &mut App::new(project), &ctx, &state_dir),
+        Err(err) => {
+            log::append(&state_dir, &err);
+            message_screen(&mut terminal, &err)
+        }
+    };
+    ratatui::restore();
+    result
+}
+
+fn event_loop(
+    terminal: &mut DefaultTerminal,
+    app: &mut App,
+    ctx: &PluginContext,
+    state_dir: &Path,
+) -> std::io::Result<()> {
+    loop {
+        terminal.draw(|frame| render::render(frame, app))?;
+        let Event::Key(key) = event::read()? else { continue };
+        if key.kind != KeyEventKind::Press {
+            continue;
+        }
+        match app.handle_key(key) {
+            Command::Continue => {}
+            Command::Quit => return Ok(()),
+            Command::Run { script, target } => {
+                let script = &app.project.scripts[script];
+                let line = app.project.manager.run_line(&script.name);
+                let result = Client::from_env()
+                    .map_err(|e| e.to_string())
+                    .and_then(|client| launch::launch(&client, ctx, target, &app.project.dir, &script.name, &line));
+                match result {
+                    Ok(()) => return Ok(()),
+                    Err(err) => {
+                        log::append(state_dir, &format!("{line}: {err}"));
+                        app.fail(err);
+                    }
+                }
+            }
+        }
+    }
+}
+
+/// Shown when there's no package.json to run from; any key closes the popup.
+fn message_screen(terminal: &mut DefaultTerminal, message: &str) -> std::io::Result<()> {
+    loop {
+        terminal.draw(|frame| {
+            let text = Text::from(vec![Line::from(message), Line::from(""), Line::from("press any key")]);
+            frame.render_widget(Paragraph::new(text).wrap(Wrap { trim: false }), frame.area());
+        })?;
+        if let Event::Key(key) = event::read()?
+            && key.kind == KeyEventKind::Press
+        {
+            return Ok(());
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn target_dir_prefers_the_focused_pane() {
+        let ctx = PluginContext {
+            focused_pane_cwd: Some("/pane".into()),
+            workspace_cwd: Some("/ws".into()),
+            ..Default::default()
+        };
+        assert_eq!(target_dir(&ctx), PathBuf::from("/pane"));
+        let ctx = PluginContext { workspace_cwd: Some("/ws".into()), ..Default::default() };
+        assert_eq!(target_dir(&ctx), PathBuf::from("/ws"));
+    }
+}
diff --git a/plugins/project-runner/src/matcher.rs b/plugins/project-runner/src/matcher.rs
new file mode 100644
index 0000000..97fec6e
--- /dev/null
+++ b/plugins/project-runner/src/matcher.rs
@@ -0,0 +1,105 @@
+//! Fuzzy filtering over script names and commands.
+
+use nucleo_matcher::pattern::{CaseMatching, Normalization, Pattern};
+use nucleo_matcher::{Config, Matcher, Utf32Str};
+use unicode_segmentation::UnicodeSegmentation;
+
+use crate::project::Script;
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct Ranked {
+    pub index: usize,
+    /// Grapheme indices into the script name to highlight.
+    pub highlights: Vec<usize>,
+}
+
+/// Owns the nucleo matcher and scratch buffers so each keystroke reuses them
+/// instead of reallocating.
+pub struct ScriptMatcher {
+    matcher: Matcher,
+    buf: Vec<char>,
+    indices: Vec<u32>,
+    haystack: String,
+}
+
+impl Default for ScriptMatcher {
+    fn default() -> Self {
+        Self { matcher: Matcher::new(Config::DEFAULT), buf: Vec::new(), indices: Vec::new(), haystack: String::new() }
+    }
+}
+
+impl ScriptMatcher {
+    /// An empty query keeps package.json order. Otherwise the best matches
+    /// come first and ties keep file order. Commands are searched too, so
+    /// `serve api` finds `"start:api": "nx serve api"`.
+    pub fn rank(&mut self, query: &str, scripts: &[Script]) -> Vec<Ranked> {
+        if query.trim().is_empty() {
+            return (0..scripts.len()).map(|index| Ranked { index, highlights: Vec::new() }).collect();
+        }
+        let pattern = Pattern::parse(query, CaseMatching::Smart, Normalization::Smart);
+        let mut scored: Vec<(u32, Ranked)> = scripts
+            .iter()
+            .enumerate()
+            .filter_map(|(index, script)| {
+                self.haystack.clear();
+                self.haystack.push_str(&script.name);
+                self.haystack.push(' ');
+                self.haystack.push_str(&script.command);
+                self.indices.clear();
+                let score = pattern.indices(
+                    Utf32Str::new(&self.haystack, &mut self.buf),
+                    &mut self.matcher,
+                    &mut self.indices,
+                )?;
+                let name_len = script.name.graphemes(true).count();
+                self.indices.sort_unstable();
+                self.indices.dedup();
+                let highlights = self.indices.iter().map(|&i| i as usize).take_while(|&i| i < name_len).collect();
+                Some((score, Ranked { index, highlights }))
+            })
+            .collect();
+        scored.sort_by(|(a, ra), (b, rb)| b.cmp(a).then(ra.index.cmp(&rb.index)));
+        scored.into_iter().map(|(_, ranked)| ranked).collect()
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn scripts(pairs: &[(&str, &str)]) -> Vec<Script> {
+        pairs.iter().map(|(n, c)| Script { name: n.to_string(), command: c.to_string() }).collect()
+    }
+
+    fn order(ranked: &[Ranked]) -> Vec<usize> {
+        ranked.iter().map(|r| r.index).collect()
+    }
+
+    #[test]
+    fn empty_query_keeps_file_order() {
+        let list = scripts(&[("b", "x"), ("a", "y")]);
+        assert_eq!(order(&ScriptMatcher::default().rank("  ", &list)), [0, 1]);
+    }
+
+    #[test]
+    fn filters_and_ranks_best_first() {
+        let list = scripts(&[("lint", "nx lint"), ("start:web", "nx serve web"), ("start:api", "nx serve api")]);
+        let mut matcher = ScriptMatcher::default();
+        assert_eq!(order(&matcher.rank("api", &list)), [2]);
+        assert_eq!(order(&matcher.rank("start", &list)), [1, 2]);
+    }
+
+    #[test]
+    fn command_matches_count_but_do_not_highlight_the_name() {
+        let list = scripts(&[("dev", "nx serve web")]);
+        let ranked = ScriptMatcher::default().rank("serve", &list);
+        assert_eq!(order(&ranked), [0]);
+        assert!(ranked[0].highlights.is_empty());
+    }
+
+    #[test]
+    fn name_matches_are_highlighted() {
+        let list = scripts(&[("start:api", "x")]);
+        assert_eq!(ScriptMatcher::default().rank("api", &list)[0].highlights, [6, 7, 8]);
+    }
+}
diff --git a/plugins/project-runner/src/project.rs b/plugins/project-runner/src/project.rs
new file mode 100644
index 0000000..22c458b
--- /dev/null
+++ b/plugins/project-runner/src/project.rs
@@ -0,0 +1,276 @@
+//! Finds the package.json that owns a directory, reads its scripts in file
+//! order, and works out which package manager runs them.
+
+use std::fmt;
+use std::path::{Path, PathBuf};
+
+use serde::de::{Deserializer, MapAccess, Visitor};
+use serde::{Deserialize, de::IgnoredAny};
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct Script {
+    pub name: String,
+    pub command: String,
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum Manager {
+    Npm,
+    Pnpm,
+    Yarn,
+    Bun,
+}
+
+impl Manager {
+    pub fn as_str(self) -> &'static str {
+        match self {
+            Manager::Npm => "npm",
+            Manager::Pnpm => "pnpm",
+            Manager::Yarn => "yarn",
+            Manager::Bun => "bun",
+        }
+    }
+
+    /// The shell line that runs `script`, e.g. `pnpm run 'build:prod'`.
+    pub fn run_line(self, script: &str) -> String {
+        format!("{} run {}", self.as_str(), shell_quote(script))
+    }
+
+    /// `packageManager` is corepack's `name@version` field.
+    fn from_package_manager(field: &str) -> Option<Self> {
+        match field.split('@').next()? {
+            "npm" => Some(Manager::Npm),
+            "pnpm" => Some(Manager::Pnpm),
+            "yarn" => Some(Manager::Yarn),
+            "bun" => Some(Manager::Bun),
+            _ => None,
+        }
+    }
+
+    fn from_lockfile(dir: &Path) -> Option<Self> {
+        const LOCKFILES: [(&str, Manager); 5] = [
+            ("pnpm-lock.yaml", Manager::Pnpm),
+            ("yarn.lock", Manager::Yarn),
+            ("bun.lock", Manager::Bun),
+            ("bun.lockb", Manager::Bun),
+            ("package-lock.json", Manager::Npm),
+        ];
+        LOCKFILES.iter().find(|(file, _)| dir.join(file).is_file()).map(|&(_, manager)| manager)
+    }
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct Project {
+    pub dir: PathBuf,
+    pub name: String,
+    pub manager: Manager,
+    pub scripts: Vec<Script>,
+}
+
+impl Project {
+    /// Walks up from `start` to the repository root (a directory holding
+    /// `.git`) or the filesystem root. The nearest package.json with scripts
+    /// wins, so a pane inside a script-less library of an nx monorepo still
+    /// finds the root's helper scripts.
+    pub fn discover(start: &Path) -> Result<Self, String> {
+        let search = search_path(start);
+        let mut fallback = None;
+        for dir in &search {
+            let path = dir.join("package.json");
+            let Ok(raw) = std::fs::read_to_string(&path) else { continue };
+            let manifest: Manifest = serde_json::from_str(&raw).map_err(|err| format!("{}: {err}", path.display()))?;
+            if !manifest.scripts.0.is_empty() {
+                return Ok(Self::new(dir, manifest, &search));
+            }
+            fallback.get_or_insert((*dir, manifest));
+        }
+        match fallback {
+            Some((dir, manifest)) => Ok(Self::new(dir, manifest, &search)),
+            None => Err(format!("no package.json in {} or its parents", start.display())),
+        }
+    }
+
+    fn new(dir: &Path, manifest: Manifest, search: &[&Path]) -> Self {
+        let manager = manifest
+            .package_manager
+            .as_deref()
+            .and_then(Manager::from_package_manager)
+            .or_else(|| search.iter().skip_while(|d| **d != dir).find_map(|d| Manager::from_lockfile(d)))
+            .unwrap_or(Manager::Npm);
+        let name = manifest
+            .name
+            .or_else(|| dir.file_name().map(|n| n.to_string_lossy().into_owned()))
+            .unwrap_or_else(|| dir.display().to_string());
+        Self { dir: dir.to_path_buf(), name, manager, scripts: manifest.scripts.0 }
+    }
+}
+
+/// `start` and its ancestors, ending at the first one that holds `.git`.
+fn search_path(start: &Path) -> Vec<&Path> {
+    let mut dirs = Vec::new();
+    for dir in start.ancestors() {
+        dirs.push(dir);
+        if dir.join(".git").exists() {
+            break;
+        }
+    }
+    dirs
+}
+
+/// Script names are usually plain (`build`, `start:api`); anything else is
+/// single-quoted so the shell passes it through untouched.
+fn shell_quote(value: &str) -> String {
+    let plain = |c: char| c.is_ascii_alphanumeric() || "-_:./@+=,%".contains(c);
+    if !value.is_empty() && value.chars().all(plain) {
+        value.to_string()
+    } else {
+        format!("'{}'", value.replace('\'', r"'\''"))
+    }
+}
+
+#[derive(Deserialize)]
+struct Manifest {
+    name: Option<String>,
+    #[serde(rename = "packageManager")]
+    package_manager: Option<String>,
+    #[serde(default)]
+    scripts: Scripts,
+}
+
+/// Scripts in file order: authors group related scripts, and a map would sort
+/// them. Non-string values are skipped rather than failing the whole file.
+#[derive(Default)]
+struct Scripts(Vec<Script>);
+
+impl<'de> Deserialize<'de> for Scripts {
+    fn deserialize<D: Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error> {
+        struct ScriptsVisitor;
+
+        impl<'de> Visitor<'de> for ScriptsVisitor {
+            type Value = Scripts;
+
+            fn expecting(&self, f: &mut fmt::Formatter) -> fmt::Result {
+                f.write_str("an object of script names to commands")
+            }
+
+            fn visit_map<A: MapAccess<'de>>(self, mut map: A) -> Result<Scripts, A::Error> {
+                let mut scripts = Vec::with_capacity(map.size_hint().unwrap_or(0));
+                while let Some(name) = map.next_key::<String>()? {
+                    match map.next_value::<StringOrOther>()? {
+                        StringOrOther::String(command) => scripts.push(Script { name, command }),
+                        StringOrOther::Other(IgnoredAny) => {}
+                    }
+                }
+                Ok(Scripts(scripts))
+            }
+        }
+
+        deserializer.deserialize_map(ScriptsVisitor)
+    }
+}
+
+#[derive(Deserialize)]
+#[serde(untagged)]
+enum StringOrOther {
+    String(String),
+    Other(IgnoredAny),
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn write(dir: &Path, file: &str, content: &str) {
+        std::fs::create_dir_all(dir).unwrap();
+        std::fs::write(dir.join(file), content).unwrap();
+    }
+
+    fn names(project: &Project) -> Vec<&str> {
+        project.scripts.iter().map(|s| s.name.as_str()).collect()
+    }
+
+    #[test]
+    fn scripts_keep_file_order_and_skip_non_strings() {
+        let dir = tempfile::tempdir().unwrap();
+        write(
+            dir.path(),
+            "package.json",
+            r#"{"name":"mono","scripts":{"start:api":"nx serve api","build":"nx run-many -t build","bad":1,"lint":"nx lint"}}"#,
+        );
+        let project = Project::discover(dir.path()).unwrap();
+        assert_eq!(project.name, "mono");
+        assert_eq!(names(&project), ["start:api", "build", "lint"]);
+        assert_eq!(project.scripts[0].command, "nx serve api");
+        assert_eq!(project.manager, Manager::Npm);
+    }
+
+    #[test]
+    fn nearest_package_with_scripts_wins_over_empty_one() {
+        let dir = tempfile::tempdir().unwrap();
+        std::fs::create_dir(dir.path().join(".git")).unwrap();
+        write(dir.path(), "package.json", r#"{"name":"root","scripts":{"dev":"nx serve web"}}"#);
+        write(dir.path(), "pnpm-lock.yaml", "");
+        let lib = dir.path().join("libs/ui");
+        write(&lib, "package.json", r#"{"name":"@mono/ui"}"#);
+        let project = Project::discover(&lib).unwrap();
+        assert_eq!(project.name, "root");
+        assert_eq!(project.dir, dir.path());
+        assert_eq!(project.manager, Manager::Pnpm);
+    }
+
+    #[test]
+    fn nested_package_with_scripts_wins_and_uses_root_lockfile() {
+        let dir = tempfile::tempdir().unwrap();
+        write(dir.path(), "yarn.lock", "");
+        write(dir.path(), "package.json", r#"{"scripts":{"dev":"a"}}"#);
+        let app = dir.path().join("apps/web");
+        write(&app, "package.json", r#"{"scripts":{"serve":"b"}}"#);
+        let project = Project::discover(&app).unwrap();
+        assert_eq!(names(&project), ["serve"]);
+        assert_eq!(project.name, "web");
+        assert_eq!(project.manager, Manager::Yarn);
+    }
+
+    #[test]
+    fn package_manager_field_beats_lockfile() {
+        let dir = tempfile::tempdir().unwrap();
+        write(dir.path(), "package-lock.json", "{}");
+        write(dir.path(), "package.json", r#"{"packageManager":"bun@1.1.0","scripts":{"x":"y"}}"#);
+        assert_eq!(Project::discover(dir.path()).unwrap().manager, Manager::Bun);
+    }
+
+    #[test]
+    fn search_stops_at_the_repo_root() {
+        let dir = tempfile::tempdir().unwrap();
+        write(dir.path(), "package.json", r#"{"scripts":{"outside":"x"}}"#);
+        let repo = dir.path().join("repo");
+        std::fs::create_dir_all(repo.join(".git")).unwrap();
+        let err = Project::discover(&repo).unwrap_err();
+        assert!(err.starts_with("no package.json in"), "{err}");
+    }
+
+    #[test]
+    fn only_empty_package_is_returned_without_scripts() {
+        let dir = tempfile::tempdir().unwrap();
+        std::fs::create_dir(dir.path().join(".git")).unwrap();
+        write(dir.path(), "package.json", r#"{"name":"bare"}"#);
+        let project = Project::discover(dir.path()).unwrap();
+        assert_eq!(project.name, "bare");
+        assert!(project.scripts.is_empty());
+    }
+
+    #[test]
+    fn invalid_json_names_the_file() {
+        let dir = tempfile::tempdir().unwrap();
+        write(dir.path(), "package.json", "{nope");
+        let err = Project::discover(dir.path()).unwrap_err();
+        assert!(err.contains("package.json"), "{err}");
+    }
+
+    #[test]
+    fn run_line_quotes_only_when_needed() {
+        assert_eq!(Manager::Pnpm.run_line("start:api"), "pnpm run start:api");
+        assert_eq!(Manager::Npm.run_line("build prod"), "npm run 'build prod'");
+        assert_eq!(Manager::Yarn.run_line("it's"), r"yarn run 'it'\''s'");
+    }
+}
diff --git a/plugins/project-runner/src/render.rs b/plugins/project-runner/src/render.rs
new file mode 100644
index 0000000..344bbbe
--- /dev/null
+++ b/plugins/project-runner/src/render.rs
@@ -0,0 +1,133 @@
+//! Draws the runner. Uses the terminal's own colors plus ANSI accents so it
+//! follows the user's herdr/terminal theme.
+
+use ratatui::Frame;
+use ratatui::layout::{Constraint, Layout, Rect};
+use ratatui::style::{Color, Style, Stylize};
+use ratatui::text::{Line, Span};
+use unicode_segmentation::UnicodeSegmentation;
+
+use crate::app::App;
+
+/// Long script names don't push every command off screen.
+const MAX_NAME_WIDTH: usize = 28;
+
+pub fn render(frame: &mut Frame, app: &App) {
+    let [input, rule, list, footer] =
+        Layout::vertical([Constraint::Length(1), Constraint::Length(1), Constraint::Min(0), Constraint::Length(1)])
+            .areas(frame.area());
+    render_input(frame, app, input);
+    frame.render_widget(Line::from("─".repeat(usize::from(rule.width))).dim(), rule);
+    render_list(frame, app, list);
+    render_footer(frame, app, footer);
+}
+
+fn render_input(frame: &mut Frame, app: &App, area: Rect) {
+    let line = Line::from(vec![Span::raw("❯ ").cyan().bold(), Span::raw(app.query.as_str())]);
+    let width = u16::try_from(line.width()).unwrap_or(u16::MAX);
+    frame.render_widget(line, area);
+    if area.width > 0 && area.height > 0 {
+        let x = area.x.saturating_add(width).min(area.right().saturating_sub(1));
+        frame.set_cursor_position((x, area.y));
+    }
+}
+
+fn render_list(frame: &mut Frame, app: &App, area: Rect) {
+    if area.height == 0 {
+        return;
+    }
+    let scripts = &app.project.scripts;
+    if app.ranked.is_empty() {
+        let message = if scripts.is_empty() { "  no scripts in package.json" } else { "  no matches" };
+        frame.render_widget(Line::from(message).dim(), area);
+        return;
+    }
+    let name_width = scripts.iter().map(|s| s.name.graphemes(true).count()).max().unwrap_or(0).min(MAX_NAME_WIDTH);
+    let height = usize::from(area.height);
+    let offset = app.selected.saturating_sub(height - 1);
+    for (row, (position, ranked)) in app.ranked.iter().enumerate().skip(offset).take(height).enumerate() {
+        let selected = position == app.selected;
+        let script = &scripts[ranked.index];
+        let mut spans = vec![Span::raw(if selected { "▸ " } else { "  " })];
+        let graphemes = script.name.graphemes(true).count();
+        spans.extend(script.name.graphemes(true).enumerate().map(|(i, g)| {
+            let span = Span::raw(g);
+            if ranked.highlights.contains(&i) { span.yellow().bold() } else { span }
+        }));
+        spans.push(Span::raw(" ".repeat(name_width.saturating_sub(graphemes) + 2)));
+        spans.push(Span::raw(script.command.as_str()).dim());
+        let mut line = Line::from(spans);
+        if selected {
+            line = line.style(Style::new().bg(Color::DarkGray));
+        }
+        frame.render_widget(line, Rect { y: area.y + row as u16, height: 1, ..area });
+    }
+}
+
+fn render_footer(frame: &mut Frame, app: &App, area: Rect) {
+    let hints = Line::from("⏎ tab  ^v split right  ^x split down  esc close").dim();
+    let right = match &app.error {
+        Some(message) => Line::from(message.as_str()).red(),
+        None => Line::from(format!("{} · {}", app.project.name, app.project.manager.as_str())).dim(),
+    };
+    let hints_width = u16::try_from(hints.width() + 2).unwrap_or(u16::MAX);
+    let [left_area, right_area] = Layout::horizontal([Constraint::Length(hints_width), Constraint::Min(0)]).areas(area);
+    frame.render_widget(hints, left_area);
+    frame.render_widget(right.right_aligned(), right_area);
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::app::tests::project;
+    use ratatui::{Terminal, backend::TestBackend};
+
+    fn draw(app: &App, width: u16, height: u16) -> Vec<String> {
+        let mut terminal = Terminal::new(TestBackend::new(width, height)).unwrap();
+        terminal.draw(|frame| render(frame, app)).unwrap();
+        let buffer = terminal.backend().buffer();
+        (0..buffer.area.height)
+            .map(|y| {
+                let line: String = (0..buffer.area.width).map(|x| buffer[(x, y)].symbol()).collect();
+                line.trim_end().to_string()
+            })
+            .collect()
+    }
+
+    #[test]
+    fn lists_scripts_with_aligned_commands() {
+        let lines = draw(&App::new(project()), 80, 7);
+        assert_eq!(lines[0], "❯");
+        assert!(lines[1].starts_with("────"), "{:?}", lines[1]);
+        assert_eq!(lines[2], "▸ start:web  nx serve web");
+        assert_eq!(lines[3], "  start:api  nx serve api");
+        assert_eq!(lines[4], "  lint       nx run-many -t lint");
+        assert!(lines[6].starts_with("⏎ tab  ^v split right"), "{:?}", lines[6]);
+        assert!(lines[6].ends_with("mono · pnpm"), "{:?}", lines[6]);
+    }
+
+    #[test]
+    fn empty_states() {
+        let mut app = App::new(project());
+        app.query = "zzz".into();
+        app.ranked.clear();
+        assert_eq!(draw(&app, 80, 7)[2], "  no matches");
+        app.project.scripts.clear();
+        assert_eq!(draw(&app, 80, 7)[2], "  no scripts in package.json");
+    }
+
+    #[test]
+    fn error_replaces_project_label() {
+        let mut app = App::new(project());
+        app.fail("tab.create: gone (workspace_not_found)".into());
+        assert!(draw(&app, 100, 7)[6].ends_with("tab.create: gone (workspace_not_found)"));
+    }
+
+    #[test]
+    fn selection_scrolls_into_view() {
+        let mut app = App::new(project());
+        app.selected = 2;
+        let lines = draw(&app, 80, 5);
+        assert_eq!(lines[3], "▸ lint       nx run-many -t lint");
+    }
+}
diff --git a/plugins/project-runner/src/testing.rs b/plugins/project-runner/src/testing.rs
new file mode 100644
index 0000000..d406ee5
--- /dev/null
+++ b/plugins/project-runner/src/testing.rs
@@ -0,0 +1,50 @@
+//! Test double for the herdr socket API.
+
+use std::collections::HashMap;
+use std::sync::Mutex;
+
+use herdr_client::{Api, Error};
+use serde_json::Value;
+
+#[derive(Default)]
+pub struct FakeApi {
+    responses: HashMap<String, Result<Value, (String, String)>>,
+    calls: Mutex<Vec<(String, Value)>>,
+}
+
+impl FakeApi {
+    pub fn new() -> Self {
+        Self::default()
+    }
+
+    pub fn ok(mut self, method: &str, result: Value) -> Self {
+        self.responses.insert(method.to_string(), Ok(result));
+        self
+    }
+
+    pub fn err(mut self, method: &str, code: &str, message: &str) -> Self {
+        self.responses.insert(method.to_string(), Err((code.to_string(), message.to_string())));
+        self
+    }
+
+    pub fn calls(&self) -> Vec<(String, Value)> {
+        self.calls.lock().unwrap().clone()
+    }
+}
+
+impl Api for FakeApi {
+    fn request(&self, method: &str, params: Value) -> Result<Value, Error> {
+        self.calls.lock().unwrap().push((method.to_string(), params));
+        match self.responses.get(method) {
+            Some(Ok(value)) => Ok(value.clone()),
+            Some(Err((code, message))) => {
+                Err(Error::Api { method: method.to_string(), code: code.clone(), message: message.clone() })
+            }
+            None => Err(Error::Api {
+                method: method.to_string(),
+                code: "unknown_method".into(),
+                message: "not faked".into(),
+            }),
+        }
+    }
+}