@mjakl/pi-processes 0.8.0

package/README.md

@@ -0,0 +1,137 @@
+# Processes Extension
+
+> **Note**
+> This is a stripped down fork of https://github.com/aliou/pi-processes.
+> Most people should likely use the original project instead.
+
+Manage background processes from Pi without blocking the conversation.
+
+## Installation
+
+Install from npm:
+
+```bash
+pi install npm:@mjakl/pi-processes
+```
+
+For development builds, install from git:
+
+```bash
+pi install git:https://github.com/mjakl/pi-processes
+```
+
+## What this fork keeps
+
+- the `process` tool for starting, listing, inspecting, killing, and clearing managed processes
+- a single `/ps` overlay for monitoring processes
+- a tiny always-visible process status line while managed processes exist, showing active/finished counts
+- process completion notifications in the conversation
+- file-backed logs so process output is preserved outside agent context
+
+## What this fork removes
+
+- all `/ps:*` subcommands
+- the log dock
+- the settings UI
+- extra widget state and dock controls
+
+## Usage
+
+### Agent tool (LLM-facing)
+
+The `process` tool is for the agent. Users should ask the agent to start or inspect long-running commands, then monitor them with `/ps`.
+
+Tool-call examples:
+
+```text
+process start "pnpm dev" name="backend-dev"
+process start "pnpm test --watch" name="tests"
+process start "pnpm dev" name="backend-dev" continueAfterStart=true
+process list
+process output id="backend-dev"
+process logs id="proc_1"
+process kill id="backend-dev"
+process kill id="proc_1" force=true
+process clear
+```
+
+#### Matching processes
+
+For `output`, `logs`, and `kill`, `id` must be either:
+
+- the exact process ID (`proc_1`)
+- the exact friendly process name (`backend-dev`)
+
+If multiple processes share the same name, use the process ID.
+
+#### Notifications for `start`
+
+Do not poll after starting a process.
+
+This tool is event-driven: the agent is notified automatically when a process exits, fails, or is externally killed. By default, `process start` ends the current agent turn so the agent actually waits for that notification instead of immediately polling. If the next step is waiting, call `process start` by itself rather than batching it with unrelated tools.
+
+The intended pattern is:
+
+1. `process start`
+2. let the turn stop and wait for the automatic notification if the process ends
+3. resume from that notification
+
+Use `continueAfterStart=true` only when the agent has immediate, specific, non-polling work to do after starting the process.
+
+Repeated `process list`, `process output`, or `process logs` calls just to see whether the process is still running are an anti-pattern.
+
+#### Logs and output
+
+- `process output` returns a one-off tailed stdout/stderr snapshot for agent consumption.
+- `process logs` returns file paths for `stdout`, `stderr`, and a combined view for the `/ps` overlay.
+- Use `output`/`logs` only when the user asks, when you need a diagnostic snapshot, or when investigating a problem - not as a polling loop.
+
+#### Killing processes
+
+- `process kill id="..."` sends `SIGTERM`
+- `process kill id="..." force=true` sends `SIGKILL`
+- tool-triggered kills never notify the agent
+
+### `/ps` overlay
+
+`/ps` opens the process overlay.
+
+Inside the overlay:
+
+- `up/down` - move the highlighted process
+- `left/right` - scroll older/newer log output for the highlighted process
+- `g/G` - jump to the top or back to the live tail
+- `x` - terminate the highlighted process; press `x` again when it shows `needs kill` to force-kill it
+- `c` - clear finished processes
+- `q` or `Esc` - close the overlay
+
+The right side always shows logs for the currently highlighted process.
+
+## Configuration
+
+Global config lives in `~/.pi/agent/extensions/process.json`.
+
+```json
+{
+  "output": {
+    "defaultTailLines": 100,
+    "maxOutputLines": 200
+  },
+  "execution": {
+    "shellPath": "/absolute/path/to/bash"
+  },
+  "interception": {
+    "blockBackgroundCommands": true
+  }
+}
+```
+
+- `output.defaultTailLines` - default number of lines returned by `process output`
+- `output.maxOutputLines` - hard cap for `process output`
+- `execution.shellPath` - absolute shell path override used for process startup
+- `interception.blockBackgroundCommands` - block shell backgrounding (`&`, `nohup`, `disown`, `setsid`) and obvious long-running foreground commands such as `pnpm dev`, `docker compose up`, `tail -f`, or `kubectl port-forward`, and guide the agent to use the `process` tool instead
+
+## Notes
+
+- Log files live in a temporary directory managed by the extension.
+- Background processes are cleaned up when the session shuts down.

package/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "@mjakl/pi-processes",
+  "version": "0.8.0",
+  "license": "MIT",
+  "type": "module",
+  "private": false,
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "pi",
+    "processes"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/mjakl/pi-processes"
+  },
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ]
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "src",
+    "!src/**/*.test.ts",
+    "README.md"
+  ],
+  "dependencies": {
+    "@aliou/sh": "^0.1.0"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*",
+    "typebox": "*"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.3.13",
+    "@earendil-works/pi-coding-agent": "0.75.1",
+    "@earendil-works/pi-tui": "0.75.1",
+    "@types/node": "^25.0.10",
+    "husky": "^9.1.7",
+    "typebox": "^1.1.24",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.18"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "lint": "biome check",
+    "format": "biome check --write",
+    "test": "vitest run",
+    "check:lockfile": "pnpm install --frozen-lockfile --ignore-scripts",
+    "prepare": "[ -d .git ] && husky || true"
+  },
+  "packageManager": "pnpm@10.26.1",
+  "peerDependenciesMeta": {
+    "@earendil-works/pi-coding-agent": {
+      "optional": true
+    },
+    "@earendil-works/pi-tui": {
+      "optional": true
+    },
+    "typebox": {
+      "optional": true
+    }
+  }
+}

package/src/commands/index.ts

@@ -0,0 +1,10 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type { ProcessManager } from "../manager";
+import { registerPsCommand } from "./processes";
+
+export function setupProcessesCommands(
+  pi: ExtensionAPI,
+  manager: ProcessManager,
+): void {
+  registerPsCommand(pi, manager);
+}

package/src/commands/processes/command.ts

@@ -0,0 +1,31 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { ProcessesComponent } from "../../components/processes-component";
+import type { ProcessManager } from "../../manager";
+
+export function registerPsCommand(
+  pi: ExtensionAPI,
+  manager: ProcessManager,
+): void {
+  pi.registerCommand("ps", {
+    description: "Open the process overlay",
+    handler: async (_args, ctx) => {
+      if (!ctx.hasUI) {
+        return;
+      }
+
+      await ctx.ui.custom<null>(
+        (tui, theme, _keybindings, done) => {
+          return new ProcessesComponent(tui, theme, () => done(null), manager);
+        },
+        {
+          overlay: true,
+          overlayOptions: {
+            width: "90%",
+            maxHeight: "80%",
+            anchor: "center",
+          },
+        },
+      );
+    },
+  });
+}

package/src/commands/processes/index.ts

@@ -0,0 +1 @@
+export { registerPsCommand } from "./command";

package/src/components/log-file-viewer.ts

@@ -0,0 +1,317 @@
+/**
+ * LogFileViewer - reads a single log file and renders a scrollable,
+ * searchable window of lines.
+ *
+ * A plain helper class (not a Component). Currently consumed by the
+ * `/ps` overlay. Callers are responsible for polling / invalidating when
+ * file content changes.
+ */
+
+import { readFileSync } from "node:fs";
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import { truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
+import { stripAnsi } from "../utils";
+
+export type StreamFilter = "combined" | "stdout" | "stderr";
+export type LineFormat = "plain" | "combined";
+
+interface ParsedLine {
+  type: "stdout" | "stderr";
+  text: string;
+}
+
+export interface LogFileViewerOptions {
+  filePath: string;
+  /** "plain" = raw lines (stdout/stderr files), "combined" = manager's 1:/2: tagged format */
+  format: LineFormat;
+  theme: Theme;
+  /** Start in follow mode (auto-scroll to tail). Default: false */
+  follow?: boolean;
+}
+
+export class LogFileViewer {
+  private filePath: string;
+  private format: LineFormat;
+  private theme: Theme;
+
+  private follow: boolean;
+  /** Absolute index of the last visible line (1-based).
+   *  null = follow mode; always shows latest lines. */
+  private anchorEnd: number | null = null;
+  private streamFilter: StreamFilter = "combined";
+
+  private searchQuery = "";
+  private searchMatches: number[] = [];
+  private searchCurrentMatch = -1;
+
+  /** Line index (0-based) to center in the viewport. null = not centering. */
+  private centerTarget: number | null = null;
+
+  constructor(opts: LogFileViewerOptions) {
+    this.filePath = opts.filePath;
+    this.format = opts.format;
+    this.theme = opts.theme;
+    this.follow = opts.follow ?? false;
+  }
+
+  // ---------------------------------------------------------------------------
+  // File reading
+  // ---------------------------------------------------------------------------
+
+  private readAllLines(): ParsedLine[] {
+    try {
+      const content = readFileSync(this.filePath, "utf-8");
+      const rawLines = content.split("\n");
+      // Remove trailing empty string produced by a trailing newline.
+      if (rawLines.length > 0 && rawLines[rawLines.length - 1] === "") {
+        rawLines.pop();
+      }
+
+      if (this.format === "plain") {
+        return rawLines.map((line) => ({
+          type: "stdout" as const,
+          text: line,
+        }));
+      }
+
+      // Combined format: "1:text" = stdout, "2:text" = stderr
+      return rawLines.map((line) => {
+        if (line.startsWith("2:")) {
+          return { type: "stderr" as const, text: line.slice(2) };
+        }
+        return {
+          type: "stdout" as const,
+          text: line.startsWith("1:") ? line.slice(2) : line,
+        };
+      });
+    } catch {
+      return [];
+    }
+  }
+
+  private applyFilter(allLines: ParsedLine[]): ParsedLine[] {
+    if (this.streamFilter === "combined") return allLines;
+    const keep = this.streamFilter === "stdout" ? "stdout" : "stderr";
+    return allLines.filter((l) => l.type === keep);
+  }
+
+  private computeMatches(lines: ParsedLine[]): number[] {
+    if (!this.searchQuery) return [];
+    const q = this.searchQuery.toLowerCase();
+    return lines.reduce<number[]>((acc, line, i) => {
+      if (stripAnsi(line.text).toLowerCase().includes(q)) acc.push(i);
+      return acc;
+    }, []);
+  }
+
+  // ---------------------------------------------------------------------------
+  // Navigation
+  // ---------------------------------------------------------------------------
+
+  scrollToTop(): void {
+    this.anchorEnd = 0;
+    this.follow = false;
+  }
+
+  scrollToBottom(): void {
+    const lines = this.applyFilter(this.readAllLines());
+    this.anchorEnd = lines.length;
+    this.follow = false;
+  }
+
+  /** delta > 0 = scroll toward older content, delta < 0 = toward newer. */
+  scrollBy(delta: number): void {
+    if (this.anchorEnd === null) {
+      const lines = this.applyFilter(this.readAllLines());
+      this.anchorEnd = lines.length;
+    }
+    this.anchorEnd = Math.max(0, this.anchorEnd - delta);
+    this.follow = false;
+  }
+
+  toggleFollow(): boolean {
+    this.follow = !this.follow;
+    if (this.follow) {
+      this.anchorEnd = null;
+    } else {
+      const lines = this.applyFilter(this.readAllLines());
+      this.anchorEnd = lines.length;
+    }
+    return this.follow;
+  }
+
+  isFollowing(): boolean {
+    return this.follow;
+  }
+
+  cycleStreamFilter(): StreamFilter {
+    const order: StreamFilter[] = ["combined", "stdout", "stderr"];
+    this.streamFilter =
+      order[(order.indexOf(this.streamFilter) + 1) % order.length];
+    // Invalidate search since the line set changed.
+    this.searchMatches = [];
+    this.searchCurrentMatch = -1;
+    return this.streamFilter;
+  }
+
+  getStreamFilter(): StreamFilter {
+    return this.streamFilter;
+  }
+
+  // ---------------------------------------------------------------------------
+  // Search
+  // ---------------------------------------------------------------------------
+
+  setSearch(query: string): void {
+    this.searchQuery = query;
+    const lines = this.applyFilter(this.readAllLines());
+    this.searchMatches = this.computeMatches(lines);
+    if (this.searchMatches.length > 0) {
+      // Start at the last match so the user lands near the tail.
+      this.searchCurrentMatch = this.searchMatches.length - 1;
+      this.jumpToMatchLine(this.searchMatches[this.searchCurrentMatch]);
+    } else {
+      this.searchCurrentMatch = -1;
+    }
+  }
+
+  clearSearch(): void {
+    this.searchQuery = "";
+    this.searchMatches = [];
+    this.searchCurrentMatch = -1;
+  }
+
+  private jumpToMatchLine(lineIdx: number): void {
+    this.centerTarget = lineIdx;
+    this.follow = false;
+  }
+
+  nextMatch(): void {
+    if (this.searchMatches.length === 0) return;
+    this.searchCurrentMatch =
+      (this.searchCurrentMatch + 1) % this.searchMatches.length;
+    this.jumpToMatchLine(this.searchMatches[this.searchCurrentMatch]);
+  }
+
+  prevMatch(): void {
+    if (this.searchMatches.length === 0) return;
+    this.searchCurrentMatch =
+      (this.searchCurrentMatch - 1 + this.searchMatches.length) %
+      this.searchMatches.length;
+    this.jumpToMatchLine(this.searchMatches[this.searchCurrentMatch]);
+  }
+
+  getSearchInfo(): { query: string; current: number; total: number } | null {
+    if (!this.searchQuery) return null;
+    return {
+      query: this.searchQuery,
+      current: this.searchCurrentMatch + 1, // 1-based for display
+      total: this.searchMatches.length,
+    };
+  }
+
+  // ---------------------------------------------------------------------------
+  // Rendering
+  // ---------------------------------------------------------------------------
+
+  /** Returns up to `maxLines` rendered content lines. */
+  renderLines(width: number, maxLines: number): string[] {
+    const theme = this.theme;
+    const dim = (s: string) => theme.fg("dim", s);
+    const warning = (s: string) => theme.fg("warning", s);
+
+    const allLines = this.readAllLines();
+    const lines = this.applyFilter(allLines);
+
+    // Refresh matches against current (possibly grown) data.
+    if (this.searchQuery) {
+      this.searchMatches = this.computeMatches(lines);
+      if (this.searchCurrentMatch >= this.searchMatches.length) {
+        this.searchCurrentMatch = Math.max(0, this.searchMatches.length - 1);
+      }
+    }
+
+    const total = lines.length;
+    if (total === 0) return [dim("(no output yet)")];
+
+    // Resolve centerTarget into anchorEnd now that we know maxLines.
+    if (this.centerTarget !== null) {
+      const half = Math.floor(maxLines / 2);
+      this.anchorEnd = Math.min(total, this.centerTarget + half + 1);
+      this.centerTarget = null;
+    }
+
+    // Resolve anchor: null = follow (tail), number = absolute frozen end.
+    const rawEnd = this.anchorEnd ?? total;
+    // Clamp to valid range. Math.max with min(maxLines, total) ensures anchorEnd = 0
+    // (scrollToTop sentinel) still shows a full window from the top.
+    const endIdx = Math.min(total, Math.max(rawEnd, Math.min(maxLines, total)));
+    const startIdx = Math.max(0, endIdx - maxLines);
+
+    const currentMatchIdx =
+      this.searchCurrentMatch >= 0 &&
+      this.searchCurrentMatch < this.searchMatches.length
+        ? this.searchMatches[this.searchCurrentMatch]
+        : -1;
+    const matchSet = new Set(this.searchMatches);
+
+    return lines.slice(startIdx, endIdx).map((line, i) => {
+      const absIdx = startIdx + i;
+      const text = truncateToWidth(stripAnsi(line.text), width);
+
+      if (absIdx === currentMatchIdx) return theme.bold(theme.inverse(text));
+      if (matchSet.has(absIdx)) return warning(text);
+      if (line.type === "stderr") return warning(text);
+      return text;
+    });
+  }
+
+  /**
+   * Returns a single status-bar string exactly `width` characters wide
+   * (visible width). Shows position, stream filter, and search state.
+   */
+  renderStatusBar(width: number): string {
+    const theme = this.theme;
+    const dim = (s: string) => theme.fg("dim", s);
+    const accent = (s: string) => theme.fg("accent", s);
+
+    const lines = this.applyFilter(this.readAllLines());
+    const total = lines.length;
+
+    // Right side: position + stream filter
+    const rightParts: string[] = [];
+    if (this.follow) {
+      rightParts.push(accent("following"));
+    } else if (total === 0) {
+      rightParts.push(dim("empty"));
+    } else {
+      const rawEnd = this.anchorEnd ?? total;
+      const endIdx = Math.min(total, Math.max(0, rawEnd));
+      const pct = Math.round((endIdx / total) * 100);
+      rightParts.push(dim(`${pct}%  L${Math.min(endIdx, total)}/${total}`));
+    }
+    if (this.streamFilter !== "combined") {
+      rightParts.push(dim(`[${this.streamFilter}]`));
+    }
+
+    // Left side: search state
+    const searchInfo = this.getSearchInfo();
+    let left = "";
+    if (searchInfo) {
+      left =
+        searchInfo.total === 0
+          ? theme.fg("error", `no matches: "${searchInfo.query}"`)
+          : `${dim("/")}${searchInfo.query}  ${dim(`${searchInfo.current}/${searchInfo.total}`)}`;
+    }
+
+    const right = rightParts.join("  ");
+    const leftW = visibleWidth(left);
+    const rightW = visibleWidth(right);
+    const gap = Math.max(1, width - leftW - rightW);
+    const bar = left + " ".repeat(gap) + right;
+    const barW = visibleWidth(bar);
+
+    if (barW > width) return truncateToWidth(bar, width);
+    return bar + " ".repeat(width - barW);
+  }
+}