@groeponline/pi-wishcraft 1.4.1 → 1.4.6

package/bash-mode/pty-session.ts

@@ -0,0 +1,356 @@
+/**
+ * pty-session.ts
+ * ------------------------------------------------------------------------
+ * PTY-backed command execution for bash mode v2 (plan U3, KTD2).
+ *
+ * Wraps `script(1)` (util-linux) to allocate a real PTY per command, so
+ * stdin-reading programs work and SGR color survives into the transcript.
+ * The ANSI filter keeps only SGR sequences (plus plain text); OSC, DCS,
+ * cursor-positioning CSI and C0 control noise are stripped — a transcript
+ * must never relay terminal-control escapes back into the host terminal.
+ *
+ * When `script` is unavailable, the session degrades per command to plain
+ * pipe execution (v1 behavior, no color). SIGWINCH/resize forwarding is a
+ * known `script(1)` ceiling — swap for node-pty only if that bites
+ * (ponytail: revisit on real demand, not speculatively).
+ * ------------------------------------------------------------------------
+ */
+
+import { mkdtempSync, writeFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { basename, join } from "node:path";
+import { randomBytes } from "node:crypto";
+import { spawn, spawnSync, type ChildProcessWithoutNullStreams } from "node:child_process";
+
+/**
+ * Fresh per-command completion delimiter. The wrapper prints it after the
+ * sourced script ends; because it is unpredictable, a command cannot forge
+ * it mid-stream and settle the run early (which would let a later
+ * runCommand replace `this.child` and orphan the still-running process
+ * group).
+ */
+function makeDoneDelimiter(): string {
+  return `__PI_DONE__${randomBytes(8).toString("hex")}`;
+}
+
+export interface PtyFilterOptions {
+  /** Keep SGR color sequences; false strips them too (plain-text mode). */
+  color: boolean;
+}
+
+export interface PtyRunResult {
+  exitCode: number;
+  cwd: string;
+}
+
+export interface PtyShellSessionOptions {
+  cwd: string;
+  /** Emit filtered output lines as they arrive. */
+  onOutput: (line: string) => void;
+  onStateChange: () => void;
+  /** Keep SGR colors (PTY mode default capability). Default true. */
+  color?: boolean;
+  /** Override for the `script` availability probe (tests). */
+  scriptAvailable?: () => boolean;
+  /** Override user shell path (tests). */
+  shellPath?: string;
+}
+
+/**
+ * Filter raw PTY output. Keeps text, newlines, tabs, and (optionally) SGR
+ * escapes. Strips OSC/DCS sequences, non-SGR CSI sequences, and C0 control
+ * noise including the CR of CRLF pairs.
+ */
+export function filterPtyOutput(chunk: string, options: PtyFilterOptions): string {
+  let out = chunk;
+
+  // OSC sequences: ESC ] ... (BEL or ST)
+  out = out.replace(/\x1b\][^\x07\x1b]*(?:\x07|\x1b\\)/g, "");
+  // DCS/SOS/PM/APC sequences: ESC P ... ST
+  out = out.replace(/\x1b[P^_][^\x07\x1b]*(?:\x07|\x1b\\)/g, "");
+
+  if (options.color) {
+    // Protect SGR sequences behind Private Use Area sentinels so the C0
+    // strip below cannot eat their ESC introducers, strip every other CSI.
+    const kept: string[] = [];
+    out = out.replace(/\x1b\[[0-9;]*m/g, (m) => {
+      kept.push(m);
+      return `\uE000${kept.length - 1}\uE001`;
+    });
+    out = out.replace(/\x1b\[[0-9;?]*[ -/]*[@-~]/g, "");
+    // C0 noise: drop everything except \n and \t; \r is dropped (CRLF -> LF).
+    out = out.replace(/[\x00-\x09\x0b-\x1f\x7f]/g, (c) => (c === "\t" ? c : ""));
+    out = out.replace(/\uE000(\d+)\uE001/g, (_, i: string) => kept[Number.parseInt(i, 10)] ?? "");
+    return out;
+  }
+
+  // Strip all CSI including SGR.
+  out = out.replace(/\x1b\[[0-9;?]*[ -/]*[@-~]/g, "");
+  // C0 noise: drop everything except \n and \t; \r is dropped (CRLF -> LF).
+  out = out.replace(/[\x00-\x09\x0b-\x1f\x7f]/g, (c) => (c === "\t" ? c : ""));
+  return out;
+}
+
+function quoteShellArg(value: string): string {
+  return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+
+function getCloseExitCode(code: number | null, signal: NodeJS.Signals | null): number {
+  if (typeof code === "number") return code;
+  if (signal === "SIGINT") return 130;
+  if (signal === "SIGTERM") return 143;
+  if (signal === "SIGKILL") return 137;
+  return 1;
+}
+
+function buildWrapper(shellName: string, cwd: string, file: string, done: string): string {
+  const quotedCwd = quoteShellArg(cwd);
+  const quotedFile = quoteShellArg(file);
+  if (shellName.includes("fish")) {
+    return `cd ${quotedCwd}; and source ${quotedFile}; printf '\\n${done}:%s:%s\\n' $status $PWD`;
+  }
+  return `cd ${quotedCwd} && . ${quotedFile}; printf '\\n${done}:%s:%s\\n' "$?" "$PWD"`;
+}
+
+interface RunningCommand {
+  id: number;
+  /** This command's completion delimiter; only its own wrapper prints it. */
+  done: string;
+  buffer: string;
+  /** Trailing partial escape sequence carried across chunks. */
+  escapeTail: string;
+  resolve: (result: PtyRunResult) => void;
+  settled: boolean;
+}
+
+export class PtyShellSession {
+  private readonly startCwd: string;
+  private readonly onOutput: (line: string) => void;
+  private readonly onStateChange: () => void;
+  private readonly color: boolean;
+  private readonly scriptProbe: () => boolean;
+  private readonly shellPath: string;
+  private readonly shellName: string;
+  private readonly tempDir = mkdtempSync(join(tmpdir(), "wishcraft-pty-"));
+  private child: ChildProcessWithoutNullStreams | null = null;
+  private commandCounter = 0;
+  private running: RunningCommand | null = null;
+  private disposed = false;
+  private interrupted = false;
+
+  state: { running: boolean; cwd: string; lastExitCode: number | null; mode: "pty" | "pipe" };
+
+  constructor(options: PtyShellSessionOptions) {
+    this.startCwd = options.cwd;
+    this.onOutput = options.onOutput;
+    this.onStateChange = options.onStateChange;
+    this.color = options.color ?? true;
+    this.scriptProbe = options.scriptAvailable ?? (() => defaultScriptAvailable());
+    this.shellPath = options.shellPath ?? process.env["SHELL"] ?? "/bin/sh";
+    this.shellName = basename(this.shellPath).toLowerCase();
+    this.state = {
+      running: false,
+      cwd: options.cwd,
+      lastExitCode: null,
+      mode: this.scriptProbe() ? "pty" : "pipe",
+    };
+  }
+
+  childPid(): number | null {
+    return this.child?.pid ?? null;
+  }
+
+  async runCommand(command: string): Promise<PtyRunResult> {
+    if (this.disposed) throw new Error("Session disposed");
+    if (this.state.running) throw new Error("Command already running");
+
+    const id = ++this.commandCounter;
+    const extension = this.shellName.includes("fish") ? "fish" : "sh";
+    const file = join(this.tempDir, `cmd-${id}.${extension}`);
+    writeFileSync(file, command.endsWith("\n") ? command : `${command}\n`, "utf8");
+
+    const done = makeDoneDelimiter();
+    const wrapper = buildWrapper(this.shellName, this.state.cwd, file, done);
+    const usePty = this.scriptProbe();
+
+    return new Promise<PtyRunResult>((resolve) => {
+      const running: RunningCommand = {
+        id,
+        done,
+        buffer: "",
+        escapeTail: "",
+        resolve: (result) => {
+          if (running.settled) return;
+          running.settled = true;
+          this.state.running = false;
+          this.state.lastExitCode = result.exitCode;
+          this.state.cwd = result.cwd;
+          this.running = null;
+          this.onStateChange();
+          rmSync(file, { force: true });
+          resolve(result);
+        },
+        settled: false,
+      };
+      this.running = running;
+      this.state.running = true;
+      this.state.mode = usePty ? "pty" : "pipe";
+      this.interrupted = false;
+      this.onStateChange();
+
+      const child = usePty
+        ? spawn("script", ["-qec", wrapper, "/dev/null"], {
+            cwd: this.state.cwd,
+            env: { ...process.env, SHELL: this.shellPath },
+            stdio: ["pipe", "pipe", "pipe"],
+            detached: true,
+          })
+        : spawn(this.shellPath, ["-c", buildWrapper(this.shellName, this.state.cwd, file, done)], {
+            cwd: this.state.cwd,
+            env: process.env,
+            stdio: ["pipe", "pipe", "pipe"],
+            detached: true,
+          });
+
+      this.child = child as ChildProcessWithoutNullStreams;
+      child.stdout.setEncoding("utf8");
+      child.stderr.setEncoding("utf8");
+      child.stdin.on("error", () => {
+        // EPIPE after the child exits: input loss at teardown is expected.
+        // Without this listener a keystroke racing the exit would raise an
+        // unhandled error on the stdin stream and take down the host.
+      });
+      child.stdout.on("data", (chunk: string) => this.handleChunk(String(chunk)));
+      child.stderr.on("data", (chunk: string) => this.handleChunk(String(chunk)));
+      child.on("error", (error) => {
+        // spawn itself failed (script removed between probe and spawn, dead
+        // SHELL path): surface the reason, then settle as a normal failure.
+        // The first script-path failure also flips the probe cache so the
+        // next command degrades to pipes instead of silently failing again.
+        console.warn(
+          "[wishcraft] spawn failed:",
+          error instanceof Error ? error.message : String(error),
+        );
+        if (usePty) {
+          _resetScriptAvailableForTests();
+        }
+        running.resolve({ exitCode: 1, cwd: this.state.cwd });
+      });
+      child.on("close", (code, signal) => {
+        this.child = null;
+        // No sentinel observed. An operator interrupt never lets the command
+        // complete, so it maps to 130 regardless of how `script` exits.
+        if (this.interrupted) {
+          running.resolve({ exitCode: 130, cwd: this.state.cwd });
+          return;
+        }
+        running.resolve({
+          exitCode: getCloseExitCode(code, signal),
+          cwd: this.state.cwd,
+        });
+      });
+    });
+  }
+
+  writeStdin(data: string): void {
+    if (this.child == null || this.child.stdin.destroyed) return;
+    this.child.stdin.write(data);
+  }
+
+  interrupt(): void {
+    if (!this.child || !this.state.running) return;
+    this.interrupted = true;
+    this.signalGroup("SIGINT");
+  }
+
+  dispose(): void {
+    this.disposed = true;
+    if (this.child) {
+      this.signalGroup("SIGKILL");
+      this.child = null;
+    }
+    this.running = null;
+    this.state.running = false;
+    rmSync(this.tempDir, { recursive: true, force: true });
+  }
+
+  private signalGroup(signal: NodeJS.Signals): void {
+    const pid = this.child?.pid;
+    if (typeof pid !== "number") return;
+    try {
+      process.kill(-pid, signal);
+    } catch {
+      try {
+        this.child?.kill(signal);
+      } catch {
+        // Process group and direct kill both failed: nothing left to signal.
+      }
+    }
+  }
+
+  private handleChunk(chunk: string): void {
+    const running = this.running;
+    if (!running || running.settled) return;
+
+    const merged = running.escapeTail + chunk;
+    running.escapeTail = "";
+
+    // Carry a trailing partial escape (unterminated CSI/OSC/DCS, or a bare
+    // ESC byte) to the next chunk so split sequences cannot leak their
+    // introducer into output — a lone ESC followed by e.g. "[31m" on the
+    // next chunk must filter as one SGR, not render as plain text.
+    let work = merged;
+    const partial = /(?:\x1b(?:\[[0-9;?]*[ -/]*|\][^\x07\x1b]*|[P^_][^\x07\x1b]*))$|\x1b$/.exec(work);
+    if (partial) {
+      running.escapeTail = partial[0];
+      work = work.slice(0, work.length - running.escapeTail.length);
+    }
+
+    const color = this.color && this.state.mode === "pty";
+    const filtered = filterPtyOutput(work, { color });
+
+    running.buffer += filtered;
+    const parts = running.buffer.split("\n");
+    running.buffer = parts.pop() ?? "";
+
+    for (const rawLine of parts) {
+      const line = rawLine.replace(/\r$/, "");
+      if (line.startsWith(`${running.done}:`)) {
+        const rest = line.slice(running.done.length + 1);
+        // exit code may not contain ':'; cwd may (rare) — split on first two only.
+        const firstColon = rest.indexOf(":");
+        if (firstColon !== -1) {
+          const exitCode = Number.parseInt(rest.slice(0, firstColon), 10);
+          const cwd = rest.slice(firstColon + 1);
+          running.resolve({
+            exitCode: Number.isFinite(exitCode) ? exitCode : 1,
+            cwd: cwd || this.state.cwd,
+          });
+          return;
+        }
+        continue;
+      }
+      if (line.trim().length > 0) {
+        this.onOutput(line);
+      }
+    }
+  }
+}
+
+let scriptAvailableCache: boolean | null = null;
+
+export function defaultScriptAvailable(): boolean {
+  if (scriptAvailableCache === null) {
+    try {
+      const probe = spawnSync("script", ["--version"], { stdio: "ignore" });
+      scriptAvailableCache = probe.status === 0;
+    } catch {
+      scriptAvailableCache = false;
+    }
+  }
+  return scriptAvailableCache;
+}
+
+export function _resetScriptAvailableForTests(): void {
+  scriptAvailableCache = null;
+}

package/bash-mode/ptyshell-managed.ts

@@ -0,0 +1,145 @@
+/**
+ * ptyshell-managed.ts
+ * ------------------------------------------------------------------------
+ * Long-lived managed shell session backed by the v2 PTY runner (plan U13).
+ *
+ * Implements the same public surface as v1 `ManagedShellSession` so the
+ * construction site in bash-mode-actions.ts can swap without touching
+ * callers: `state`, `ensureReady()`, `runCommand()`, `interrupt()`,
+ * `dispose()`, plus `writeStdin()` for editor forward-mode (U4).
+ *
+ * Every command runs in its own `script(1)` PTY via PtyShellSession, so
+ * stdin-reading programs work and SGR color survives into the transcript.
+ * `ready` is true from construction — there is no persistent shell process
+ * to wait for; the PtyShellSession probes `script(1)` itself and degrades
+ * per command to plain pipes when it is missing (KTD2).
+ *
+ * Divergence from v1 (documented): v1 sourced `initScript` once into a
+ * long-lived shell. v2 has no persistent shell, so init runs as a preamble
+ * of every command. That keeps env/paths set by init available per command
+ * (ponytail: a persistent PTY shell is the upgrade path if init side
+ * effects per command ever matter).
+ * ------------------------------------------------------------------------
+ */
+
+import { basename } from "node:path";
+import type { BashTranscriptStore } from "./transcript.ts";
+import { PtyShellSession } from "./pty-session.ts";
+import type { ShellSessionState } from "./types.ts";
+
+export class PtyManagedShellSession {
+  readonly state: ShellSessionState;
+  private readonly transcript: BashTranscriptStore;
+  private readonly onStateChange: () => void;
+  private readonly onCommandSuccess: (command: string, cwd: string) => void;
+  private readonly initScript: string;
+  private readonly pty: PtyShellSession;
+  private commandCounter = 0;
+  private currentCommandId: string | null = null;
+
+  constructor(
+    shellPath: string,
+    cwd: string,
+    transcript: BashTranscriptStore,
+    onStateChange: () => void,
+    onCommandSuccess: (command: string, cwd: string) => void,
+    initScript: string | null = null,
+    scriptAvailable?: () => boolean,
+  ) {
+    this.transcript = transcript;
+    this.onStateChange = onStateChange;
+    this.onCommandSuccess = onCommandSuccess;
+    this.initScript = initScript ?? "";
+    const shellName = basename(shellPath).toLowerCase();
+    this.state = {
+      ready: true,
+      running: false,
+      shellPath,
+      shellName,
+      cwd,
+      lastExitCode: null,
+    };
+    this.pty = new PtyShellSession({
+      cwd,
+      shellPath,
+      onOutput: (line) => this.appendToTranscript(line),
+      // The managed session notifies every user-visible transition itself;
+      // passing the caller's callback through would double-fire renders.
+      onStateChange: () => {},
+      scriptAvailable,
+      color: true,
+    });
+  }
+
+  /**
+   * v2 sessions support editor forward-mode only when the active transport
+   * is a real PTY — the script(1)-missing pipe fallback has no interactive
+   * stdin (KTD2), so forwarding would swallow input (CodeRabbit #dJjDJ).
+   */
+  supportsForwardMode(): boolean {
+    return this.pty.state.mode !== "pipe";
+  }
+
+  async ensureReady(): Promise<void> {
+    // No persistent process; PtyShellSession probes script(1) lazily per
+    // command and degrades to pipes when absent (KTD2).
+  }
+
+  async runCommand(command: string): Promise<void> {
+    if (this.state.running) {
+      throw new Error("Shell command already running");
+    }
+
+    const id = `cmd-${++this.commandCounter}`;
+    this.currentCommandId = id;
+    this.state.running = true;
+    this.transcript.startCommand(id, command, this.state.cwd);
+    this.onStateChange();
+    try {
+      const result = await this.pty.runCommand(
+        this.initScript ? `${this.initScript}\n${command}` : command,
+      );
+      this.state.lastExitCode = result.exitCode;
+      this.state.cwd = result.cwd;
+      this.transcript.finishCommand(id, result.exitCode);
+      if (result.exitCode === 0) {
+        // A throwing success callback must not re-finish the already
+        // finished record as exit 1 and notify "run failed" for a command
+        // that succeeded.
+        try {
+          this.onCommandSuccess(command, result.cwd);
+        } catch (error) {
+          console.warn("[wishcraft] shell command succeeded but history callback failed", error);
+        }
+      }
+    } catch (error) {
+      const exitCode = 1;
+      this.state.lastExitCode = exitCode;
+      this.transcript.finishCommand(id, exitCode);
+      throw error;
+    } finally {
+      this.currentCommandId = null;
+      this.state.running = false;
+      this.onStateChange();
+    }
+  }
+
+  writeStdin(data: string): void {
+    this.pty.writeStdin(data);
+  }
+
+  interrupt(): void {
+    this.pty.interrupt();
+  }
+
+  dispose(): void {
+    this.pty.dispose();
+  }
+
+  private appendToTranscript(line: string): void {
+    const id = this.currentCommandId;
+    if (!id || !this.state.running) return;
+    this.transcript.appendOutput(id, line);
+    this.onStateChange();
+  }
+}

package/bash-mode/session-factory.ts

@@ -0,0 +1,64 @@
+import { PtyManagedShellSession } from "./ptyshell-managed.ts";
+import {
+  _resetScriptAvailableForTests,
+  defaultScriptAvailable,
+} from "./pty-session.ts";
+import type { BashTranscriptStore } from "./transcript.ts";
+
+export type SessionPreference = "auto" | "v2";
+
+export interface CreateShellSessionOptions {
+  cwd: string;
+  prefer?: SessionPreference;
+  transcript: BashTranscriptStore;
+  onStateChange?: () => void;
+  onCommandSuccess?: (command: string, cwd: string) => void;
+  initScript?: string | null;
+  shellPath?: string;
+  /** Override the script(1) availability probe (tests). */
+  scriptAvailable?: () => boolean;
+}
+
+let warnedScriptMissing = false;
+
+export function _resetWarnForTests(): void {
+  warnedScriptMissing = false;
+}
+
+function warnScriptMissingOnce(): void {
+  if (warnedScriptMissing) return;
+  warnedScriptMissing = true;
+  console.warn(
+    "[wishcraft] script(1) unavailable; bash mode v2 runs commands via plain pipes (no color, no interactive stdin) until it is installed",
+  );
+}
+
+export function isPtyPreferred(): boolean {
+  return defaultScriptAvailable();
+}
+
+export function _resetPtyProbeForTests(): void {
+  _resetScriptAvailableForTests();
+}
+
+export function createShellSession(
+  opts: CreateShellSessionOptions,
+): PtyManagedShellSession {
+  // transcript is a typed required field (TS enforces it); the factory has
+  // no untyped JS consumers.
+  const ptyAvailable = opts.scriptAvailable ? opts.scriptAvailable() : isPtyPreferred();
+  if (!ptyAvailable) {
+    warnScriptMissingOnce();
+  }
+  // auto and v2 both route through the PTY-backed managed session; when
+  // script(1) is absent it degrades per command to plain pipes (KTD2).
+  return new PtyManagedShellSession(
+    opts.shellPath ?? "/bin/sh",
+    opts.cwd,
+    opts.transcript,
+    opts.onStateChange ?? (() => {}),
+    opts.onCommandSuccess ?? (() => {}),
+    opts.initScript ?? null,
+    opts.scriptAvailable,
+  );
+}

package/bash-mode/transcript-v2.ts

@@ -0,0 +1,77 @@
+/**
+ * Transcript v2 (U4). ANSI-aware append: keep color escapes, drop malformed
+ * (dangling) SGR sequences, and truncate to a visible-width cap. Width is
+ * measured by the upstream `visibleWidth` helper; raw escape bytes are not
+ * counted, so a 10-column cap fits roughly 10 visible glyphs even when the
+ * underlying byte stream carries escape sequences.
+ */
+
+import { visibleWidth } from "@earendil-works/pi-tui";
+
+function stripMalformedSgr(text: string): string {
+  let out = "";
+  let i = 0;
+  while (i < text.length) {
+    if (text[i] === "\x1b" && text[i + 1] === "[") {
+      let j = i + 2;
+      while (j < text.length && /[0-9;]/.test(text[j] ?? "")) j += 1;
+      if (text[j] === "m") {
+        out += text.slice(i, j + 1);
+      }
+      i = j + 1;
+      continue;
+    }
+    out += text[i];
+    i += 1;
+  }
+  return out;
+}
+
+function balancedSgr(text: string, maxWidth: number): string {
+  const stripped = stripMalformedSgr(text);
+  const visible = visibleWidth(stripped);
+  if (visible <= maxWidth) return stripped;
+  return truncateToVisibleWidth(stripped, maxWidth);
+}
+
+function truncateToVisibleWidth(text: string, maxWidth: number): string {
+  let visible = "";
+  let width = 0;
+  let colorActive = false;
+  let i = 0;
+  while (i < text.length && width < maxWidth) {
+    const codePoint = text.codePointAt(i) ?? 0;
+    const ch = String.fromCodePoint(codePoint);
+    if (ch === "\x1b" && text[i + 1] === "[") {
+      let j = i + 2;
+      while (j < text.length && /[0-9;]/.test(text[j] ?? "")) j += 1;
+      if (text[j] === "m") {
+        const seq = text.slice(i, j + 1);
+        // Zero-width: keep the sequence at its original position so text
+        // before it stays unstyled; only a reset deactivates the format.
+        visible += seq;
+        colorActive = seq !== "\x1b[0m";
+      }
+      i = j + 1;
+      continue;
+    }
+    visible += ch;
+    // Iterate display units, not UTF-16 code units: wide glyphs advance the
+    // cap by their visible width and surrogate pairs are never split.
+    width += visibleWidth(ch);
+    i += ch.length;
+  }
+  return colorActive ? `${visible}\x1b[0m` : visible;
+}
+
+export function appendColored(
+  buf: readonly string[],
+  chunk: string,
+  maxWidth: number,
+): string[] {
+  const normalized = chunk.replace(/\r/g, "");
+  const lines = normalized.split("\n");
+  if (lines[lines.length - 1] === "") lines.pop();
+  const balanced = lines.map((line) => balancedSgr(line, maxWidth));
+  return [...buf, ...balanced];
+}

package/bash-mode/transcript.ts

@@ -91,6 +91,24 @@ export class BashTranscriptStore {
     };
   }
 
+  /**
+   * Shallow tail for hot render paths: last `count` commands with only the
+   * last `outputTail` lines each, no deep copy (the always-on powerline
+   * reads nothing else). Full snapshots stay on getSnapshot for
+   * doctor/export paths.
+   */
+  recentCommands(
+    count: number,
+    outputTail = 6,
+  ): { commands: BashCommandRecord[]; truncatedCommands: number } {
+    return {
+      commands: this.commands
+        .slice(-count)
+        .map((command) => ({ ...command, output: command.output.slice(-outputTail) })),
+      truncatedCommands: this.truncatedCommands,
+    };
+  }
+
   private enforceLimits(): void {
     while (
       this.commands.length > 1