@aliou/pi-processes 0.9.4 → 0.10.0

package/extensions/processes-logs/logs-client.ts

@@ -0,0 +1,101 @@
+import type { EventBus } from "@earendil-works/pi-coding-agent";
+import {
+  CHANNELS,
+  type LogsChunkPayload,
+  type LogsSubscribePayload,
+  type LogsUnsubscribePayload,
+} from "../../src/protocol";
+import { isRecord } from "../../src/utils/is-record";
+
+export type ProcessLogLine = { type: "stdout" | "stderr"; text: string };
+
+export interface LogsConnection {
+  initialLines: ProcessLogLine[];
+  onChunk: (callback: (lines: ProcessLogLine[]) => void) => () => void;
+  unsubscribe: () => void;
+}
+
+export function connectToProcessLogs(
+  events: EventBus,
+  processId: string,
+  opts: { tailLines?: number } = {},
+): LogsConnection | { ok: false; error: string } {
+  const subscriberId = `processes-logs-${Date.now()}-${Math.random().toString(36).slice(2)}`;
+  let initialLines: ProcessLogLine[] = [];
+  let error: string | null = null;
+  let replied = false;
+  let disposed = false;
+  const chunkCallbacks = new Set<(lines: ProcessLogLine[]) => void>();
+
+  const disposeChunkListener = events.on(CHANNELS.LOGS_CHUNK, (raw) => {
+    if (disposed) return;
+    if (!isLogsChunkPayload(raw)) return;
+    const chunk = raw;
+    if (chunk.subscriberId !== subscriberId || chunk.processId !== processId)
+      return;
+
+    for (const callback of chunkCallbacks) callback(chunk.lines);
+  });
+
+  const payload: LogsSubscribePayload = {
+    subscriberId,
+    processId,
+    tailLines: opts.tailLines,
+    reply: (result) => {
+      replied = true;
+      if (result.ok) {
+        initialLines = result.initialLines;
+      } else {
+        error = result.error;
+      }
+    },
+  };
+
+  events.emit(CHANNELS.LOGS_SUBSCRIBE, payload);
+
+  if (!replied) {
+    disposeChunkListener();
+    return {
+      ok: false,
+      error: "processes core extension did not reply to log subscription",
+    };
+  }
+  if (error) {
+    disposeChunkListener();
+    return { ok: false, error };
+  }
+
+  return {
+    initialLines,
+    onChunk: (callback) => {
+      chunkCallbacks.add(callback);
+      return () => chunkCallbacks.delete(callback);
+    },
+    unsubscribe: () => {
+      if (disposed) return;
+      disposed = true;
+      chunkCallbacks.clear();
+      disposeChunkListener();
+      const unsubscribePayload: LogsUnsubscribePayload = { subscriberId };
+      events.emit(CHANNELS.LOGS_UNSUBSCRIBE, unsubscribePayload);
+    },
+  };
+}
+
+function isLogsChunkPayload(payload: unknown): payload is LogsChunkPayload {
+  return (
+    isRecord(payload) &&
+    typeof payload.subscriberId === "string" &&
+    typeof payload.processId === "string" &&
+    Array.isArray(payload.lines) &&
+    payload.lines.every(isProcessLogLine)
+  );
+}
+
+function isProcessLogLine(line: unknown): line is ProcessLogLine {
+  return (
+    isRecord(line) &&
+    (line.type === "stdout" || line.type === "stderr") &&
+    typeof line.text === "string"
+  );
+}

package/extensions/shared/line-buffer.ts

@@ -0,0 +1,35 @@
+export const OUTPUT_DROPPED_MARKER_TYPE = "stderr" as const;
+
+export function buildDroppedOutputLine(count: number): {
+  type: typeof OUTPUT_DROPPED_MARKER_TYPE;
+  text: string;
+} {
+  return {
+    type: OUTPUT_DROPPED_MARKER_TYPE,
+    text: `… ${count} lines dropped (output too fast)`,
+  };
+}
+
+export function trimToBudget<T>(
+  lines: T[],
+  maxLines: number,
+  maxBytes: number,
+  textOf: (line: T) => string = (line) => (line as { text: string }).text,
+): T[] {
+  if (lines.length === 0) return [];
+
+  const lineLimit = Math.max(1, maxLines);
+  const out =
+    lines.length > lineLimit ? lines.slice(-lineLimit) : lines.slice();
+  let bytes = 0;
+
+  for (let index = out.length - 1; index >= 0; index--) {
+    bytes += Buffer.byteLength(textOf(out[index]), "utf-8");
+    if (bytes > maxBytes) {
+      // Keep the newest line even when it alone exceeds the whole budget.
+      return index === out.length - 1 ? out.slice(index) : out.slice(index + 1);
+    }
+  }
+
+  return out;
+}

package/extensions/shared/output-payload.ts

@@ -0,0 +1,28 @@
+import type { ProcessesOutputChangedPayload } from "../../src/protocol";
+import { isRecord } from "../../src/utils/is-record";
+
+export function isOutputChangedPayload(
+  payload: unknown,
+): payload is ProcessesOutputChangedPayload {
+  return (
+    isRecord(payload) &&
+    typeof payload.id === "string" &&
+    (payload.appendedText === undefined ||
+      (Array.isArray(payload.appendedText) &&
+        payload.appendedText.every(isOutputLine))) &&
+    (payload.droppedLines === undefined ||
+      (typeof payload.droppedLines === "number" &&
+        Number.isSafeInteger(payload.droppedLines) &&
+        payload.droppedLines > 0))
+  );
+}
+
+function isOutputLine(
+  value: unknown,
+): value is { type: "stdout" | "stderr"; text: string } {
+  return (
+    isRecord(value) &&
+    (value.type === "stdout" || value.type === "stderr") &&
+    typeof value.text === "string"
+  );
+}

package/extensions/shared/ui.ts

@@ -0,0 +1,146 @@
+/**
+ * Shared extension-UI primitives used across the processes, processes-logs,
+ * and processes-dock extensions.
+ *
+ * This module lives outside pi-agnostic `src/` because it depends on the Pi
+ * TUI (`Component`, `Theme`). It consolidates the tiny render-component
+ * copies and the status-display helpers that were duplicated across the three
+ * extensions.
+ */
+
+import type { Theme, ThemeColor } from "@earendil-works/pi-coding-agent";
+import { type Component, visibleWidth } from "@earendil-works/pi-tui";
+
+import { LIVE_STATUSES, type ProcessInfo } from "../../src/types";
+import { formatStatus } from "../../src/utils/format";
+
+// ---------------------------------------------------------------------------
+// Render components
+// ---------------------------------------------------------------------------
+
+/** Render a single line produced by a width-aware callback. */
+export class LineComponent implements Component {
+  constructor(private readonly renderLine: (width: number) => string) {}
+
+  render(width: number): string[] {
+    return [this.renderLine(width)];
+  }
+
+  invalidate(): void {}
+}
+
+/** Render multiple lines produced by a width-aware callback. */
+export class LinesComponent implements Component {
+  constructor(private readonly renderLines: (width: number) => string[]) {}
+
+  render(width: number): string[] {
+    return this.renderLines(width);
+  }
+
+  invalidate(): void {}
+}
+
+/** Render a horizontal rule line sized to the available width. */
+export class RuleComponent implements Component {
+  constructor(private readonly theme: Theme) {}
+
+  render(width: number): string[] {
+    return [this.theme.fg("dim", "─".repeat(Math.max(0, width)))];
+  }
+
+  invalidate(): void {}
+}
+
+// ---------------------------------------------------------------------------
+// Name column / tab width
+// ---------------------------------------------------------------------------
+
+/** Maximum visible width for a process name or tab label. */
+export const MAX_TAB_NAME = 12;
+
+/** Minimum width for the dock log-line sidebar column. */
+export const MIN_NAME_COLUMN = 4;
+
+/**
+ * Compute the sidebar width for a set of processes: the longest name
+ * clamped to [min, max]. Use this instead of hardcoding a fixed width so
+ * short names (`api`, `web`) don't get padded to 12 columns.
+ */
+export function clampNameColumn(
+  processes: ProcessInfo[],
+  max: number = MAX_TAB_NAME,
+  min: number = MIN_NAME_COLUMN,
+): number {
+  const longest = processes.reduce(
+    (acc, p) => Math.max(acc, visibleWidth(p.name)),
+    0,
+  );
+  return Math.min(Math.max(longest, min), max);
+}
+
+// ---------------------------------------------------------------------------
+// Status formatting
+// ---------------------------------------------------------------------------
+
+/**
+ * The color a process's status should render in. Shared by the status dot
+ * and process name so the dot and the name always agree on color.
+ */
+export function statusColor(process: ProcessInfo): ThemeColor {
+  if (process.success === false && process.status !== "killed") {
+    return "error";
+  }
+  if (process.status === "terminating") {
+    return "warning";
+  }
+  if (LIVE_STATUSES.has(process.status)) {
+    return "accent";
+  }
+  if (process.status === "exited" && process.success) {
+    return "success";
+  }
+  return "dim";
+}
+
+/**
+ * Render the status indicator dot for a process.
+ *
+ * Glyph carries state class; color refines:
+ * - `!` (error) for failures/crashes, unless intentionally killed.
+ * - `●` (warning) for terminating.
+ * - `●`/`○` (accent/dim) for live processes, depending on `active`.
+ * - `✓` (success) for a clean exit.
+ * - `■` (dim) for other terminal states (e.g. killed).
+ */
+export function statusDot(
+  process: ProcessInfo,
+  active: boolean,
+  theme: Theme,
+): string {
+  if (process.success === false && process.status !== "killed") {
+    return theme.fg("error", "!");
+  }
+  if (process.status === "terminating") {
+    return theme.fg("warning", "●");
+  }
+  if (LIVE_STATUSES.has(process.status)) {
+    return active ? theme.fg("accent", "●") : theme.fg("dim", "○");
+  }
+  if (process.status === "exited" && process.success) {
+    return theme.fg("success", "✓");
+  }
+  return theme.fg("dim", "■");
+}
+
+/**
+ * Build the `description` string for process picker items and autocomplete
+ * completions: `"running — pnpm dev"`. Shared so `/ps:kill`, `/ps:logs`,
+ * `/ps:pin`, and the logs completions stay consistent.
+ */
+export function formatProcessSelectionDescription(
+  process: ProcessInfo,
+  suffix = "",
+): string {
+  const base = `${formatStatus(process)} — ${process.command}`;
+  return suffix ? `${base}${suffix}` : base;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aliou/pi-processes",
-  "version": "0.9.4",
+  "version": "0.10.0",
   "license": "MIT",
   "type": "module",
   "private": false,
@@ -16,25 +16,34 @@
   },
   "pi": {
     "extensions": [
-      "./src/index.ts"
+      "./extensions/processes/index.ts",
+      "./extensions/processes-logs/index.ts",
+      "./extensions/processes-dock/index.ts"
     ],
     "skills": [
       "./skills/pi-processes"
     ],
-    "video": "https://assets.aliou.me/github/aliou/pi-processes/demo.mp4"
+    "video": "https://assets.aliou.me/pi-extensions/demos/pi-processes.mp4"
   },
   "publishConfig": {
     "access": "public"
   },
+  "engines": {
+    "node": ">=22.19.0"
+  },
   "files": [
     "src",
+    "!src/**/*.test.ts",
+    "extensions",
+    "!extensions/**/*.test.ts",
     "skills",
+    "schema.json",
     "README.md",
     "CONTRIBUTING.md"
   ],
   "dependencies": {
-    "@aliou/pi-utils-settings": "^0.15.1",
-    "@aliou/pi-utils-ui": "^0.4.1",
+    "@aliou/pi-utils-settings": "^0.18.0",
+    "@aliou/pi-utils-ui": "^0.5.0",
     "@aliou/sh": "^0.1.0"
   },
   "peerDependencies": {
@@ -46,12 +55,40 @@
   "devDependencies": {
     "@aliou/biome-plugins": "^0.8.1",
     "@biomejs/biome": "^2.4.15",
-    "@changesets/cli": "^2.31.0",
-    "@types/node": "^25.9.1",
+    "@changesets/cli": "^2.27.11",
+    "@earendil-works/pi-ai": "0.80.3",
+    "@earendil-works/pi-coding-agent": "0.80.3",
+    "@earendil-works/pi-tui": "0.80.3",
+    "@golevelup/ts-vitest": "^4.0.0",
+    "@types/node": "^25.0.10",
     "husky": "^9.1.7",
-    "typescript": "^6.0.3",
-    "vitest": "^4.1.7"
+    "memfs": "^4.57.2",
+    "ts-json-schema-generator": "^2.9.0",
+    "typebox": "1.1.38",
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.5"
+  },
+  "pnpm": {
+    "overrides": {
+      "@earendil-works/pi-ai": "$@earendil-works/pi-coding-agent",
+      "@earendil-works/pi-tui": "$@earendil-works/pi-coding-agent"
+    }
   },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "lint": "biome check",
+    "format": "biome check --write",
+    "gen:schema": "ts-json-schema-generator --path extensions/processes/config/types.ts --type ProcessConfig --no-type-check -o schema.json",
+    "check:schema": "ts-json-schema-generator --path extensions/processes/config/types.ts --type ProcessConfig --no-type-check -o /tmp/pi-processes-schema-check.json && diff -q schema.json /tmp/pi-processes-schema-check.json",
+    "check:lockfile": "pnpm install --frozen-lockfile --ignore-scripts",
+    "prepare": "[ -d .git ] && husky || true",
+    "changeset": "changeset",
+    "version": "changeset version",
+    "test": "vitest run",
+    "test:e2e": "vitest run --config vitest.e2e.config.ts",
+    "release": "pnpm changeset publish"
+  },
+  "packageManager": "pnpm@10.26.1",
   "peerDependenciesMeta": {
     "@earendil-works/pi-ai": {
       "optional": true
@@ -65,15 +102,5 @@
     "typebox": {
       "optional": true
     }
-  },
-  "scripts": {
-    "typecheck": "tsc --noEmit",
-    "lint": "biome check",
-    "format": "biome check --write",
-    "check:lockfile": "pnpm install --frozen-lockfile --ignore-scripts",
-    "changeset": "changeset",
-    "version": "changeset version",
-    "test": "vitest run",
-    "release": "pnpm changeset publish"
   }
-}
+}

package/schema.json

@@ -0,0 +1,134 @@
+{
+  "$ref": "#/definitions/ProcessConfig",
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "definitions": {
+    "ExecutionConfig": {
+      "additionalProperties": false,
+      "properties": {
+        "shellPath": {
+          "description": "Absolute shell executable used to run process commands.",
+          "type": "string"
+        }
+      },
+      "type": "object"
+    },
+    "FollowConfig": {
+      "additionalProperties": false,
+      "properties": {
+        "autoHideOnFinish": {
+          "description": "Hide process log interfaces when all managed processes finish.",
+          "type": "boolean"
+        },
+        "enabledByDefault": {
+          "description": "Open process log interfaces in follow mode by default.",
+          "type": "boolean"
+        }
+      },
+      "type": "object"
+    },
+    "InterceptionConfig": {
+      "additionalProperties": false,
+      "properties": {
+        "blockBackgroundCommands": {
+          "description": "Block shell background patterns and redirect the agent to the process tool.",
+          "type": "boolean"
+        }
+      },
+      "type": "object"
+    },
+    "OutputConfig": {
+      "additionalProperties": false,
+      "properties": {
+        "defaultTailLines": {
+          "description": "Default number of recent lines returned by the process output action.",
+          "type": "number"
+        },
+        "maxOutputBytes": {
+          "description": "Maximum bytes retained by each process log interface.",
+          "type": "number"
+        },
+        "maxOutputLines": {
+          "description": "Maximum lines retained by process log interfaces.",
+          "type": "number"
+        }
+      },
+      "type": "object"
+    },
+    "ProcessConfig": {
+      "additionalProperties": false,
+      "description": "User-facing pi-processes settings stored on disk.",
+      "properties": {
+        "$schema": {
+          "description": "JSON Schema URL used by editors for validation and autocomplete.",
+          "type": "string"
+        },
+        "execution": {
+          "$ref": "#/definitions/ExecutionConfig",
+          "description": "Process execution settings."
+        },
+        "follow": {
+          "$ref": "#/definitions/FollowConfig",
+          "description": "Live log follow behavior."
+        },
+        "interception": {
+          "$ref": "#/definitions/InterceptionConfig",
+          "description": "Shell-command interception settings."
+        },
+        "output": {
+          "$ref": "#/definitions/OutputConfig",
+          "description": "Process output retention settings."
+        },
+        "processList": {
+          "$ref": "#/definitions/ProcessListConfig",
+          "description": "Process overview and log viewport settings."
+        },
+        "version": {
+          "description": "Config migration marker written after v0.10.0 settings migration.",
+          "type": "string"
+        },
+        "widget": {
+          "$ref": "#/definitions/WidgetConfig",
+          "description": "Dock and status widget settings."
+        }
+      },
+      "type": "object"
+    },
+    "ProcessListConfig": {
+      "additionalProperties": false,
+      "properties": {
+        "maxPreviewLines": {
+          "description": "Maximum log rows displayed in the overview preview and logs overlay.",
+          "type": "number"
+        },
+        "maxVisibleProcesses": {
+          "description": "Maximum process rows displayed in the overview before scrolling.",
+          "type": "number"
+        }
+      },
+      "type": "object"
+    },
+    "WidgetConfig": {
+      "additionalProperties": false,
+      "properties": {
+        "dockDefaultState": {
+          "description": "Initial visibility of the process dock.",
+          "enum": [
+            "closed",
+            "collapsed",
+            "expanded"
+          ],
+          "type": "string"
+        },
+        "dockHeight": {
+          "description": "Number of log rows displayed in the expanded process dock.",
+          "type": "number"
+        },
+        "showStatusWidget": {
+          "description": "Show a one-line process summary below the editor.",
+          "type": "boolean"
+        }
+      },
+      "type": "object"
+    }
+  }
+}