@aliou/pi-processes 0.9.5 → 0.10.1

package/src/protocol/requests.ts

@@ -0,0 +1,76 @@
+import type { ProcessInfo } from "../types";
+
+// UI emits, core listens and calls reply synchronously.
+// Reply callbacks make this an in-process protocol, not serializable IPC/RPC.
+
+export interface RequestListPayload {
+  reply: (processes: ProcessInfo[]) => void;
+}
+
+export interface RequestGetPayload {
+  id: string;
+  reply: (info: ProcessInfo | null) => void;
+}
+
+export interface RequestOutputPayload {
+  id: string;
+  tailLines?: number;
+  reply: (
+    output: { stdout: string[]; stderr: string[]; status: string } | null,
+  ) => void;
+}
+
+export interface RequestCombinedOutputPayload {
+  id: string;
+  tailLines?: number;
+  reply: (
+    lines: Array<{ type: "stdout" | "stderr"; text: string }> | null,
+  ) => void;
+}
+
+export interface RequestLogFilesPayload {
+  id: string;
+  reply: (
+    files: {
+      stdoutFile: string;
+      stderrFile: string;
+      combinedFile: string;
+    } | null,
+  ) => void;
+}
+
+export interface RequestFileSizePayload {
+  id: string;
+  reply: (sizes: { stdout: number; stderr: number } | null) => void;
+}
+
+export interface ProcessProtocolConfig {
+  execution: {
+    shellPath: string | undefined;
+  };
+  interception: {
+    blockBackgroundCommands: boolean;
+  };
+  processList: {
+    maxPreviewLines: number;
+    maxVisibleProcesses: number;
+  };
+  output: {
+    defaultTailLines: number;
+    maxOutputLines: number;
+    maxOutputBytes: number;
+  };
+  follow: {
+    enabledByDefault: boolean;
+    autoHideOnFinish: boolean;
+  };
+  widget: {
+    showStatusWidget: boolean;
+    dockDefaultState: "closed" | "collapsed" | "expanded";
+    dockHeight: number;
+  };
+}
+
+export interface RequestConfigPayload {
+  reply: (config: ProcessProtocolConfig) => void;
+}

package/src/types.ts

@@ -0,0 +1,66 @@
+export type ProcessStatus =
+  | "running"
+  | "terminating"
+  | "terminate_timeout"
+  | "exited"
+  | "killed";
+
+export const LIVE_STATUSES: ReadonlySet<ProcessStatus> = new Set([
+  "running",
+  "terminating",
+  "terminate_timeout",
+]);
+
+export type ProcessEndReason =
+  | "exit"
+  | "signal"
+  | "spawn_error"
+  | "missing_pid"
+  | "kill_timeout"
+  | "lost";
+
+export interface ProcessSignalInfo {
+  name: NodeJS.Signals;
+  number: number | null;
+  description: string;
+}
+
+export interface ProcessInfo {
+  id: string;
+  name: string;
+  pid: number; // On Unix, this is also the PGID (process group leader)
+  command: string;
+  cwd: string;
+  startTime: number;
+  endTime: number | null;
+  status: ProcessStatus;
+  exitCode: number | null;
+  success: boolean | null; // null if running, true if exit code 0, false otherwise
+  stdoutFile: string;
+  stderrFile: string;
+  endReason: ProcessEndReason | null;
+  signal: ProcessSignalInfo | null;
+  errorMessage: string | null;
+}
+
+export type ManagerEvent =
+  | { type: "process_started"; info: ProcessInfo }
+  | { type: "process_ended"; info: ProcessInfo }
+  | {
+      type: "process_output_changed";
+      id: string;
+      appendedText?: Array<{ type: "stdout" | "stderr"; text: string }>;
+      droppedLines?: number;
+    }
+  | { type: "processes_changed" };
+
+export type KillResult =
+  | { ok: true; info: ProcessInfo }
+  | { ok: false; info: ProcessInfo; reason: "not_found" | "timeout" | "error" };
+
+export type WriteResult =
+  | { ok: true }
+  | {
+      ok: false;
+      reason: "not_found" | "process_exited" | "stdin_closed" | "write_error";
+    };

package/src/utils/ansi.ts

@@ -12,7 +12,7 @@ const BEL = String.fromCodePoint(0x0007);
 
 const ANSI_REPLACEMENTS: RegExp[] = [
   // CSI sequences: SGR, cursor movement, erase, scroll, etc.
-  new RegExp(`${ESC}\\[[0-9;]*[A-Za-z]`, "gu"),
+  new RegExp(`${ESC}\\[[\\x30-\\x3f]*[\\x20-\\x2f]*[\\x40-\\x7e]`, "gu"),
   // OSC sequences: ESC]...<BEL> or ESC]...<ESC>\\.
   new RegExp(`${ESC}\\][^${BEL}${ESC}]*(?:${BEL}|${ESC}\\\\)`, "gu"),
   // APC sequences: ESC_...<BEL> or ESC_...<ESC>\\.
@@ -25,9 +25,7 @@ const ANSI_REPLACEMENTS: RegExp[] = [
 // biome-ignore lint/suspicious/noControlCharactersInRegex: this regex intentionally targets terminal control characters.
 const TERMINAL_CONTROL_CHARS = /[\u0000-\u0008\u000b-\u001f\u007f]/gu;
 
-/**
- * Check if a string contains ANSI escape codes.
- */
+/** Check if a string contains ANSI escape codes. */
 export function hasAnsi(str: string): boolean {
   return str.includes(ESC);
 }

package/src/utils/format.ts

@@ -1,12 +1,16 @@
-import type { Theme } from "@earendil-works/pi-coding-agent";
-import type { ProcessInfo } from "../constants";
+import type { ProcessStatus } from "../types";
 
+/**
+ * Format a process runtime as a human-readable string.
+ * "3s", "2m 15s", "1h 30m"
+ */
 export function formatRuntime(
   startTime: number,
   endTime: number | null,
+  now: number = Date.now(),
 ): string {
-  const end = endTime ?? Date.now();
-  const ms = end - startTime;
+  const end = endTime ?? now;
+  const ms = Math.max(0, end - startTime);
   const seconds = Math.floor(ms / 1000);
   const minutes = Math.floor(seconds / 60);
   const hours = Math.floor(minutes / 60);
@@ -20,8 +24,16 @@ export function formatRuntime(
   return `${seconds}s`;
 }
 
-export function formatStatus(proc: ProcessInfo): string {
-  switch (proc.status) {
+/**
+ * Format a process status as a plain string.
+ * "running", "exit(0)", "exit(1)"
+ */
+export function formatStatus(proc: {
+  status: string;
+  success: boolean | null;
+  exitCode: number | null;
+}): string {
+  switch (proc.status as ProcessStatus) {
     case "running":
       return "running";
     case "terminating":
@@ -37,38 +49,18 @@ export function formatStatus(proc: ProcessInfo): string {
   }
 }
 
+/**
+ * Truncate a command string to a maximum length.
+ */
 export function truncateCmd(cmd: string, max = 40): string {
   if (cmd.length <= max) return cmd;
   return `${cmd.slice(0, max - 3)}...`;
 }
 
+/**
+ * Format a timestamp as an ISO string or "-" if null.
+ */
 export function formatTimestamp(ts: number | null): string {
   if (!ts) return "-";
   return new Date(ts).toISOString().replace("T", " ").slice(0, 19);
 }
-
-export function formatStatusTag(
-  process: {
-    status: string;
-    success: boolean | null;
-    exitCode: number | null;
-  },
-  theme: Theme,
-): string {
-  switch (process.status) {
-    case "running":
-      return theme.fg("accent", "running");
-    case "terminating":
-      return theme.fg("warning", "terminating");
-    case "terminate_timeout":
-      return theme.fg("error", "terminate_timeout");
-    case "killed":
-      return theme.fg("warning", "killed");
-    case "exited":
-      return process.success
-        ? theme.fg("success", "exit(0)")
-        : theme.fg("error", `exit(${process.exitCode ?? "?"})`);
-    default:
-      return theme.fg("muted", process.status);
-  }
-}

package/src/utils/index.ts

@@ -1,9 +1,13 @@
 export { hasAnsi, stripAnsi } from "./ansi";
+export { resolveShellExecutable, spawnCommand } from "./command-executor";
 export {
   formatRuntime,
   formatStatus,
-  formatStatusTag,
   formatTimestamp,
   truncateCmd,
 } from "./format";
+export type { LineMatchMode } from "./match-line";
+export { compileLineMatcher } from "./match-line";
 export { isProcessGroupAlive, killProcessGroup } from "./process-group";
+export { walkCommands, wordToString } from "./shell-utils";
+export { shortenPath } from "./shorten-path";

package/src/utils/is-record.ts

@@ -0,0 +1,3 @@
+export function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/src/utils/match-line.ts

@@ -0,0 +1,32 @@
+/**
+ * Shared line-matching logic used by both the notification log-matchers
+ * and the output tool action. Pi-agnostic — no Pi imports.
+ */
+
+export type LineMatchMode = "literal" | "regex";
+
+/**
+ * Compile a pattern + mode into a line-matching predicate.
+ *
+ * - literal: substring match (case-sensitive).
+ * - regex:   RegExp test (throws on invalid pattern).
+ */
+export function compileLineMatcher(
+  pattern: string,
+  mode: LineMatchMode,
+): (line: string) => boolean {
+  // Guard against the match-all footgun for an empty pattern. An empty
+  // literal would match every line via String#includes(""), and an empty
+  // regex matches at every position. Callers should treat "" as "no filter",
+  // but defend here too so the shared primitive can never become a match-all.
+  if (pattern.length === 0) {
+    return () => false;
+  }
+
+  if (mode === "literal") {
+    return (line) => line.includes(pattern);
+  }
+
+  const regex = new RegExp(pattern);
+  return (line) => regex.test(line);
+}

package/src/utils/platform.ts

@@ -0,0 +1,13 @@
+/**
+ * Platform gate for the processes extensions.
+ *
+ * The manager spawns detached process groups and kills them by negative pid
+ * (`src/utils/process-group.ts`), which is a POSIX-only operation. On Windows
+ * there is no process-group kill and detached spawn semantics differ, so the
+ * extensions intentionally no-op there rather than silently misbehaving.
+ *
+ * Main (0.9.4) shipped the same guard. The rewrite had dropped it.
+ */
+export function isWindowsPlatform(): boolean {
+  return process.platform === "win32";
+}

package/src/utils/process-group.ts

@@ -3,6 +3,7 @@
  * Uses signal 0 to test existence without actually sending a signal.
  */
 export function isProcessGroupAlive(pgid: number): boolean {
+  if (!Number.isInteger(pgid) || pgid <= 0) return false;
   try {
     process.kill(-pgid, 0);
     return true;
@@ -18,5 +19,8 @@ export function isProcessGroupAlive(pgid: number): boolean {
  * Negative PID targets the process group.
  */
 export function killProcessGroup(pgid: number, signal: NodeJS.Signals): void {
+  if (!Number.isInteger(pgid) || pgid <= 0) {
+    throw new RangeError("Process group ID must be a positive integer");
+  }
   process.kill(-pgid, signal);
 }

package/src/utils/shorten-path.ts

@@ -0,0 +1,11 @@
+import { homedir } from "node:os";
+import { sep } from "node:path";
+
+/** Replace a home-directory prefix with `~` for display. */
+export function shortenPath(path: string, home = homedir()): string {
+  if (path === home) return "~";
+  if (path.startsWith(`${home}${sep}`)) {
+    return `~${path.slice(home.length)}`;
+  }
+  return path;
+}

package/src/utils/signals.ts

@@ -0,0 +1,22 @@
+import type { ProcessSignalInfo } from "../types";
+
+const SIGNALS: Partial<
+  Record<NodeJS.Signals, { number: number; description: string }>
+> = {
+  SIGINT: { number: 2, description: "interrupt" },
+  SIGTERM: { number: 15, description: "termination request" },
+  SIGKILL: { number: 9, description: "forced kill" },
+  SIGHUP: { number: 1, description: "terminal hangup" },
+  SIGQUIT: { number: 3, description: "quit" },
+  SIGABRT: { number: 6, description: "abort" },
+  SIGALRM: { number: 14, description: "alarm" },
+};
+
+export function formatSignalInfo(signal: NodeJS.Signals): ProcessSignalInfo {
+  const known = SIGNALS[signal];
+  return {
+    name: signal,
+    number: known?.number ?? null,
+    description: known?.description ?? signal,
+  };
+}

package/src/commands/clear/command.ts

@@ -1,14 +0,0 @@
-import type { ExtensionAPI } from "@earendil-works/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

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

package/src/commands/completions.ts

@@ -1,38 +0,0 @@
-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

@@ -1,29 +0,0 @@
-import type { ExtensionAPI } from "@earendil-works/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

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

package/src/commands/index.ts

@@ -1,33 +0,0 @@
-/**
- * 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 "@earendil-works/pi-coding-agent";
-import type { DockActions } from "../hooks/widget";
-import type { ProcessManager } from "../manager";
-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 {
-  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

@@ -1,69 +0,0 @@
-import type { ExtensionAPI } from "@earendil-works/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.get(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;
-        }
-      }
-
-      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(proc.id, { signal, timeoutMs });
-
-      if (result.ok) {
-        if (dockActions.getFocusedProcessId() === proc.id) {
-          dockActions.setFocus(null);
-        }
-      }
-    },
-  });
-}

package/src/commands/kill/index.ts

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

package/src/commands/logs/command.ts

@@ -1,47 +0,0 @@
-import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import { LogOverlayComponent } from "../../components/log-overlay-component";
-import type { ProcessManager } from "../../manager";
-import { allProcessCompletions } from "../completions";
-
-export function registerPsLogsCommand(
-  pi: ExtensionAPI,
-  manager: ProcessManager,
-): void {
-  pi.registerCommand("ps:logs", {
-    description:
-      "Open log viewer for a process (search, scroll, stream filter)",
-    getArgumentCompletions: allProcessCompletions(manager),
-    handler: async (args, ctx) => {
-      if (!ctx.hasUI) return;
-
-      const arg = args.trim();
-      let processId: string | undefined;
-
-      if (arg) {
-        const proc = manager.get(arg);
-        if (!proc) return;
-        processId = proc.id;
-      }
-
-      await ctx.ui.custom<null>(
-        (_tui, theme, _kb, done) => {
-          return new LogOverlayComponent({
-            tui: _tui,
-            theme,
-            manager,
-            initialProcessId: processId,
-            done: () => done(null),
-          });
-        },
-        {
-          overlay: true,
-          overlayOptions: {
-            width: "90%",
-            maxHeight: "80%",
-            anchor: "center",
-          },
-        },
-      );
-    },
-  });
-}

package/src/commands/logs/index.ts

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

package/src/commands/pick-process.ts

@@ -1,34 +0,0 @@
-import type { ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
-import { ProcessPickerComponent } from "../components/process-picker-component";
-import type { ProcessInfo } from "../constants";
-import type { ProcessManager } from "../manager";
-
-export async function pickProcess(
-  ctx: ExtensionCommandContext,
-  manager: ProcessManager,
-  title: string,
-  filter?: (proc: ProcessInfo) => boolean,
-): Promise<string | undefined> {
-  if (!ctx.hasUI) {
-    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,
-    );
-  });
-
-  if (result === undefined || result === null) {
-    return undefined;
-  }
-
-  return result;
-}