@aliou/pi-processes 0.10.9 → 0.11.0

package/extensions/shared/log-line.ts

@@ -16,7 +16,7 @@ import {
   sanitizeForDisplay,
   stripSgr,
 } from "./display-text";
-import { truncateToWidth } from "./truncate";
+import { truncateToWidth, wrapToWidth } from "./truncate";
 
 export interface DisplayLogLine {
   type: "stdout" | "stderr";
@@ -56,13 +56,60 @@ export function renderLogLine(
   const prefixWidth = visibleWidth(prefix);
   const textWidth = Math.max(1, width - prefixWidth);
   const safe = sanitizeForDisplay(line.text);
+  // Use "→" as the truncation indicator so the user can see that a line
+  // was clipped (wrap mode is available via the `w` key in the overlay).
   const text = closeSgr(
-    truncateToWidth(plain ? stripSgr(safe) : safe, textWidth, "", true),
+    truncateToWidth(plain ? stripSgr(safe) : safe, textWidth, "→", true),
   );
 
   return `${prefix}${toneLogText(text, line.type, emphasis, theme)}`;
 }
 
+/**
+ * Wrap a log line into multiple display rows instead of truncating.
+ *
+ * Each returned row is toned (by stream / match state) and padded to `width`.
+ * SGR state is carried across wrapped chunks so colours survive wrapping.
+ * Continuation rows (every row after the first) are indented with a dim
+ * `continuationPrefix` so the user can visually distinguish a wrapped chunk
+ * from a new log line — matching `less`/`journalctl` behaviour.
+ * Used by the `/ps:logs` overlay soft-wrap mode; `renderLogLine` (truncate)
+ * remains the default for the `/ps` preview and dock.
+ */
+export function renderLogLineWrap(
+  line: DisplayLogLine,
+  options: RenderLogLineOptions,
+): string[] {
+  const {
+    theme,
+    width,
+    emphasis = "none",
+    prefix = "",
+    plain = false,
+  } = options;
+  if (width <= 0) return [];
+
+  const prefixWidth = visibleWidth(prefix);
+  const textWidth = Math.max(1, width - prefixWidth);
+  const safe = sanitizeForDisplay(line.text);
+  const source = plain ? stripSgr(safe) : safe;
+
+  // Continuation rows get a dim arrow indent so wrapped chunks are
+  // visually distinct from new log lines.
+  const contMarker = "↳ ";
+  const contIndent = visibleWidth(contMarker);
+
+  const wrapped = wrapToWidth(source, textWidth, contIndent);
+
+  return wrapped.map((row, index) => {
+    const toned = toneLogText(row, line.type, emphasis, theme);
+    if (index === 0) {
+      return `${prefix}${toned}`;
+    }
+    return `${theme.fg("dim", contMarker)}${toned}`;
+  });
+}
+
 /** Text of a log line as the views display it, for match comparisons. */
 export function displayTextOf(line: DisplayLogLine): string {
   return plainTextForDisplay(line.text);

package/{src → extensions/shared}/protocol/broadcasts.ts

@@ -1,4 +1,4 @@
-import type { ProcessInfo } from "../types";
+import type { ProcessInfo } from "../../../src/types";
 
 // Core emits, UI listens.
 

package/{src → extensions/shared}/protocol/channels.ts

@@ -15,6 +15,7 @@ export const CHANNELS = {
   REQUEST_CONFIG: "processes:request:config",
 
   // Command channels (UI -> core, callback)
+  COMMAND_START: "processes:command:start",
   COMMAND_KILL: "processes:command:kill",
   COMMAND_CLEAR: "processes:command:clear",
   // Pin handled by the dock extension, if loaded.

package/{src → extensions/shared}/protocol/commands.ts

@@ -1,7 +1,18 @@
-import type { KillResult } from "../types";
+import type { KillResult, ProcessInfo } from "../../../src/types";
 
 // UI emits, core handles then calls reply.
 
+export interface CommandStartPayload {
+  name: string;
+  command: string;
+  cwd?: string;
+  reply: (result: CommandStartResult) => void;
+}
+
+export type CommandStartResult =
+  | { ok: true; process: ProcessInfo }
+  | { ok: false; error: string };
+
 export interface CommandKillPayload {
   id: string;
   signal?: NodeJS.Signals;

package/{src → extensions/shared}/protocol/index.ts

@@ -10,6 +10,8 @@ export type {
   CommandKillPayload,
   CommandPinPayload,
   CommandPinResult,
+  CommandStartPayload,
+  CommandStartResult,
 } from "./commands";
 export type {
   LogsChunkPayload,

package/{src → extensions/shared}/protocol/notifications.ts

@@ -2,7 +2,7 @@ import type {
   ProcessEndReason,
   ProcessSignalInfo,
   ProcessStatus,
-} from "../types";
+} from "../../../src/types";
 
 /**
  * Notification event payload broadcast on {@link CHANNELS.NOTIFICATION}.

package/{src → extensions/shared}/protocol/requests.ts

@@ -1,4 +1,4 @@
-import type { ProcessInfo } from "../types";
+import type { ProcessInfo } from "../../../src/types";
 
 // UI emits, core listens and calls reply synchronously.
 // Reply callbacks make this an in-process protocol, not serializable IPC/RPC.

package/extensions/shared/shortcut-hints.ts

@@ -0,0 +1,150 @@
+/**
+ * Footer shortcut-hint rendering shared by the `/ps` overview and the
+ * `/ps:logs` overlay footers.
+ *
+ * Each hint renders in one of two modes:
+ *
+ * - Minimal: when the hint's key is a single character that occurs in its
+ *   label, only the word is shown and every occurrence of the key letter is
+ *   rendered in accent + bold. "w wrap" becomes "wrap" with a bold accent
+ *   "w"; the remainder of the word keeps the segment style (so a stateful
+ *   label like "wrap" can stay dim while off and accent while on).
+ * - Classic: `<dim key> <label>` (e.g. "j/k scroll"), used whenever the key
+ *   is not a single letter found in the label ("q close", "/ search",
+ *   "N prev").
+ *
+ * `renderShortcutHints` additionally collapses the bar to a leading "? more"
+ * affordance when the full list does not fit the available width: the "?"
+ * key opens the full shortcuts overlay (see shortcuts-overlay.ts).
+ *
+ * Keys and labels are static, trusted UI copy — never process output — so
+ * they do not go through the untrusted-text sanitizers.
+ */
+
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import { type Component, visibleWidth } from "@earendil-works/pi-tui";
+
+import { truncateToWidth } from "./truncate";
+
+/** Style applied to a label segment. */
+export type ShortcutLabelStyle = "plain" | "dim" | "accent";
+
+export interface ShortcutLabelSegment {
+  /** Segment text (trusted, static UI copy — not process output). */
+  text: string;
+  style?: ShortcutLabelStyle;
+}
+
+export interface ShortcutHint {
+  /** Key label as shown to the user, e.g. "w", "j/k", "/", "pgup/pgdn". */
+  key: string;
+  /**
+   * Action label: a plain word, or pre-styled segments for stateful labels
+   * (such as the stream filter's "stdout+stderr" whose halves dim and
+   * accent independently).
+   */
+  label: string | ShortcutLabelSegment[];
+}
+
+/** Separator between hints in a rendered bar. */
+const SEPARATOR = "  ";
+
+/** The key that opens the shortcuts overlay. */
+export const SHORTCUTS_KEY = "?";
+
+function styleSegment(
+  text: string,
+  style: ShortcutLabelStyle,
+  theme: Theme,
+): string {
+  if (text.length === 0) return "";
+  if (style === "dim") return theme.fg("dim", text);
+  if (style === "accent") return theme.fg("accent", text);
+  return text;
+}
+
+function segmentsOf(label: ShortcutHint["label"]): ShortcutLabelSegment[] {
+  return typeof label === "string" ? [{ text: label }] : label;
+}
+
+/** True when the hint can render in minimal mode (single-char key in label). */
+function isMinimal(hint: ShortcutHint): boolean {
+  if (hint.key.length !== 1) return false;
+  return segmentsOf(hint.label).some((segment) =>
+    segment.text.includes(hint.key),
+  );
+}
+
+/** Render a single hint (see module doc for the two modes). */
+function renderShortcutHint(hint: ShortcutHint, theme: Theme): string {
+  if (isMinimal(hint)) {
+    const key = theme.fg("accent", theme.bold(hint.key));
+    return segmentsOf(hint.label)
+      .map((segment) => {
+        const style = segment.style ?? "plain";
+        return segment.text
+          .split(hint.key)
+          .map((piece) => styleSegment(piece, style, theme))
+          .join(key);
+      })
+      .join("");
+  }
+
+  const label =
+    typeof hint.label === "string"
+      ? hint.label
+      : segmentsOf(hint.label)
+          .map((segment) =>
+            styleSegment(segment.text, segment.style ?? "plain", theme),
+          )
+          .join("");
+  return `${theme.fg("dim", hint.key)} ${label}`;
+}
+
+/** Render the "? more" affordance shown when the bar overflows. */
+function renderMoreHint(theme: Theme): string {
+  return `${theme.fg("accent", theme.bold(SHORTCUTS_KEY))}${theme.fg("dim", " more")}`;
+}
+
+/**
+ * Render a hint bar for the given width. When the full list fits, the hints
+ * are joined as-is. When it does not, the bar starts with "? more" (the
+ * shortcut that opens the shortcuts overlay) followed by every hint that
+ * still fits, in list order.
+ */
+export function renderShortcutHints(
+  hints: ShortcutHint[],
+  theme: Theme,
+  width: number,
+): string {
+  const rendered = hints.map((hint) => renderShortcutHint(hint, theme));
+  const full = rendered.join(SEPARATOR);
+  if (visibleWidth(full) <= width) {
+    return truncateToWidth(full, width, "", true);
+  }
+
+  let line = renderMoreHint(theme);
+  for (const hint of rendered) {
+    const next = `${line}${SEPARATOR}${hint}`;
+    if (visibleWidth(next) > width) break;
+    line = next;
+  }
+  return truncateToWidth(line, width, "", true);
+}
+
+/**
+ * Render a footer shortcut-hint bar. Hints are fetched through a getter so
+ * stateful labels (wrap on/off, active stream) stay fresh across renders.
+ */
+export class ShortcutHintsComponent implements Component {
+  constructor(
+    private readonly getHints: () => ShortcutHint[],
+    private readonly theme: Theme,
+  ) {}
+
+  render(width: number): string[] {
+    return [renderShortcutHints(this.getHints(), this.theme, width)];
+  }
+
+  invalidate(): void {}
+}

package/extensions/shared/shortcuts-overlay.ts

@@ -0,0 +1,229 @@
+/**
+ * The "? more" shortcuts overlay: a small centered panel stacked on top of
+ * the `/ps` overview or the `/ps:logs` overlay that lists every shortcut the
+ * footer may have truncated away.
+ *
+ * Layout follows herdr's keybinds panel: a title row (bold lowercase
+ * `keybinds` on the left, an inverse `esc close` pill on the right), then
+ * grouped sections with accent lowercase headers (`scrolling`, `view`, …),
+ * each row rendering keys in accent and the description in the normal
+ * foreground, descriptions aligned in one column shared by every group.
+ *
+ * Opened through `showShortcutsOverlay`, which pushes the component onto the
+ * TUI overlay stack (`tui.showOverlay`) so it renders above the calling
+ * overlay and captures keyboard focus; dismissing it restores focus to the
+ * caller. Any of `?`, `esc`, `enter`, `q`, or `ctrl+c` dismisses it.
+ */
+
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import {
+  type Component,
+  Key,
+  matchesKey,
+  type OverlayHandle,
+  type TUI,
+  visibleWidth,
+} from "@earendil-works/pi-tui";
+
+import { truncateToWidth } from "./truncate";
+
+/** One shortcut row: keys (already display-formatted) + description. */
+export interface ShortcutRow {
+  /** Key tokens joined with " / ", e.g. "j / k", "ctrl+u / ctrl+d". */
+  keys: string;
+  /** Action description, e.g. "line up / down". */
+  description: string;
+}
+
+/** A named group of shortcut rows. */
+export interface ShortcutGroup {
+  /** Lowercase group header, e.g. "scrolling". */
+  title: string;
+  rows: ShortcutRow[];
+}
+
+export interface ShortcutsOverlayOptions {
+  theme: Theme;
+  /** Groups to render, in order (the title row and close pill are fixed). */
+  groups: ShortcutGroup[];
+  /** Called when the user dismisses the overlay. */
+  onDismiss: () => void;
+}
+
+const OVERLAY_TITLE = "keybinds";
+const CLOSE_PILL = " esc close ";
+const KEY_COLUMN_GAP = 3;
+const PANEL_PADDING = 1;
+const MIN_OVERLAY_WIDTH = 36;
+const MAX_OVERLAY_WIDTH = 72;
+
+export class ShortcutsOverlayComponent implements Component {
+  private readonly contentWidth: number;
+
+  constructor(private readonly opts: ShortcutsOverlayOptions) {
+    this.contentWidth = computeKeyColumn(opts.groups);
+  }
+
+  render(width: number): string[] {
+    const theme = this.opts.theme;
+    const inner = Math.max(1, width - 2); // borders
+    const pad = Math.max(0, Math.min(PANEL_PADDING, inner));
+    const contentWidth = Math.max(1, inner - pad * 2);
+
+    const lines: string[] = [];
+    lines.push(borderTop(theme, inner, OVERLAY_TITLE));
+    lines.push(
+      contentLine(theme, inner, pad, this.renderTitleRow(contentWidth)),
+    );
+    let first = true;
+    for (const group of this.opts.groups) {
+      if (!first) lines.push(blankLine(inner));
+      first = false;
+      lines.push(
+        contentLine(
+          theme,
+          inner,
+          pad,
+          theme.fg("accent", theme.bold(group.title)),
+        ),
+      );
+      const keyColumn = this.contentWidth;
+      for (const row of group.rows) {
+        const keys = theme.fg("accent", row.keys);
+        const gap = " ".repeat(
+          Math.max(1, keyColumn - visibleWidth(row.keys) + KEY_COLUMN_GAP - 1),
+        );
+        const description = row.description;
+        lines.push(
+          contentLine(theme, inner, pad, `${keys}${gap}${description}`),
+        );
+      }
+    }
+    lines.push(blankLine(inner));
+    lines.push(borderBottom(theme, inner));
+    return lines;
+  }
+
+  /**
+   * Title row: the inverse `esc close` pill, right-aligned. The bold title
+   * itself lives in the top border, so it is not duplicated here.
+   */
+  private renderTitleRow(width: number): string {
+    const theme = this.opts.theme;
+    const pill = theme.bg("selectedBg", theme.fg("dim", CLOSE_PILL));
+    const gap = Math.max(0, width - visibleWidth(pill));
+    return truncateToWidth(`${" ".repeat(gap)}${pill}`, width, "", true);
+  }
+
+  handleInput(data: string): void {
+    if (
+      matchesKey(data, Key.escape) ||
+      matchesKey(data, Key.ctrl("c")) ||
+      matchesKey(data, Key.enter) ||
+      data === "q" ||
+      data === "?"
+    ) {
+      this.opts.onDismiss();
+    }
+  }
+
+  invalidate(): void {
+    return;
+  }
+}
+
+function blankLine(inner: number): string {
+  return `│${" ".repeat(inner)}│`;
+}
+
+function borderTop(theme: Theme, inner: number, title: string): string {
+  const styled = theme.fg("dim", ` ${theme.bold(title)} `);
+  const titleWidth = visibleWidth(styled);
+  const left = Math.max(0, Math.floor((inner - titleWidth) / 2));
+  const right = Math.max(0, inner - titleWidth - left);
+  return (
+    theme.fg("dim", `╭${"─".repeat(left)}`) +
+    styled +
+    theme.fg("dim", `${"─".repeat(right)}╮`)
+  );
+}
+
+function borderBottom(theme: Theme, inner: number): string {
+  return theme.fg("dim", `╰${"─".repeat(inner)}╯`);
+}
+
+function contentLine(
+  theme: Theme,
+  inner: number,
+  pad: number,
+  content: string,
+): string {
+  const line =
+    " ".repeat(pad) +
+    truncateToWidth(content, Math.max(0, inner - pad * 2), "", true) +
+    " ".repeat(pad);
+  return theme.fg("dim", "│") + line + theme.fg("dim", "│");
+}
+
+/** Width of the aligned key column: longest key row across all groups. */
+function computeKeyColumn(groups: ShortcutGroup[]): number {
+  return Math.max(
+    ...groups.flatMap((group) =>
+      group.rows.map((row) => visibleWidth(row.keys)),
+    ),
+    1,
+  );
+}
+
+/**
+ * Natural panel width for a group list: key column + gap + longest
+ * description, plus padding and borders, clamped to sane bounds.
+ */
+export function computeShortcutsOverlayWidth(groups: ShortcutGroup[]): number {
+  const keyColumn = computeKeyColumn(groups);
+  const longest = Math.max(
+    ...groups.flatMap((group) =>
+      group.rows.map(
+        (row) => keyColumn + KEY_COLUMN_GAP - 1 + visibleWidth(row.description),
+      ),
+    ),
+    1,
+  );
+  return Math.min(
+    MAX_OVERLAY_WIDTH,
+    Math.max(MIN_OVERLAY_WIDTH, longest + PANEL_PADDING * 2 + 2),
+  );
+}
+
+/**
+ * Push the shortcuts overlay onto the TUI overlay stack. Returns a disposer
+ * that hides it; safe to call more than once.
+ */
+export function showShortcutsOverlay(
+  tui: TUI,
+  options: Omit<ShortcutsOverlayOptions, "onDismiss">,
+): () => void {
+  let handle: OverlayHandle | null = null;
+  let dismissed = false;
+
+  const dismiss = () => {
+    if (dismissed) return;
+    dismissed = true;
+    handle?.hide();
+    tui.requestRender();
+  };
+
+  const component = new ShortcutsOverlayComponent({
+    ...options,
+    onDismiss: dismiss,
+  });
+
+  handle = tui.showOverlay(component, {
+    anchor: "center",
+    width: computeShortcutsOverlayWidth(options.groups),
+    maxHeight: "80%",
+    margin: 2,
+  });
+
+  return dismiss;
+}