fix: support Ctrl-Z job-control suspend (#269)

benvinegar · web-flow · commit 7b7794a84810 · 2026-05-10T08:11:50.000-04:00
diff --git a/src/core/jobControl.test.ts b/src/core/jobControl.test.ts
@@ -0,0 +1,219 @@
+import { describe, expect, test } from "bun:test";
+import type { KeyEvent } from "@opentui/core";
+import { installJobControlSuspendSupport } from "./jobControl";
+
+function createTestKey(overrides: Partial<KeyEvent> = {}) {
+  let defaultPrevented = false;
+  let propagationStopped = false;
+
+  return {
+    ctrl: false,
+    get defaultPrevented() {
+      return defaultPrevented;
+    },
+    meta: false,
+    name: "z",
+    get propagationStopped() {
+      return propagationStopped;
+    },
+    shift: false,
+    preventDefault() {
+      defaultPrevented = true;
+    },
+    stopPropagation() {
+      propagationStopped = true;
+    },
+    ...overrides,
+  } as KeyEvent;
+}
+
+function createMockRenderer() {
+  const keypressListeners = new Set<(key: KeyEvent) => void>();
+
+  return {
+    isDestroyed: false,
+    keyInput: {
+      off(_event: "keypress", listener: (key: KeyEvent) => void) {
+        keypressListeners.delete(listener);
+      },
+      on(_event: "keypress", listener: (key: KeyEvent) => void) {
+        keypressListeners.add(listener);
+      },
+    },
+    keypressListeners,
+    resumeCalls: 0,
+    suspendCalls: 0,
+    emitKeypress(key: KeyEvent) {
+      for (const listener of keypressListeners) {
+        listener(key);
+      }
+    },
+    resume() {
+      this.resumeCalls += 1;
+    },
+    suspend() {
+      this.suspendCalls += 1;
+    },
+  };
+}
+
+function createSignalHarness() {
+  const listeners = new Map<NodeJS.Signals, Set<() => void>>();
+  const onceWrappers = new Map<() => void, () => void>();
+  const removed: NodeJS.Signals[] = [];
+
+  return {
+    emit(signal: NodeJS.Signals) {
+      const signalListeners = listeners.get(signal);
+      if (!signalListeners) {
+        return;
+      }
+
+      const snapshot = Array.from(signalListeners);
+      for (const listener of snapshot) {
+        listener();
+      }
+    },
+    listenerCount(signal: NodeJS.Signals) {
+      return listeners.get(signal)?.size ?? 0;
+    },
+    off(signal: NodeJS.Signals, listener: () => void) {
+      removed.push(signal);
+      listeners.get(signal)?.delete(listener);
+      const wrapped = onceWrappers.get(listener);
+      if (wrapped) {
+        listeners.get(signal)?.delete(wrapped);
+        onceWrappers.delete(listener);
+      }
+    },
+    once(signal: NodeJS.Signals, listener: () => void) {
+      const wrapped = () => {
+        listeners.get(signal)?.delete(wrapped);
+        onceWrappers.delete(listener);
+        listener();
+      };
+      onceWrappers.set(listener, wrapped);
+
+      let signalListeners = listeners.get(signal);
+      if (!signalListeners) {
+        signalListeners = new Set();
+        listeners.set(signal, signalListeners);
+      }
+      signalListeners.add(wrapped);
+    },
+    removed,
+  };
+}
+
+describe("installJobControlSuspendSupport", () => {
+  test("does not install keypress listeners on Windows", () => {
+    const renderer = createMockRenderer();
+
+    installJobControlSuspendSupport(renderer, {
+      platform: "win32",
+    });
+
+    expect(renderer.keypressListeners.size).toBe(0);
+  });
+
+  test("ignores keys other than Ctrl-Z", () => {
+    const renderer = createMockRenderer();
+    const sentSignals: NodeJS.Signals[] = [];
+
+    installJobControlSuspendSupport(renderer, {
+      kill: (_pid, signal) => sentSignals.push(signal),
+      platform: "linux",
+    });
+
+    const plainZ = createTestKey({ name: "z" });
+    renderer.emitKeypress(plainZ);
+
+    expect(plainZ.defaultPrevented).toBe(false);
+    expect(renderer.suspendCalls).toBe(0);
+    expect(sentSignals).toEqual([]);
+  });
+
+  test("suspends the foreground process group on Ctrl-Z and resumes on SIGCONT", () => {
+    const renderer = createMockRenderer();
+    const signals = createSignalHarness();
+    const sentSignals: Array<{ pid: number; signal: NodeJS.Signals }> = [];
+
+    installJobControlSuspendSupport(renderer, {
+      kill: (pid, signal) => sentSignals.push({ pid, signal }),
+      off: signals.off,
+      once: signals.once,
+      platform: "linux",
+    });
+
+    const ctrlZ = createTestKey({ ctrl: true, name: "z" });
+    renderer.emitKeypress(ctrlZ);
+    expect(ctrlZ.defaultPrevented).toBe(true);
+    expect(ctrlZ.propagationStopped).toBe(true);
+    expect(renderer.suspendCalls).toBe(1);
+    expect(signals.listenerCount("SIGCONT")).toBe(1);
+    expect(sentSignals).toEqual([{ pid: 0, signal: "SIGTSTP" }]);
+
+    signals.emit("SIGCONT");
+    expect(renderer.resumeCalls).toBe(1);
+    expect(signals.listenerCount("SIGCONT")).toBe(0);
+  });
+
+  test("does not resume a destroyed renderer after SIGCONT", () => {
+    const renderer = createMockRenderer();
+    const signals = createSignalHarness();
+
+    installJobControlSuspendSupport(renderer, {
+      kill: () => undefined,
+      off: signals.off,
+      once: signals.once,
+      platform: "linux",
+    });
+
+    renderer.emitKeypress(createTestKey({ ctrl: true, name: "z" }));
+    renderer.isDestroyed = true;
+    signals.emit("SIGCONT");
+
+    expect(renderer.suspendCalls).toBe(1);
+    expect(renderer.resumeCalls).toBe(0);
+  });
+
+  test("restores the renderer if SIGTSTP cannot be sent", () => {
+    const renderer = createMockRenderer();
+    const signals = createSignalHarness();
+
+    installJobControlSuspendSupport(renderer, {
+      kill: () => {
+        throw new Error("unsupported signal");
+      },
+      off: signals.off,
+      once: signals.once,
+      platform: "linux",
+    });
+
+    renderer.emitKeypress(createTestKey({ ctrl: true, name: "z" }));
+    expect(renderer.suspendCalls).toBe(1);
+    expect(renderer.resumeCalls).toBe(1);
+    expect(signals.listenerCount("SIGCONT")).toBe(0);
+  });
+
+  test("dispose removes the keypress listener and pending SIGCONT listener", () => {
+    const renderer = createMockRenderer();
+    const signals = createSignalHarness();
+
+    const support = installJobControlSuspendSupport(renderer, {
+      kill: () => undefined,
+      off: signals.off,
+      once: signals.once,
+      platform: "linux",
+    });
+
+    renderer.emitKeypress(createTestKey({ ctrl: true, name: "z" }));
+    support.dispose();
+
+    expect(renderer.keypressListeners.size).toBe(0);
+    expect(signals.listenerCount("SIGCONT")).toBe(0);
+
+    renderer.emitKeypress(createTestKey({ ctrl: true, name: "z" }));
+    expect(renderer.suspendCalls).toBe(1);
+  });
+});
diff --git a/src/core/jobControl.ts b/src/core/jobControl.ts
@@ -0,0 +1,105 @@
+import type { CliRenderer, KeyEvent } from "@opentui/core";
+
+type SignalListener = () => void;
+type KeypressListener = (key: KeyEvent) => void;
+
+type JobControlRenderer = Pick<CliRenderer, "isDestroyed" | "resume" | "suspend"> & {
+  keyInput: {
+    off: (event: "keypress", listener: KeypressListener) => unknown;
+    on: (event: "keypress", listener: KeypressListener) => unknown;
+  };
+};
+
+/** Test seams for installing process-level Unix job-control signal handling. */
+export interface JobControlSuspendDeps {
+  kill?: (pid: number, signal: NodeJS.Signals) => unknown;
+  off?: (signal: NodeJS.Signals, listener: SignalListener) => unknown;
+  once?: (signal: NodeJS.Signals, listener: SignalListener) => unknown;
+  platform?: NodeJS.Platform | string;
+  /** Signal target passed to process.kill; defaults to 0 for the foreground process group. */
+  pid?: number;
+}
+
+export interface JobControlSuspendSupport {
+  /** Remove listeners installed for the lifetime of one app renderer. */
+  dispose: () => void;
+}
+
+/** Match the parsed Ctrl-Z shortcut that opencode binds to its terminal suspend command. */
+function isCtrlZ(key: KeyEvent) {
+  return key.ctrl && !key.meta && !key.shift && key.name === "z";
+}
+
+/**
+ * Install Ctrl-Z job-control suspend support for OpenTUI raw-mode input.
+ *
+ * OpenTUI receives Ctrl-Z as a parsed keypress instead of letting the terminal driver turn it into
+ * SIGTSTP. Match the common TUI pattern used by apps like opencode: treat Ctrl-Z as an app command,
+ * ask OpenTUI to restore the terminal, then send SIGTSTP to the foreground process group so the
+ * shell can manage Hunk as a normal suspended job. SIGCONT resumes the renderer after `fg`.
+ */
+export function installJobControlSuspendSupport(
+  renderer: JobControlRenderer,
+  deps: JobControlSuspendDeps = {},
+): JobControlSuspendSupport {
+  const platform = deps.platform ?? process.platform;
+  if (platform === "win32") {
+    return { dispose: () => undefined };
+  }
+
+  const kill = deps.kill ?? process.kill.bind(process);
+  const off = deps.off ?? process.off.bind(process);
+  const once = deps.once ?? process.once.bind(process);
+  const pid = deps.pid ?? 0;
+  let disposed = false;
+  let resumeOnContinue: SignalListener | null = null;
+
+  const clearPendingContinue = () => {
+    if (resumeOnContinue) {
+      off("SIGCONT", resumeOnContinue);
+      resumeOnContinue = null;
+    }
+  };
+
+  const suspend = () => {
+    resumeOnContinue = () => {
+      resumeOnContinue = null;
+      if (!renderer.isDestroyed) {
+        renderer.resume();
+      }
+    };
+
+    renderer.suspend();
+    once("SIGCONT", resumeOnContinue);
+
+    try {
+      kill(pid, "SIGTSTP");
+    } catch {
+      // If the platform/runtime refuses SIGTSTP, leave the app usable instead of half-suspended.
+      clearPendingContinue();
+      if (!renderer.isDestroyed) {
+        renderer.resume();
+      }
+    }
+  };
+
+  const keypressListener: KeypressListener = (key) => {
+    if (disposed || renderer.isDestroyed || !isCtrlZ(key)) {
+      return;
+    }
+
+    key.preventDefault();
+    key.stopPropagation();
+    suspend();
+  };
+
+  renderer.keyInput.on("keypress", keypressListener);
+
+  return {
+    dispose: () => {
+      disposed = true;
+      clearPendingContinue();
+      renderer.keyInput.off("keypress", keypressListener);
+    },
+  };
+}
diff --git a/src/main.tsx b/src/main.tsx
@@ -3,6 +3,7 @@
 import { createCliRenderer } from "@opentui/core";
 import { createRoot } from "@opentui/react";
 import { formatCliError } from "./core/errors";
+import { installJobControlSuspendSupport } from "./core/jobControl";
 import { pagePlainText } from "./core/pager";
 import { shutdownSession } from "./core/shutdown";
 import { prepareStartupPlan } from "./core/startup";
@@ -72,7 +73,9 @@ async function main() {
     onDestroy: () => controllingTerminal?.close(),
   });
 
-  const root = createRoot(renderer);
+  const appRenderer = renderer;
+  const jobControlSuspendSupport = installJobControlSuspendSupport(appRenderer);
+  const root = createRoot(appRenderer);
   let shuttingDown = false;
 
   /** Tear down the renderer before exit so the primary terminal screen comes back cleanly. */
@@ -82,8 +85,9 @@ async function main() {
     }
 
     shuttingDown = true;
+    jobControlSuspendSupport.dispose();
     hostClient.stop();
-    shutdownSession({ root, renderer });
+    shutdownSession({ root, renderer: appRenderer });
   }
 
   // The app owns the full alternate screen session from this point on.
