@aliou/pi-processes 0.5.0 → 0.6.1

package/README.md

@@ -21,7 +21,10 @@ pi install git:github.com/aliou/pi-processes
 ## Features
 
 - **Tool**: `process` with actions: `start`, `list`, `output`, `logs`, `kill`, `clear`
-- **Commands**: `/process:list` (interactive panel), `/process:stream` (stream logs), `/process:logs` (log paths), `/process:kill` (kill process), `/process:clear` (clear finished)
+- **Commands**: `/ps` (interactive panel), `/ps:pin` (pin dock to process), `/ps:logs` (open log overlay), `/ps:kill` (kill process), `/ps:clear` (clear finished), `/ps:dock` (control dock visibility), `/ps:settings`
+- **Log Dock**: Unified view for all process logs with color-coded prefixes
+- **Follow Mode**: Automatically shows dock when processes start (enabled by default)
+- **Focus Mode**: Filter to a single process's logs
 - Auto-cleanup on session exit
 - File-based logging (logs written to temp files, not memory)
 - Friendly process names (auto-inferred or custom)
@@ -52,19 +55,84 @@ Note: User always sees process updates in the UI. The alert flags control whethe
 
 ### Commands (interactive)
 
-Run `/process:list` to open the panel:
+#### `/ps` - Open full panel
+
+View and manage all processes in an interactive panel:
 - `j/k` - select process
 - `J/K` - scroll logs
-- `enter` - stream logs for selected process
+- `enter` - focus on selected process
 - `x` - kill selected process
 - `c` - clear finished processes
 - `q` - quit
 
-Other commands:
-- `/process:stream [id|name]` - stream logs from a running process
-- `/process:logs [id|name]` - show log file paths
-- `/process:kill [id|name]` - kill a running process
-- `/process:clear` - clear finished processes
+#### `/ps:pin [id|name]` - Pin dock to a process
+
+Pin the dock to a specific process. Opens the dock automatically if hidden.
+
+Without arguments, shows a picker to select a process.
+
+#### `/ps:logs [id|name]` - Open log overlay
+
+Open the interactive log viewer overlay (search, scroll, stream filter).
+
+#### `/ps:kill [id|name]` - Kill a process
+
+Kill a running process. Without arguments, shows a picker.
+
+#### `/ps:clear` - Clear finished
+
+Remove all finished processes from the list.
+
+#### `/ps:dock [show|hide|toggle]` - Control dock
+
+Control dock visibility. Without arguments, it toggles state. With arguments:
+- `show` - Show dock (open)
+- `hide` - Hide dock
+- `toggle` - Cycle dock visibility state
+
+### Log Dock
+
+The log dock shows interleaved logs from all processes with color-coded prefixes:
+
+```
+[dev]   GET /api/users 200 45ms    (cyan)
+[test]  Running auth.test.ts...    (yellow)
+[dev]   POST /api/auth 200 12ms
+[test]  ✓ login flow
+...
+```
+
+**Dock Keyboard Shortcuts** (when dock is open):
+- `h` - focus previous process
+- `l` - focus next process
+- `f` - toggle focus mode (filter to single process)
+- `x` - kill focused process
+- `q` - close/unfocus dock
+- Follow mode toggle is only available via settings (`/ps:settings`)
+
+**Dock States:**
+- `collapsed` (1-2 lines): Summary + last log line
+- `open` (8-12 lines): Full interleaved or focused logs
+
+### Deprecated Commands (backward compatible)
+
+The following commands are deprecated but still work with a warning:
+- `/process:list` → Use `/ps` instead
+- `/process:stream` → Use `/ps:pin` instead
+- `/process:logs` → Use `/ps:logs` instead
+- `/process:kill` → Use `/ps:kill` instead
+- `/process:clear` → Use `/ps:clear` instead
+
+## Settings
+
+Configure via `/ps:settings` or `~/.pi/agent/extensions/processes.json`:
+
+- **Widget**: Dock default state, dock height
+- **Follow Mode**: Enable by default, auto-hide on finish
+- **Process List**: Max visible processes, max preview lines
+- **Output Limits**: Default tail lines, max output lines
+- **Execution**: Shell path override
+- **Interception**: Block background commands
 
 ## Test Scripts
 
@@ -79,8 +147,9 @@ Test scripts in `src/test/` directory:
 
 ## Future Improvements
 
-- [ ] **Expandable log view**: Allow toggling between collapsed (current fixed height) and expanded (full height) log view in the `/process:list` panel.
-
-- [ ] **Copy log file path**: Add keyboard shortcut to copy the stdout/stderr log file path to clipboard for easy access.
-
-- [ ] **Open logs in editor**: Add keyboard shortcut to open log files directly in the configured editor (`$EDITOR` or VS Code).
+- [ ] **Configurable keybindings UI**: Allow editing keybindings in settings panel
+- [ ] **Process filtering**: Filter by name/status in full panel
+- [ ] **Log search**: Search within logs (Ctrl+F in dock)
+- [ ] **Copy log path**: Keyboard shortcut to copy log file path
+- [ ] **Open in editor**: Keyboard shortcut to open logs in $EDITOR
+- [ ] **Sound notifications**: Play sound on process completion

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aliou/pi-processes",
-  "version": "0.5.0",
+  "version": "0.6.1",
   "license": "MIT",
   "type": "module",
   "private": false,
@@ -28,7 +28,7 @@
     "README.md"
   ],
   "dependencies": {
-    "@aliou/pi-utils-settings": "^0.4.0",
+    "@aliou/pi-utils-settings": "^0.6.0",
     "@aliou/pi-utils-ui": "^0.1.0",
     "@aliou/sh": "^0.1.0",
     "@sinclair/typebox": "^0.34.41"

package/src/commands/clear/command.ts

@@ -0,0 +1,14 @@
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import type { ProcessManager } from "../../manager";
+
+export function registerPsClearCommand(
+  pi: ExtensionAPI,
+  manager: ProcessManager,
+): void {
+  pi.registerCommand("ps:clear", {
+    description: "Remove all finished processes from the list",
+    handler: async (_args, _ctx) => {
+      manager.clearFinished();
+    },
+  });
+}

package/src/commands/clear/index.ts

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

package/src/commands/completions.ts

@@ -0,0 +1,38 @@
+import type { ProcessManager } from "../manager";
+
+export function runningProcessCompletions(manager: ProcessManager) {
+  return (prefix: string) => {
+    const processes = manager.list();
+    const lower = prefix.toLowerCase();
+    return processes
+      .filter(
+        (p) =>
+          p.status === "running" &&
+          (p.id.toLowerCase().startsWith(lower) ||
+            p.name.toLowerCase().startsWith(lower)),
+      )
+      .map((p) => ({
+        value: p.id,
+        label: p.id,
+        description: p.name,
+      }));
+  };
+}
+
+export function allProcessCompletions(manager: ProcessManager) {
+  return (prefix: string) => {
+    const processes = manager.list();
+    const lower = prefix.toLowerCase();
+    return processes
+      .filter(
+        (p) =>
+          p.id.toLowerCase().startsWith(lower) ||
+          p.name.toLowerCase().startsWith(lower),
+      )
+      .map((p) => ({
+        value: p.id,
+        label: p.id,
+        description: p.name,
+      }));
+  };
+}

package/src/commands/dock/command.ts

@@ -0,0 +1,29 @@
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import type { DockActions } from "../../hooks/widget";
+
+export function registerPsDockCommand(
+  pi: ExtensionAPI,
+  dockActions: DockActions,
+): void {
+  pi.registerCommand("ps:dock", {
+    description: "Control dock visibility",
+    getArgumentCompletions: () => [
+      { value: "show", label: "show — make the dock visible" },
+      { value: "hide", label: "hide — hide the dock" },
+      { value: "toggle", label: "toggle — cycle visibility" },
+    ],
+    handler: async (args, _ctx) => {
+      const arg = args.trim().toLowerCase();
+
+      if (arg === "show") {
+        dockActions.expand();
+      } else if (arg === "hide") {
+        dockActions.hide();
+      } else if (arg === "toggle" || arg === "") {
+        dockActions.toggle();
+      } else {
+        dockActions.toggle();
+      }
+    },
+  });
+}

package/src/commands/dock/index.ts

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

package/src/commands/index.ts

@@ -1,334 +1,33 @@
-import type {
-  ExtensionAPI,
-  ExtensionCommandContext,
-  Theme,
-} from "@mariozechner/pi-coding-agent";
-import { LogStreamComponent } from "../components/log-stream-component";
-import { ProcessPickerComponent } from "../components/process-picker-component";
-import { ProcessesComponent } from "../components/processes-component";
-import { LIVE_STATUSES, type ProcessInfo } from "../constants";
+/**
+ * Process commands with /ps: prefix.
+ *
+ * /ps                         - View and manage all background processes
+ * /ps:logs [id]               - Open log viewer overlay (search, scroll, stream filter)
+ * /ps:pin [id]                - Pin the dock to a specific process
+ * /ps:kill [id]               - Kill a running process
+ * /ps:clear                   - Remove all finished processes from the list
+ * /ps:dock [show|hide|toggle] - Control dock visibility
+ */
+
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import type { DockActions } from "../hooks/widget";
 import type { ProcessManager } from "../manager";
-
-const LOG_STREAM_WIDGET_ID = "processes-log-stream";
-
-function runningProcessCompletions(manager: ProcessManager) {
-  return (prefix: string) => {
-    const processes = manager.list();
-    const lower = prefix.toLowerCase();
-    return processes
-      .filter(
-        (p) =>
-          LIVE_STATUSES.has(p.status) &&
-          (p.id.toLowerCase().startsWith(lower) ||
-            p.name.toLowerCase().startsWith(lower)),
-      )
-      .map((p) => ({
-        value: p.id,
-        label: p.id,
-        description: p.name,
-      }));
-  };
-}
-
-function allProcessCompletions(manager: ProcessManager) {
-  return (prefix: string) => {
-    const processes = manager.list();
-    const lower = prefix.toLowerCase();
-    return processes
-      .filter(
-        (p) =>
-          p.id.toLowerCase().startsWith(lower) ||
-          p.name.toLowerCase().startsWith(lower),
-      )
-      .map((p) => ({
-        value: p.id,
-        label: p.id,
-        description: p.name,
-      }));
-  };
-}
+import { registerPsClearCommand } from "./clear";
+import { registerPsDockCommand } from "./dock";
+import { registerPsKillCommand } from "./kill";
+import { registerPsLogsCommand } from "./logs";
+import { registerPsPinCommand } from "./pin";
+import { registerPsCommand } from "./processes";
 
 export function setupProcessesCommands(
   pi: ExtensionAPI,
   manager: ProcessManager,
+  dockActions: DockActions,
 ): void {
-  let streamingProcessId: string | null = null;
-
-  // ── /process:list ──────────────────────────────────────────────────
-  // Registered first so it appears first in autocomplete.
-  pi.registerCommand("process:list", {
-    description: "View and manage background processes",
-    handler: async (_args, ctx) => {
-      if (!ctx.hasUI) {
-        ctx.ui.notify("/process:list requires interactive mode", "error");
-        return;
-      }
-
-      // If currently streaming, dismiss the stream widget and show the list.
-      if (streamingProcessId) {
-        ctx.ui.setWidget(LOG_STREAM_WIDGET_ID, undefined);
-        streamingProcessId = null;
-      }
-
-      const result = await ctx.ui.custom<string | null>(
-        (tui, theme, _keybindings, done) => {
-          return new ProcessesComponent(
-            tui,
-            theme,
-            (processId?: string) => {
-              if (processId) {
-                done(processId);
-              } else {
-                done(null);
-              }
-            },
-            manager,
-          );
-        },
-      );
-
-      // RPC fallback.
-      if (result === undefined) {
-        ctx.ui.notify("/process:list requires interactive mode", "info");
-        return;
-      }
-
-      // User dismissed with Escape/q.
-      if (result === null) {
-        return;
-      }
-
-      // User selected a process — start streaming its logs.
-      startStreaming(ctx.ui, manager, result);
-    },
-  });
-
-  // ── /process:stream [id|name] ──────────────────────────────────────
-  pi.registerCommand("process:stream", {
-    description: "Stream logs from a running process",
-    getArgumentCompletions: runningProcessCompletions(manager),
-    handler: async (args, ctx) => {
-      const arg = args.trim();
-
-      // Explicit argument: stream that process.
-      if (arg) {
-        const proc = manager.find(arg);
-        if (!proc) {
-          ctx.ui.notify(`Process not found: ${arg}`, "error");
-          return;
-        }
-        if (!LIVE_STATUSES.has(proc.status)) {
-          ctx.ui.notify(
-            `${proc.name} (${proc.id}) is not running (${proc.status})`,
-            "info",
-          );
-          return;
-        }
-        startStreaming(ctx.ui, manager, proc.id);
-        return;
-      }
-
-      // No argument + currently streaming: dismiss.
-      if (streamingProcessId) {
-        ctx.ui.setWidget(LOG_STREAM_WIDGET_ID, undefined);
-        streamingProcessId = null;
-        return;
-      }
-
-      // No argument + not streaming: pick from running processes.
-      const running = manager.list().filter((p) => LIVE_STATUSES.has(p.status));
-
-      // No running processes.
-      if (running.length === 0) {
-        ctx.ui.notify("No running processes", "info");
-        return;
-      }
-
-      // Single running process: auto-select.
-      if (running.length === 1 && running[0]) {
-        startStreaming(ctx.ui, manager, running[0].id);
-        return;
-      }
-
-      // Multiple running processes: show picker.
-      const processId = await pickProcess(
-        ctx,
-        manager,
-        "Select process to stream",
-        (p) => LIVE_STATUSES.has(p.status),
-      );
-      if (!processId) return;
-      startStreaming(ctx.ui, manager, processId);
-    },
-  });
-
-  // ── /process:logs [id|name] ────────────────────────────────────────
-  pi.registerCommand("process:logs", {
-    description: "Show log file paths for a process",
-    getArgumentCompletions: allProcessCompletions(manager),
-    handler: async (args, ctx) => {
-      const arg = args.trim();
-
-      let processId: string | undefined;
-
-      if (arg) {
-        const proc = manager.find(arg);
-        if (!proc) {
-          ctx.ui.notify(`Process not found: ${arg}`, "error");
-          return;
-        }
-        processId = proc.id;
-      } else {
-        // No argument: show picker.
-        processId = await pickProcess(ctx, manager, "Select process for logs");
-        if (!processId) return;
-      }
-
-      const logFiles = manager.getLogFiles(processId);
-      const proc = manager.get(processId);
-      if (!logFiles || !proc) {
-        ctx.ui.notify(`Process not found: ${processId}`, "error");
-        return;
-      }
-
-      ctx.ui.notify(
-        `${proc.name} (${proc.id})\nstdout: ${logFiles.stdoutFile}\nstderr: ${logFiles.stderrFile}`,
-        "info",
-      );
-    },
-  });
-
-  // ── /process:kill [id|name] ────────────────────────────────────────
-  pi.registerCommand("process:kill", {
-    description: "Kill a running background process",
-    getArgumentCompletions: runningProcessCompletions(manager),
-    handler: async (args, ctx) => {
-      const arg = args.trim();
-
-      let processId: string | undefined;
-
-      if (arg) {
-        const proc = manager.find(arg);
-        if (!proc) {
-          ctx.ui.notify(`Process not found: ${arg}`, "error");
-          return;
-        }
-        if (!LIVE_STATUSES.has(proc.status)) {
-          ctx.ui.notify(
-            `${proc.name} (${proc.id}) is not running (${proc.status})`,
-            "info",
-          );
-          return;
-        }
-        processId = proc.id;
-      } else {
-        // No argument: show picker (only running processes).
-        const running = manager
-          .list()
-          .filter((p) => LIVE_STATUSES.has(p.status));
-
-        if (running.length === 0) {
-          ctx.ui.notify("No running processes to kill", "info");
-          return;
-        }
-
-        if (running.length === 1 && running[0]) {
-          processId = running[0].id;
-        } else {
-          processId = await pickProcess(
-            ctx,
-            manager,
-            "Select process to kill",
-            (p) => LIVE_STATUSES.has(p.status),
-          );
-          if (!processId) return;
-        }
-      }
-
-      const proc = manager.get(processId);
-      if (!proc) {
-        ctx.ui.notify(`Process not found: ${processId}`, "error");
-        return;
-      }
-
-      const signal =
-        proc.status === "terminate_timeout" ? "SIGKILL" : "SIGTERM";
-      const timeoutMs = signal === "SIGKILL" ? 200 : 3000;
-      const result = await manager.kill(processId, { signal, timeoutMs });
-
-      if (result.ok) {
-        ctx.ui.notify(`Killed ${proc.name} (${proc.id})`, "info");
-      } else {
-        ctx.ui.notify(
-          `Failed to kill ${proc.name} (${proc.id}): ${result.reason}`,
-          "error",
-        );
-      }
-    },
-  });
-
-  // ── /process:clear ─────────────────────────────────────────────────
-  pi.registerCommand("process:clear", {
-    description: "Clear finished processes",
-    handler: async (_args, ctx) => {
-      const cleared = manager.clearFinished();
-      if (cleared > 0) {
-        ctx.ui.notify(
-          `Cleared ${cleared} finished process${cleared > 1 ? "es" : ""}`,
-          "info",
-        );
-      } else {
-        ctx.ui.notify("No finished processes to clear", "info");
-      }
-    },
-  });
-
-  // ── Helpers ────────────────────────────────────────────────────────
-
-  function startStreaming(
-    ui: ExtensionCommandContext["ui"],
-    mgr: ProcessManager,
-    processId: string,
-  ) {
-    streamingProcessId = processId;
-    ui.setWidget(
-      LOG_STREAM_WIDGET_ID,
-      (tui: { requestRender: () => void }, theme: Theme) => {
-        return new LogStreamComponent(tui, theme, mgr, processId);
-      },
-      { placement: "aboveEditor" },
-    );
-  }
-}
-
-async function pickProcess(
-  ctx: ExtensionCommandContext,
-  manager: ProcessManager,
-  title: string,
-  filter?: (proc: ProcessInfo) => boolean,
-): Promise<string | undefined> {
-  if (!ctx.hasUI) {
-    ctx.ui.notify("Interactive mode required", "error");
-    return undefined;
-  }
-
-  const result = await ctx.ui.custom<string | null>((tui, theme, _kb, done) => {
-    return new ProcessPickerComponent(
-      tui,
-      theme,
-      (processId?: string) => {
-        done(processId ?? null);
-      },
-      manager,
-      title,
-      filter,
-    );
-  });
-
-  // RPC fallback or user cancelled.
-  if (result === undefined || result === null) {
-    return undefined;
-  }
-
-  return result;
+  registerPsCommand(pi, manager, dockActions);
+  registerPsPinCommand(pi, manager, dockActions);
+  registerPsLogsCommand(pi, manager);
+  registerPsKillCommand(pi, manager, dockActions);
+  registerPsClearCommand(pi, manager);
+  registerPsDockCommand(pi, dockActions);
 }

package/src/commands/kill/command.ts

@@ -0,0 +1,69 @@
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import { LIVE_STATUSES } from "../../constants";
+import type { DockActions } from "../../hooks/widget";
+import type { ProcessManager } from "../../manager";
+import { runningProcessCompletions } from "../completions";
+import { pickProcess } from "../pick-process";
+
+export function registerPsKillCommand(
+  pi: ExtensionAPI,
+  manager: ProcessManager,
+  dockActions: DockActions,
+): void {
+  pi.registerCommand("ps:kill", {
+    description: "Kill a running process",
+    getArgumentCompletions: runningProcessCompletions(manager),
+    handler: async (args, ctx) => {
+      const arg = args.trim();
+
+      let processId: string | undefined;
+
+      if (arg) {
+        const proc = manager.find(arg);
+        if (!proc) {
+          return;
+        }
+        if (!LIVE_STATUSES.has(proc.status)) {
+          return;
+        }
+        processId = proc.id;
+      } else {
+        const running = manager
+          .list()
+          .filter((p) => LIVE_STATUSES.has(p.status));
+
+        if (running.length === 0) {
+          return;
+        }
+
+        if (running.length === 1 && running[0]) {
+          processId = running[0].id;
+        } else {
+          processId = await pickProcess(
+            ctx,
+            manager,
+            "Select process to kill",
+            (p) => LIVE_STATUSES.has(p.status),
+          );
+          if (!processId) return;
+        }
+      }
+
+      const proc = manager.get(processId);
+      if (!proc) {
+        return;
+      }
+
+      const signal =
+        proc.status === "terminate_timeout" ? "SIGKILL" : "SIGTERM";
+      const timeoutMs = signal === "SIGKILL" ? 200 : 3000;
+      const result = await manager.kill(processId, { signal, timeoutMs });
+
+      if (result.ok) {
+        if (dockActions.getFocusedProcessId() === processId) {
+          dockActions.setFocus(null);
+        }
+      }
+    },
+  });
+}

package/src/commands/kill/index.ts

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