@aliou/pi-processes 0.9.4 → 0.10.0

package/extensions/processes/settings/build-sections.ts

@@ -0,0 +1,420 @@
+/**
+ * Build settings sections for the processes package.
+ *
+ * The first-level view stays focused. Extension-specific groups open focused
+ * detail panels instead of expanding every setting into one long list.
+ */
+
+import {
+  type Scope,
+  SettingsDetailEditor,
+  type SettingsSection,
+  type SettingsTheme,
+} from "@aliou/pi-utils-settings";
+import type { SettingItem } from "@earendil-works/pi-tui";
+
+import type { ProcessConfig, ProcessProtocolConfig } from "../config";
+
+interface BuildSectionsContext {
+  setDraft: (config: ProcessConfig) => void;
+  scope: Scope;
+  isInherited: (path: string) => boolean;
+  theme: SettingsTheme;
+}
+
+export function buildSections(
+  tabConfig: ProcessConfig | null,
+  resolved: ProcessProtocolConfig,
+  ctx: BuildSectionsContext,
+): SettingsSection[] {
+  const scopedConfig = structuredClone(tabConfig ?? {}) as ProcessConfig;
+
+  const coreSection: SettingsSection = {
+    label: "Core",
+    items: [
+      buildShellPathItem(scopedConfig, resolved, ctx),
+      boolItem(
+        "interception.blockBackgroundCommands",
+        "Block background commands",
+        "Block shell background patterns (&, nohup, disown, setsid) in bash tool calls. Redirects to the process tool instead.",
+        scopedConfig.interception?.blockBackgroundCommands,
+        resolved.interception.blockBackgroundCommands,
+      ),
+    ],
+  };
+
+  const logsSection: SettingsSection = {
+    label: "Interfaces",
+    items: [
+      boolItem(
+        "widget.showStatusWidget",
+        "Status widget",
+        "Show a one-line summary of managed processes below the editor.",
+        scopedConfig.widget?.showStatusWidget,
+        resolved.widget.showStatusWidget,
+      ),
+      buildOverviewDetailItem(scopedConfig, resolved, ctx),
+      buildLogsDetailItem(scopedConfig, resolved, ctx),
+      buildDockDetailItem(scopedConfig, resolved, ctx),
+    ],
+  };
+
+  return [coreSection, logsSection];
+}
+
+function buildShellPathItem(
+  scopedConfig: ProcessConfig,
+  resolved: ProcessProtocolConfig,
+  ctx: BuildSectionsContext,
+): SettingItem {
+  const shellPath =
+    scopedConfig.execution?.shellPath ?? resolved.execution.shellPath ?? "";
+  const display = scopedConfig.execution?.shellPath
+    ? scopedConfig.execution.shellPath
+    : resolved.execution.shellPath
+      ? `inherited: ${resolved.execution.shellPath}`
+      : "(default)";
+
+  return {
+    id: "execution.shellPath.details",
+    label: "Shell path",
+    currentValue: display,
+    description:
+      "Open focused settings for the shell executable used by process commands.",
+    submenu: (_current, done) => {
+      const current = scopedConfig;
+      let nextShellPath = shellPath;
+
+      const syncDraft = () => {
+        ctx.setDraft({
+          ...current,
+          execution: {
+            ...current.execution,
+            shellPath: nextShellPath,
+          },
+        });
+      };
+
+      return new SettingsDetailEditor({
+        title: "Shell path",
+        theme: ctx.theme,
+        fields: [
+          {
+            id: "execution.shellPath.value",
+            type: "text",
+            label: "Shell path",
+            description:
+              "Path to the shell executable. Leave empty to use the system default.",
+            getValue: () => nextShellPath,
+            setValue: (value) => {
+              nextShellPath = value;
+              syncDraft();
+            },
+            displayValue: (value) => value || "(default)",
+          },
+        ],
+        getDoneSummary: () => nextShellPath || "(default)",
+        onDone: (summary) => done(summary),
+      });
+    },
+  };
+}
+
+function buildOverviewDetailItem(
+  scopedConfig: ProcessConfig,
+  resolved: ProcessProtocolConfig,
+  ctx: BuildSectionsContext,
+): SettingItem {
+  const maxVisibleProcesses =
+    scopedConfig.processList?.maxVisibleProcesses ??
+    resolved.processList.maxVisibleProcesses;
+
+  return {
+    id: "overview.details",
+    label: "Overview panel",
+    currentValue: `${maxVisibleProcesses} rows`,
+    description:
+      "Open focused settings for the /ps overview panel visible row count.",
+    submenu: (_current, done) => {
+      const current = scopedConfig;
+      let nextMaxVisible = String(maxVisibleProcesses);
+
+      const syncDraft = () => {
+        const updated: ProcessConfig = {
+          ...current,
+          processList: {
+            ...current.processList,
+            maxVisibleProcesses: parsePositiveInt(nextMaxVisible),
+          },
+        };
+        ctx.setDraft(updated);
+      };
+
+      return new SettingsDetailEditor({
+        title: "Overview panel",
+        theme: ctx.theme,
+        fields: [
+          {
+            id: "overview.maxVisibleProcesses",
+            type: "text",
+            label: "Visible rows",
+            description:
+              "Maximum process rows shown at once in the /ps overview. The list scrolls past this.",
+            getValue: () => nextMaxVisible,
+            setValue: (value) => {
+              nextMaxVisible = value;
+              syncDraft();
+            },
+            validate: positiveIntegerError,
+          },
+        ],
+        getDoneSummary: () => `${parsePositiveInt(nextMaxVisible)} rows`,
+        onDone: (summary) => done(summary),
+      });
+    },
+  };
+}
+
+function buildLogsDetailItem(
+  scopedConfig: ProcessConfig,
+  resolved: ProcessProtocolConfig,
+  ctx: BuildSectionsContext,
+): SettingItem {
+  const viewportRows =
+    scopedConfig.processList?.maxPreviewLines ??
+    resolved.processList.maxPreviewLines;
+  const historyLines =
+    scopedConfig.output?.maxOutputLines ?? resolved.output.maxOutputLines;
+  const historyBudgetMb = Math.max(
+    1,
+    Math.round(
+      (scopedConfig.output?.maxOutputBytes ?? resolved.output.maxOutputBytes) /
+        (1024 * 1024),
+    ),
+  );
+  const followByDefault =
+    scopedConfig.follow?.enabledByDefault ?? resolved.follow.enabledByDefault;
+
+  return {
+    id: "logs.details",
+    label: "Logs overlay",
+    currentValue: `${historyLines} lines · ${historyBudgetMb} MB · ${viewportRows} rows · ${followByDefault ? "follow" : "manual"}`,
+    description:
+      "Open focused settings for /ps:logs tabs, history, viewport, and follow behavior.",
+    submenu: (_current, done) => {
+      const current = scopedConfig;
+      let nextViewportRows = String(viewportRows);
+      let nextHistoryLines = String(historyLines);
+      let nextHistoryBudgetMb = String(historyBudgetMb);
+      let historyBudgetEdited = false;
+      let nextFollowByDefault = followByDefault;
+      let nextAutoHideOnFinish =
+        scopedConfig.follow?.autoHideOnFinish ??
+        resolved.follow.autoHideOnFinish;
+
+      const syncDraft = () => {
+        const output = {
+          ...current.output,
+          maxOutputLines: parsePositiveInt(nextHistoryLines),
+        };
+        if (historyBudgetEdited) {
+          output.maxOutputBytes =
+            parsePositiveInt(nextHistoryBudgetMb) * 1024 * 1024;
+        }
+        const updated: ProcessConfig = {
+          ...current,
+          processList: {
+            ...current.processList,
+            maxPreviewLines: parsePositiveInt(nextViewportRows),
+          },
+          output,
+          follow: {
+            ...current.follow,
+            enabledByDefault: nextFollowByDefault,
+            autoHideOnFinish: nextAutoHideOnFinish,
+          },
+        };
+        ctx.setDraft(updated);
+      };
+
+      return new SettingsDetailEditor({
+        title: "Logs overlay",
+        theme: ctx.theme,
+        fields: [
+          {
+            id: "logs.viewportRows",
+            type: "text",
+            label: "Viewport rows",
+            description:
+              "Maximum log rows rendered in the /ps:logs overlay body.",
+            getValue: () => nextViewportRows,
+            setValue: (value) => {
+              nextViewportRows = value;
+              syncDraft();
+            },
+            validate: positiveIntegerError,
+          },
+          {
+            id: "logs.historyLines",
+            type: "text",
+            label: "History lines",
+            description:
+              "Maximum existing log lines loaded when opening a process log.",
+            getValue: () => nextHistoryLines,
+            setValue: (value) => {
+              nextHistoryLines = value;
+              syncDraft();
+            },
+            validate: positiveIntegerError,
+          },
+          {
+            id: "logs.historyBudgetMb",
+            type: "text",
+            label: "History budget (MB)",
+            description:
+              "Maximum in-memory log history retained per process view.",
+            getValue: () => nextHistoryBudgetMb,
+            setValue: (value) => {
+              nextHistoryBudgetMb = value;
+              historyBudgetEdited = true;
+              syncDraft();
+            },
+            validate: positiveIntegerError,
+          },
+          {
+            id: "logs.followByDefault",
+            type: "boolean",
+            label: "Follow by default",
+            description: "Open process logs pinned to the latest output.",
+            getValue: () => nextFollowByDefault,
+            setValue: (value) => {
+              nextFollowByDefault = value;
+              syncDraft();
+            },
+          },
+          {
+            id: "logs.autoHideOnFinish",
+            type: "boolean",
+            label: "Auto-hide on finish",
+            description:
+              "Close the logs overlay when all processes have finished.",
+            getValue: () => nextAutoHideOnFinish,
+            setValue: (value) => {
+              nextAutoHideOnFinish = value;
+              syncDraft();
+            },
+          },
+        ],
+        getDoneSummary: () =>
+          `${parsePositiveInt(nextHistoryLines)} lines · ${parsePositiveInt(nextHistoryBudgetMb)} MB · ${parsePositiveInt(nextViewportRows)} rows · ${nextFollowByDefault ? "follow" : "manual"}`,
+        onDone: (summary) => done(summary),
+      });
+    },
+  };
+}
+
+function buildDockDetailItem(
+  scopedConfig: ProcessConfig,
+  resolved: ProcessProtocolConfig,
+  ctx: BuildSectionsContext,
+): SettingItem {
+  const dockDefaultState =
+    scopedConfig.widget?.dockDefaultState ?? resolved.widget.dockDefaultState;
+  const dockHeight =
+    scopedConfig.widget?.dockHeight ?? resolved.widget.dockHeight;
+
+  return {
+    id: "dock.details",
+    label: "Dock",
+    currentValue: `${dockDefaultState} · ${dockHeight} log lines`,
+    description:
+      "Open focused settings for the /ps:dock widget above the editor.",
+    submenu: (_current, done) => {
+      const current = scopedConfig;
+      let nextDockDefaultState = dockDefaultState;
+      let nextDockHeight = String(dockHeight);
+
+      const syncDraft = () => {
+        ctx.setDraft({
+          ...current,
+          widget: {
+            ...current.widget,
+            dockDefaultState: nextDockDefaultState,
+            dockHeight: parsePositiveInt(nextDockHeight),
+          },
+        });
+      };
+
+      return new SettingsDetailEditor({
+        title: "Dock",
+        theme: ctx.theme,
+        fields: [
+          {
+            id: "dock.defaultState",
+            type: "enum",
+            label: "Default state",
+            description: "Initial state, also used when a new process starts.",
+            options: ["closed", "collapsed", "expanded"],
+            getValue: () => nextDockDefaultState,
+            setValue: (value) => {
+              nextDockDefaultState = value as
+                | "closed"
+                | "collapsed"
+                | "expanded";
+              syncDraft();
+            },
+          },
+          {
+            id: "dock.height",
+            type: "text",
+            label: "Log lines displayed",
+            description:
+              "Maximum log/content rows shown inside the dock. Border, title, process strip, and separator are added on top.",
+            getValue: () => nextDockHeight,
+            setValue: (value) => {
+              nextDockHeight = value;
+              syncDraft();
+            },
+            validate: positiveIntegerError,
+          },
+        ],
+        getDoneSummary: () =>
+          `${nextDockDefaultState} · ${parsePositiveInt(nextDockHeight)} log lines`,
+        onDone: (summary) => done(summary),
+      });
+    },
+  };
+}
+
+function boolItem(
+  id: string,
+  label: string,
+  description: string,
+  scopedValue: boolean | undefined,
+  resolvedValue: boolean,
+): SettingItem {
+  const display =
+    scopedValue === undefined
+      ? `inherited: ${resolvedValue ? "on" : "off"}`
+      : scopedValue
+        ? "on"
+        : "off";
+  return {
+    id,
+    label,
+    description,
+    currentValue: display,
+    values: ["on", "off"],
+  };
+}
+
+function positiveIntegerError(value: string): string | null {
+  return Number.isInteger(Number(value)) && Number(value) > 0
+    ? null
+    : "Enter a positive integer";
+}
+
+function parsePositiveInt(value: string): number {
+  const parsed = Number.parseInt(value, 10);
+  return Number.isNaN(parsed) || parsed <= 0 ? 1 : parsed;
+}

package/extensions/processes/settings/index.ts

@@ -0,0 +1,42 @@
+/**
+ * Settings registration for the processes extension.
+ *
+ * Uses @aliou/pi-utils-settings infrastructure for a /ps:settings command
+ * with Global/Local/Memory tabs and sectioned settings.
+ */
+
+import {
+  registerSettingsCommand,
+  type SettingsSection,
+} from "@aliou/pi-utils-settings";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+import type { ProcessConfig, ProcessProtocolConfig } from "../config";
+import { createSettingsConfigStore } from "../config";
+import { applySettingChange } from "./apply-setting-change";
+import { buildSections } from "./build-sections";
+
+export function registerProcessSettings(pi: ExtensionAPI): void {
+  const configStore = createSettingsConfigStore();
+
+  registerSettingsCommand<ProcessConfig, ProcessProtocolConfig>(pi, {
+    commandName: "ps:settings",
+    title: "Processes Settings",
+    configStore,
+    buildSections: (
+      tabConfig: ProcessConfig | null,
+      resolved: ProcessProtocolConfig,
+      ctx,
+    ): SettingsSection[] => {
+      return buildSections(tabConfig, resolved, {
+        setDraft: ctx.setDraft,
+        scope: ctx.scope,
+        isInherited: ctx.isInherited,
+        theme: ctx.theme,
+      });
+    },
+    onSettingChange: (id, newValue, config) => {
+      return applySettingChange(id, newValue, config);
+    },
+  });
+}

package/extensions/processes/tools/clear/index.ts

@@ -0,0 +1,21 @@
+import type { ProcessManager } from "../../../../src/manager";
+
+export interface ClearDetails {
+  action: "clear";
+  cleared: number;
+}
+
+export function executeClear(manager: ProcessManager): ClearDetails {
+  return {
+    action: "clear",
+    cleared: manager.clearFinished(),
+  };
+}
+
+export function formatClearDetails(details: ClearDetails): string {
+  if (details.cleared === 0) {
+    return "No finished background processes to clear.";
+  }
+
+  return `Cleared ${details.cleared} finished background ${details.cleared === 1 ? "process" : "processes"}.`;
+}

package/extensions/processes/tools/clear/render.ts

@@ -0,0 +1,40 @@
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import { Container, Text } from "@earendil-works/pi-tui";
+import { ProcessActionTitle } from "../components";
+import type { ProcessesParamsType } from "../schema";
+import { formatCount } from "../utils";
+import type { ClearDetails } from ".";
+
+export function buildHeader(
+  _args: ProcessesParamsType,
+  theme: Theme,
+): Container {
+  const header = new Container();
+  header.addChild(new ProcessActionTitle("clear", theme));
+  return header;
+}
+
+export function buildExpanded(details: ClearDetails, theme: Theme): Container {
+  return buildCollapsed(details, theme);
+}
+
+export function buildCollapsed(details: ClearDetails, theme: Theme): Container {
+  const container = new Container();
+  const tone = details.cleared > 0 ? "success" : "muted";
+  container.addChild(
+    new Text(
+      theme.fg(tone, `${formatCount(details.cleared, "process")} cleared`),
+      0,
+      0,
+    ),
+  );
+  return container;
+}
+
+export function buildFooter(
+  _details: ClearDetails,
+  _options: { expanded?: boolean },
+  _theme: Theme,
+): Container | null {
+  return null;
+}

package/extensions/processes/tools/components/index.ts

@@ -0,0 +1,4 @@
+export { ProcessActionHeader } from "./process-action-header";
+export { ProcessActionTitle } from "./process-action-title";
+export { ToolLayout } from "./tool-layout";
+export { buildMatcherLine, formatPatternForDisplay } from "./watch";

package/extensions/processes/tools/components/process-action-header.ts

@@ -0,0 +1,31 @@
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import { Container, Spacer } from "@earendil-works/pi-tui";
+import type { ProcessesParamsType } from "../schema";
+import { buildCommandField } from "../utils";
+import { ProcessActionTitle } from "./process-action-title";
+
+export class ProcessActionHeader extends Container {
+  constructor(
+    args: ProcessesParamsType,
+    theme: Theme,
+    options: { action: string; suffix?: string; expanded?: boolean },
+  ) {
+    super();
+
+    this.addChild(
+      new ProcessActionTitle(options.action, theme, options.suffix),
+    );
+
+    if (args.command) {
+      if (options.expanded) {
+        this.addChild(new Spacer(1));
+      }
+
+      this.addChild(
+        buildCommandField(args.command, theme, {
+          truncate: !options.expanded,
+        }),
+      );
+    }
+  }
+}

package/extensions/processes/tools/components/process-action-title.ts

@@ -0,0 +1,17 @@
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import { Text } from "@earendil-works/pi-tui";
+
+export class ProcessActionTitle extends Text {
+  constructor(action: string, theme: Theme, suffix?: string) {
+    const parts = [
+      theme.fg("toolTitle", theme.bold("Process:")),
+      theme.fg("muted", action),
+    ];
+
+    if (suffix) {
+      parts.push(suffix);
+    }
+
+    super(parts.join(" "), 0, 0);
+  }
+}

package/extensions/processes/tools/components/tool-layout.ts

@@ -0,0 +1,70 @@
+import { type Component, Spacer } from "@earendil-works/pi-tui";
+
+export class ToolLayout implements Component {
+  private header: Component | null = null;
+  private body: Component | null = null;
+  private footer: Component | null = null;
+  private spacing = true;
+
+  setHeader(component: Component | null): this {
+    this.header = component;
+    return this;
+  }
+
+  setBody(component: Component | null): this {
+    this.body = component;
+    return this;
+  }
+
+  setFooter(component: Component | null): this {
+    this.footer = component;
+    return this;
+  }
+
+  withSectionSpacing(enabled?: boolean): this {
+    this.spacing = Boolean(enabled);
+    return this;
+  }
+
+  invalidate(): void {
+    for (const component of this.sections()) {
+      component.invalidate?.();
+    }
+  }
+
+  render(width: number): string[] {
+    const lines: string[] = [];
+
+    for (const component of this.sections()) {
+      lines.push(...component.render(width));
+    }
+
+    return lines;
+  }
+
+  private sections(): Component[] {
+    const sections: Component[] = [];
+
+    if (this.header) {
+      sections.push(this.header);
+    }
+
+    if (this.spacing && this.header && this.body) {
+      sections.push(new Spacer(1));
+    }
+
+    if (this.body) {
+      sections.push(this.body);
+    }
+
+    if (this.spacing && (this.header || this.body) && this.footer) {
+      sections.push(new Spacer(1));
+    }
+
+    if (this.footer) {
+      sections.push(this.footer);
+    }
+
+    return sections;
+  }
+}

package/extensions/processes/tools/components/watch.ts

@@ -0,0 +1,53 @@
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import { Text } from "@earendil-works/pi-tui";
+
+import type { LogMatcherConfig } from "../../notifications/registry";
+
+export function buildMatcherLine(
+  matcher: LogMatcherConfig,
+  theme: Theme,
+  prefix = "",
+): Text {
+  const mode = matcher.mode ?? "literal";
+  const stream = matcher.stream ?? "both";
+  const repeat = matcher.repeat ? " (repeat)" : "";
+  const on = matcher.on ?? "turn";
+  const attentionTone =
+    on === "turn" ? "warning" : on === "context" ? "success" : "muted";
+
+  return new Text(
+    [
+      prefix,
+      theme.fg("muted", `[${stream}] ${mode}`),
+      "  ",
+      theme.bold(theme.fg(attentionTone, `${on}${repeat}`)),
+      "  ",
+      theme.fg("accent", formatPatternForDisplay(matcher.pattern)),
+    ].join(""),
+    0,
+    0,
+  );
+}
+
+export function formatPatternForDisplay(pattern: string): string {
+  let formatted = "";
+
+  for (const character of pattern) {
+    if (character === "\r") {
+      formatted += "\\r";
+    } else if (character === "\n") {
+      formatted += "\\n";
+    } else if (character === "\t") {
+      formatted += "\\t";
+    } else {
+      const codePoint = character.codePointAt(0) ?? 0;
+      if (codePoint <= 0x1f || (codePoint >= 0x7f && codePoint <= 0x9f)) {
+        formatted += `\\x${codePoint.toString(16).padStart(2, "0")}`;
+      } else {
+        formatted += character;
+      }
+    }
+  }
+
+  return formatted;
+}