@aliou/pi-processes 0.9.4 → 0.10.0

package/extensions/processes/components/overview-panel.ts

@@ -0,0 +1,177 @@
+import type { Component } from "@earendil-works/pi-tui";
+import { truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
+
+export interface OverviewPanelOptions {
+  title?: string;
+  headerLeft?: string;
+  headerRight?: string;
+  body: Component;
+  footer?: Component;
+  borderStyle?: (text: string) => string;
+  titleStyle?: (text: string) => string;
+  metaStyle?: (text: string) => string;
+  padding?: number;
+}
+
+const BORDER = {
+  tl: "╭",
+  tr: "╮",
+  bl: "╰",
+  br: "╯",
+  left: "│",
+  right: "│",
+  footSep: "├",
+  footEnd: "┤",
+  h: "─",
+};
+
+/**
+ * Local vendored variant of @aliou/pi-utils-ui Panel for /ps.
+ *
+ * The upstream Panel only supports a centered title. The overview needs
+ * left/center/right header slots. Keep this small and local so it can be
+ * upstreamed later without changing the rest of the /ps component.
+ */
+export class OverviewPanel implements Component {
+  private readonly title: string;
+  private readonly headerLeft: string;
+  private readonly headerRight: string;
+  private readonly body: Component;
+  private readonly footer?: Component;
+  private readonly borderStyle: (text: string) => string;
+  private readonly titleStyle: (text: string) => string;
+  private readonly metaStyle: (text: string) => string;
+  private readonly padding: number;
+
+  constructor(options: OverviewPanelOptions) {
+    this.title = options.title ?? "";
+    this.headerLeft = options.headerLeft ?? "";
+    this.headerRight = options.headerRight ?? "";
+    this.body = options.body;
+    this.footer = options.footer;
+    this.borderStyle = options.borderStyle ?? ((text) => text);
+    this.titleStyle = options.titleStyle ?? ((text) => text);
+    this.metaStyle = options.metaStyle ?? ((text) => text);
+    this.padding = options.padding ?? 1;
+  }
+
+  render(width: number): string[] {
+    const lines: string[] = [];
+    const innerWidth = Math.max(0, width - 2);
+    const contentWidth = Math.max(0, innerWidth - this.padding * 2);
+
+    lines.push(this.renderHeader(innerWidth));
+
+    for (let i = 0; i < this.padding; i++) {
+      lines.push(this.borderLine(innerWidth));
+    }
+
+    for (const line of this.body.render(contentWidth)) {
+      lines.push(this.contentLine(innerWidth, line));
+    }
+
+    for (let i = 0; i < this.padding; i++) {
+      lines.push(this.borderLine(innerWidth));
+    }
+
+    if (this.footer) {
+      lines.push(
+        this.borderStyle(BORDER.footSep) +
+          this.borderStyle(BORDER.h.repeat(innerWidth)) +
+          this.borderStyle(BORDER.footEnd),
+      );
+      for (const line of this.footer.render(contentWidth)) {
+        lines.push(this.contentLine(innerWidth, line));
+      }
+    }
+
+    lines.push(
+      this.borderStyle(BORDER.bl) +
+        this.borderStyle(BORDER.h.repeat(innerWidth)) +
+        this.borderStyle(BORDER.br),
+    );
+
+    return lines;
+  }
+
+  invalidate(): void {
+    this.body.invalidate();
+    this.footer?.invalidate();
+  }
+
+  private renderHeader(innerWidth: number): string {
+    if (innerWidth <= 0) {
+      return this.borderStyle(BORDER.tl) + this.borderStyle(BORDER.tr);
+    }
+
+    const leftRaw = this.headerLeft ? ` ${this.headerLeft} ` : "";
+    const rightRaw = this.headerRight ? ` ${this.headerRight} ` : "";
+    const centerRaw = this.title ? ` ${this.title} ` : "";
+
+    const center = this.titleStyle(truncateToWidth(centerRaw, innerWidth, ""));
+    const centerWidth = visibleWidth(center);
+    const centerStart = Math.max(0, Math.floor((innerWidth - centerWidth) / 2));
+
+    const leftBudget = centerStart;
+    const left = this.metaStyle(truncateToWidth(leftRaw, leftBudget, ""));
+
+    const centerEnd = centerStart + centerWidth;
+    const rightBudget = Math.max(0, innerWidth - centerEnd);
+    const right = this.metaStyle(truncateToWidth(rightRaw, rightBudget, ""));
+    const rightWidth = visibleWidth(right);
+
+    let output = "";
+    let cursor = 0;
+    const appendRuleTo = (target: number) => {
+      if (target <= cursor) return;
+      output += this.borderStyle(BORDER.h.repeat(target - cursor));
+      cursor = target;
+    };
+    const appendSegment = (segment: string) => {
+      output += segment;
+      cursor += visibleWidth(segment);
+    };
+
+    appendSegment(left);
+    appendRuleTo(centerStart);
+    appendSegment(center);
+    if (rightWidth > 0) {
+      const rightStart = Math.max(0, innerWidth - rightWidth);
+      if (rightStart >= cursor) {
+        appendRuleTo(rightStart);
+        appendSegment(right);
+      }
+    }
+    appendRuleTo(innerWidth);
+
+    return (
+      this.borderStyle(BORDER.tl) +
+      truncateToWidth(output, innerWidth, "", true) +
+      this.borderStyle(BORDER.tr)
+    );
+  }
+
+  private borderLine(innerWidth: number): string {
+    return (
+      this.borderStyle(BORDER.left) +
+      " ".repeat(innerWidth) +
+      this.borderStyle(BORDER.right)
+    );
+  }
+
+  private contentLine(innerWidth: number, content: string): string {
+    const padded =
+      " ".repeat(this.padding) +
+      truncateToWidth(
+        content,
+        Math.max(0, innerWidth - this.padding * 2),
+        "",
+        true,
+      ) +
+      " ".repeat(this.padding);
+    const inner = truncateToWidth(padded, innerWidth, "", true);
+    return (
+      this.borderStyle(BORDER.left) + inner + this.borderStyle(BORDER.right)
+    );
+  }
+}

package/extensions/processes/config/defaults.ts

@@ -0,0 +1,28 @@
+import type { ProcessProtocolConfig } from "./types";
+
+export const DEFAULT_CONFIG: ProcessProtocolConfig = {
+  execution: {
+    shellPath: undefined,
+  },
+  interception: {
+    blockBackgroundCommands: false,
+  },
+  processList: {
+    maxPreviewLines: 12,
+    maxVisibleProcesses: 8,
+  },
+  output: {
+    defaultTailLines: 100,
+    maxOutputLines: 200,
+    maxOutputBytes: 4 * 1024 * 1024,
+  },
+  follow: {
+    enabledByDefault: true,
+    autoHideOnFinish: true,
+  },
+  widget: {
+    showStatusWidget: false,
+    dockDefaultState: "closed",
+    dockHeight: 12,
+  },
+};

package/extensions/processes/config/index.ts

@@ -0,0 +1,13 @@
+export { DEFAULT_CONFIG } from "./defaults";
+export {
+  configLoader,
+  createSettingsConfigStore,
+  drainImportMessages,
+  loadProcessConfig,
+} from "./loader";
+export { migrations } from "./migrations";
+export {
+  PROCESS_CONFIG_SCHEMA_URL,
+  PROCESS_CONFIG_SCHEMA_VERSION,
+} from "./schema";
+export type { ProcessConfig, ProcessProtocolConfig } from "./types";

package/extensions/processes/config/loader.ts

@@ -0,0 +1,62 @@
+import {
+  ConfigLoader,
+  type ConfigStore,
+  type Scope,
+} from "@aliou/pi-utils-settings";
+import { DEFAULT_CONFIG } from "./defaults";
+import { importLegacyProcessConfig, migrations } from "./migrations";
+import { PROCESS_CONFIG_SCHEMA_URL } from "./schema";
+import type { ProcessConfig, ProcessProtocolConfig } from "./types";
+
+/**
+ * Pending messages from the one-time legacy config import. Drained alongside
+ * ConfigLoader migration messages in registerMigrationMessageNotifications.
+ */
+const importMessages: string[] = [];
+
+export async function loadProcessConfig(): Promise<void> {
+  const result = await importLegacyProcessConfig();
+  if (result.kind === "imported") {
+    importMessages.push(
+      `Imported pi-processes settings from the legacy 0.9.4 config file at ${result.legacyPath}. Your existing settings were preserved and migrated to the current schema.`,
+    );
+  } else if (result.kind === "invalid") {
+    importMessages.push(
+      `Found a legacy 0.9.4 config file at ${result.legacyPath}, but it is not a readable JSON object (${result.error}). It was left in place and the current settings were loaded from defaults instead.`,
+    );
+  }
+  await configLoader.load();
+}
+
+/** Drain (remove and return) all pending legacy-import messages. */
+export function drainImportMessages(): string[] {
+  return importMessages.splice(0);
+}
+
+export const configLoader = new ConfigLoader<
+  ProcessConfig,
+  ProcessProtocolConfig
+>("processes", DEFAULT_CONFIG, {
+  scopes: ["global", "local", "memory"],
+  migrations,
+  schemaUrl: PROCESS_CONFIG_SCHEMA_URL,
+});
+
+export function createSettingsConfigStore(): ConfigStore<
+  ProcessConfig,
+  ProcessProtocolConfig
+> {
+  return {
+    save: (scope, config) => configLoader.save(scope, config),
+    getConfig: () => configLoader.getConfig(),
+    getRawConfig: (scope) => configLoader.getRawConfig(scope),
+    hasScope: (scope) => configLoader.hasScope(scope),
+    hasConfig: (scope) => configLoader.hasConfig(scope),
+    getEnabledScopes: () => {
+      const enabled = new Set(configLoader.getEnabledScopes());
+      return (["global", "local", "memory"] as Scope[]).filter((scope) =>
+        enabled.has(scope),
+      );
+    },
+  };
+}

package/extensions/processes/config/migrations/000-import-legacy-process-config.ts

@@ -0,0 +1,113 @@
+import { existsSync } from "node:fs";
+import { constants, copyFile, readFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+
+const { COPYFILE_EXCL } = constants;
+
+/**
+ * Config namespace used by pi-processes before 0.10.0.
+ *
+ * 0.9.4 shipped as the "process" extension, so its settings lived at
+ * `~/.pi/agent/extensions/process.json`. The rewrite renamed the namespace
+ * to "processes" (`processes.json`). ConfigLoader derives the file path
+ * strictly from the extension name, with no alias or legacy support.
+ */
+const LEGACY_EXTENSION_NAME = "process";
+const EXTENSION_NAME = "processes";
+
+/**
+ * Outcome of {@link importLegacyProcessConfig}.
+ *
+ * - `imported`: legacy file was copied to the current path. ConfigLoader should
+ *   load the new file and run the `001` schema migration on real 0.9.4 data.
+ * - `skipped`: nothing to import (no legacy file, or current file already
+ *   exists). ConfigLoader proceeds normally.
+ * - `invalid`: the legacy file exists but is not a readable JSON object. The
+ *   copy is **not** performed, so ConfigLoader falls back to defaults instead
+ *   of inheriting a corrupt config. The caller can surface a warning.
+ */
+export type LegacyImportResult =
+  | { kind: "imported"; legacyPath: string }
+  | { kind: "skipped" }
+  | { kind: "invalid"; legacyPath: string; error: string };
+
+/**
+ * One-time import of the legacy 0.9.4 config file.
+ *
+ * Before `ConfigLoader.load()` runs, copy the legacy `process.json` to the
+ * new `processes.json` if (and only if) the new file does not exist yet. The
+ * subsequent `001` schema migration then runs on the real 0.9.4 data instead
+ * of defaults.
+ *
+ * This cannot be a `Migration` array entry: `ConfigLoader.load()` only runs
+ * migrations after a file is successfully read, and returns `null` for a
+ * missing file. So a migration would never execute for the exact users it
+ * targets (those who still only have `process.json`). The pre-load step
+ * closes that gap.
+ *
+ * The legacy file is validated as a JSON object **before** copying. A corrupt
+ * `process.json` is left untouched; importing it would make ConfigLoader's
+ * `readFile` throw and silently fall back to defaults while a "settings
+ * preserved" message is shown -- which would be actively misleading.
+ *
+ * The copy uses `COPYFILE_EXCL` so a concurrent import (e.g. two Pi instances
+ * running in the same agent dir during an upgrade) cannot overwrite a
+ * `processes.json` the other instance just created. The loser treats that as
+ * "skipped".
+ *
+ * The legacy file is left in place as an accidental backup; it is ignored on
+ * subsequent loads because `processes.json` now exists.
+ *
+ * 0.9.4 only used the global scope (`~/.pi/agent/extensions/`), so only the
+ * global path is imported. No local-scope import is needed.
+ */
+export async function importLegacyProcessConfig(): Promise<LegacyImportResult> {
+  const agentDir = getAgentDir();
+  const legacyPath = resolve(
+    agentDir,
+    `extensions/${LEGACY_EXTENSION_NAME}.json`,
+  );
+  const currentPath = resolve(agentDir, `extensions/${EXTENSION_NAME}.json`);
+
+  if (!existsSync(legacyPath)) return { kind: "skipped" };
+  if (existsSync(currentPath)) return { kind: "skipped" };
+
+  // Validate the legacy file before copying. A corrupt process.json would
+  // make ConfigLoader.readFile throw and fall back to defaults; importing it
+  // anyway would let us show a misleading "settings preserved" message.
+  try {
+    const raw = await readFile(legacyPath, "utf-8");
+    const parsed: unknown = JSON.parse(raw);
+    if (
+      parsed === null ||
+      typeof parsed !== "object" ||
+      Array.isArray(parsed)
+    ) {
+      return {
+        kind: "invalid",
+        legacyPath,
+        error: "legacy config is not a JSON object",
+      };
+    }
+  } catch (error) {
+    return {
+      kind: "invalid",
+      legacyPath,
+      error: (error as Error).message,
+    };
+  }
+
+  // COPYFILE_EXCL makes the copy fail (EEXIST) if another instance created
+  // processes.json between our existence check and the copy. Treat that as a
+  // benign skip rather than a data-loss overwrite.
+  try {
+    await copyFile(legacyPath, currentPath, COPYFILE_EXCL);
+  } catch (error) {
+    const err = error as NodeJS.ErrnoException;
+    if (err.code === "EEXIST") return { kind: "skipped" };
+    throw error;
+  }
+
+  return { kind: "imported", legacyPath };
+}

package/extensions/processes/config/migrations/001-v0-9-4-to-v0-10-0-config.ts

@@ -0,0 +1,184 @@
+import type { Migration } from "@aliou/pi-utils-settings";
+
+import { PROCESS_CONFIG_SCHEMA_URL } from "../schema";
+import type { ProcessConfig } from "../types";
+
+type DockDefaultStateV094 = "hidden" | "collapsed";
+type DockDefaultStateV0100 = "closed" | "collapsed" | "expanded";
+
+export interface ConfigV094 {
+  $schema?: string;
+  execution?: {
+    shellPath?: string;
+  };
+  interception?: {
+    blockBackgroundCommands?: boolean;
+  };
+  processList?: {
+    maxPreviewLines?: number;
+    maxVisibleProcesses?: number;
+  };
+  output?: {
+    defaultTailLines?: number;
+    maxOutputLines?: number;
+  };
+  follow?: {
+    enabledByDefault?: boolean;
+    autoHideOnFinish?: boolean;
+  };
+  widget?: {
+    showStatusWidget?: boolean;
+    dockDefaultState?: DockDefaultStateV094;
+    dockHeight?: number;
+  };
+  keybindings?: Record<string, unknown>;
+}
+
+export interface ConfigV0100 {
+  $schema?: string;
+  execution?: {
+    shellPath?: string;
+  };
+  interception?: {
+    blockBackgroundCommands?: boolean;
+  };
+  processList?: {
+    maxPreviewLines?: number;
+    maxVisibleProcesses?: number;
+  };
+  output?: {
+    defaultTailLines?: number;
+    maxOutputLines?: number;
+  };
+  follow?: {
+    enabledByDefault?: boolean;
+    autoHideOnFinish?: boolean;
+  };
+  widget?: {
+    showStatusWidget?: boolean;
+    dockDefaultState?: DockDefaultStateV0100;
+    dockHeight?: number;
+  };
+}
+
+/**
+ * Config v0.9.4 -> v0.10.0 settings migration.
+ *
+ * Current sections with the same shape are copied through:
+ * execution, interception, processList, output, and follow.
+ *
+ * Widget settings changed:
+ * - widget.dockDefaultState "hidden" became "closed".
+ * - widget.dockHeight keeps the same key but means dock log rows.
+ * - widget.showStatusWidget is preserved (still controls the status widget).
+ */
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function setIfDefined<T extends object, K extends keyof T>(
+  target: T,
+  key: K,
+  value: T[K] | undefined,
+): void {
+  if (value !== undefined) target[key] = value;
+}
+
+function migrateDockDefaultState(
+  value: unknown,
+): DockDefaultStateV0100 | undefined {
+  if (value === "hidden") return "closed";
+  if (value === "closed" || value === "collapsed" || value === "expanded") {
+    return value;
+  }
+  return undefined;
+}
+
+export function needsConfigV094ToV0100Migration(
+  config: ProcessConfig,
+): boolean {
+  const root = config as Record<string, unknown>;
+  const widget = isRecord(root.widget) ? root.widget : undefined;
+
+  return widget?.dockDefaultState === "hidden";
+}
+
+export function migrateConfigV094ToV0100(config: ConfigV094): ConfigV0100 {
+  const next: ConfigV0100 = { $schema: PROCESS_CONFIG_SCHEMA_URL };
+
+  if (config.execution) {
+    const execution: NonNullable<ConfigV0100["execution"]> = {};
+    setIfDefined(execution, "shellPath", config.execution.shellPath);
+    setNonEmpty(next, "execution", execution);
+  }
+
+  if (config.interception) {
+    const interception: NonNullable<ConfigV0100["interception"]> = {};
+    setIfDefined(
+      interception,
+      "blockBackgroundCommands",
+      config.interception.blockBackgroundCommands,
+    );
+    setNonEmpty(next, "interception", interception);
+  }
+
+  if (config.processList) {
+    const processList: NonNullable<ConfigV0100["processList"]> = {};
+    setIfDefined(
+      processList,
+      "maxVisibleProcesses",
+      config.processList.maxVisibleProcesses,
+    );
+    setIfDefined(
+      processList,
+      "maxPreviewLines",
+      config.processList.maxPreviewLines,
+    );
+    setNonEmpty(next, "processList", processList);
+  }
+
+  if (config.output) {
+    const output: NonNullable<ConfigV0100["output"]> = {};
+    setIfDefined(output, "defaultTailLines", config.output.defaultTailLines);
+    setIfDefined(output, "maxOutputLines", config.output.maxOutputLines);
+    setNonEmpty(next, "output", output);
+  }
+
+  if (config.follow) {
+    const follow: NonNullable<ConfigV0100["follow"]> = {};
+    setIfDefined(follow, "enabledByDefault", config.follow.enabledByDefault);
+    setIfDefined(follow, "autoHideOnFinish", config.follow.autoHideOnFinish);
+    setNonEmpty(next, "follow", follow);
+  }
+
+  if (config.widget) {
+    const widget: NonNullable<ConfigV0100["widget"]> = {};
+    setIfDefined(widget, "showStatusWidget", config.widget.showStatusWidget);
+    setIfDefined(
+      widget,
+      "dockDefaultState",
+      migrateDockDefaultState(config.widget.dockDefaultState),
+    );
+    setIfDefined(widget, "dockHeight", config.widget.dockHeight);
+    setNonEmpty(next, "widget", widget);
+  }
+
+  return next;
+}
+
+function setNonEmpty<K extends keyof ConfigV0100>(
+  target: ConfigV0100,
+  key: K,
+  value: NonNullable<ConfigV0100[K]>,
+): void {
+  if (Object.keys(value).length > 0) target[key] = value;
+}
+
+export const configV094ToV0100Migration: Migration<ProcessConfig> = {
+  name: "001-v0-9-4-to-v0-10-0-config",
+  shouldRun: (config) => needsConfigV094ToV0100Migration(config),
+  run: (config) => migrateConfigV094ToV0100(config as ConfigV094),
+  message:
+    "Migrated pi-processes settings to the current schema. Mapped the dock hidden state to closed.",
+};

package/extensions/processes/config/migrations/002-stamp-v0-10-0-config-version.ts

@@ -0,0 +1,21 @@
+import type { Migration } from "@aliou/pi-utils-settings";
+
+import type { ProcessConfig } from "../types";
+
+export const PROCESS_CONFIG_VERSION = "0.10.0";
+
+export function needsConfigVersionStamp(config: ProcessConfig): boolean {
+  return (config.version ?? "") < PROCESS_CONFIG_VERSION;
+}
+
+export function stampConfigVersion(config: ProcessConfig): ProcessConfig {
+  return { ...config, version: PROCESS_CONFIG_VERSION };
+}
+
+export const configVersionStampMigration: Migration<ProcessConfig> = {
+  name: "002-stamp-v0-10-0-config-version",
+  shouldRun: needsConfigVersionStamp,
+  run: (config) => stampConfigVersion(config),
+  message:
+    "Updated pi-processes settings for v0.10.0. This release rewrites the package into separate process, logs, and dock extensions while preserving your existing settings. Release notes will be published at https://github.com/aliou/pi-processes/releases/tag/v0.10.0.",
+};

package/extensions/processes/config/migrations/index.ts

@@ -0,0 +1,25 @@
+import type { Migration } from "@aliou/pi-utils-settings";
+
+import type { ProcessConfig } from "../types";
+import { configV094ToV0100Migration } from "./001-v0-9-4-to-v0-10-0-config";
+import { configVersionStampMigration } from "./002-stamp-v0-10-0-config-version";
+
+export { importLegacyProcessConfig } from "./000-import-legacy-process-config";
+export {
+  type ConfigV094,
+  type ConfigV0100,
+  configV094ToV0100Migration,
+  migrateConfigV094ToV0100,
+  needsConfigV094ToV0100Migration,
+} from "./001-v0-9-4-to-v0-10-0-config";
+export {
+  configVersionStampMigration,
+  needsConfigVersionStamp,
+  PROCESS_CONFIG_VERSION,
+  stampConfigVersion,
+} from "./002-stamp-v0-10-0-config-version";
+
+export const migrations: Migration<ProcessConfig>[] = [
+  configV094ToV0100Migration,
+  configVersionStampMigration,
+];

package/extensions/processes/config/schema.ts

@@ -0,0 +1,9 @@
+import { buildSchemaUrl } from "@aliou/pi-utils-settings";
+
+import pkg from "../../../package.json" with { type: "json" };
+
+export const PROCESS_CONFIG_SCHEMA_VERSION = pkg.version;
+export const PROCESS_CONFIG_SCHEMA_URL = buildSchemaUrl(
+  pkg.name,
+  PROCESS_CONFIG_SCHEMA_VERSION,
+);