pi-startup-redraw-fix 0.1.12 → 0.2.0

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # Changelog
 
+## [Unreleased]
+
+## [0.2.0] - 2026-07-03
+
+### Added
+- Added an `enabled` master toggle (defaults to `true`) that gates extension startup, and structured debug logging written to an extension-local `debug/` directory when `debug` is enabled. ([2d57235](https://github.com/MasuRii/pi-startup-redraw-fix/commit/2d57235b6b72b6ec28f0a5298228d8fafe828da5))
+
+### Changed
+- Widened Pi coding-agent and Pi TUI peer dependency ranges through `^0.80.0` and added a `postinstall` patch with npm `overrides` to resolve known vulnerabilities in transitive dependencies. ([2f1f400](https://github.com/MasuRii/pi-startup-redraw-fix/commit/2f1f400f804ee08b8f72f0f5d43ee6194de9b500))
+- Extracted a fresh-terminal fixture helper for the terminal clear-sequence tests. ([0fc323d](https://github.com/MasuRii/pi-startup-redraw-fix/commit/0fc323d19a74ed9e7cdf070cb57015261e22865f))
+- Updated README badge styling and added a ko-fi support button. ([0c3f0c3](https://github.com/MasuRii/pi-startup-redraw-fix/commit/0c3f0c36291a637dc47f2a5e8335eeb152e26244))
+
+## [0.1.13] - 2026-06-16
+
+### Fixed
+- Buffered trailing broken clear-sequence prefixes across multiple `write` calls so split escape sequences that arrive in separate chunks are correctly normalized instead of being silently discarded.
+
 ## [0.1.12] - 2026-06-01
 
 ### Changed

package/README.md

@@ -1,9 +1,17 @@
+<div align="center">
+
 # pi-startup-redraw-fix
 
-A Pi coding agent extension that patches terminal full-clear escape sequence ordering to prevent startup redraw glitches in certain terminal emulators.
+[![npm version](https://img.shields.io/npm/v/pi-startup-redraw-fix?style=for-the-badge)](https://www.npmjs.com/package/pi-startup-redraw-fix)
+[![License](https://img.shields.io/github/license/MasuRii/pi-startup-redraw-fix?style=for-the-badge)](LICENSE)
+[![Platform](https://img.shields.io/badge/Platform-macOS%20%7C%20Linux%20%7C%20Windows-blue?style=for-the-badge)]()
 
+[![ko-fi](https://ko-fi.com/img/githubbutton_sm.svg)](https://ko-fi.com/Y8Y01PSSVR)
+
+A Pi coding agent extension that patches terminal full-clear escape sequence ordering to prevent startup redraw glitches in certain terminal emulators.
 <img width="1360" height="752" alt="image" src="https://github.com/user-attachments/assets/05bfd443-052c-475e-bc80-3350cde5c642" />
 
+</div>
 
 ## Table of Contents
 

package/config/config.example.json

@@ -1,3 +1,4 @@
-{
-  "enabled": true
-}
+{
+  "enabled": true,
+  "debug": false
+}

package/package.json

@@ -1,64 +1,72 @@
-{
-  "name": "pi-startup-redraw-fix",
-  "version": "0.1.12",
-  "description": "Pi extension that patches terminal full-clear ordering to avoid startup redraw glitches.",
-  "type": "module",
-  "main": "./index.ts",
-  "exports": {
-    ".": "./index.ts"
-  },
-  "files": [
-    "index.ts",
-    "src",
-    "asset",
-    "config/config.example.json",
-    "README.md",
-    "CHANGELOG.md",
-    "LICENSE"
-  ],
-  "scripts": {
-    "build": "npx --yes -p typescript@5.7.3 tsc -p tsconfig.json --noCheck",
-    "lint": "npm run build",
-    "test": "npx --yes tsx --test normalize-clear-sequence.test.mjs",
-    "check": "npm run lint && npm run test"
-  },
-  "keywords": [
-    "pi-package",
-    "pi",
-    "pi-extension",
-    "pi-coding-agent",
-    "pi-tui",
-    "coding-agent",
-    "terminal",
-    "terminal-emulator",
-    "startup",
-    "startup-fix",
-    "redraw",
-    "bugfix"
-  ],
-  "author": "MasuRii",
-  "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/MasuRii/pi-startup-redraw-fix.git"
-  },
-  "bugs": {
-    "url": "https://github.com/MasuRii/pi-startup-redraw-fix/issues"
-  },
-  "homepage": "https://github.com/MasuRii/pi-startup-redraw-fix#readme",
-  "engines": {
-    "node": ">=20"
-  },
-  "publishConfig": {
-    "access": "public"
-  },
-  "pi": {
-    "extensions": [
-      "./index.ts"
-    ]
-  },
-  "peerDependencies": {
-    "@earendil-works/pi-coding-agent": "^0.74.0 || ^0.75.0 || ^0.77.0 || ^0.78.0",
-    "@earendil-works/pi-tui": "^0.74.0 || ^0.75.0 || ^0.77.0 || ^0.78.0"
-  }
-}
+{
+  "name": "pi-startup-redraw-fix",
+  "version": "0.2.0",
+  "description": "Pi extension that patches terminal full-clear ordering to avoid startup redraw glitches.",
+  "type": "module",
+  "main": "./index.ts",
+  "exports": {
+    ".": "./index.ts"
+  },
+  "files": [
+    "index.ts",
+    "src",
+    "asset",
+    "config/config.example.json",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "npx --yes -p typescript@5.7.3 tsc -p tsconfig.json --noCheck",
+    "lint": "npm run build",
+    "test": "npx --yes tsx --test normalize-clear-sequence.test.mjs",
+    "check": "npm run lint && npm run test",
+    "postinstall": "node -e \"const fs=require('fs'),cp=require('child_process'),p=require('path');const cwd=process.cwd();const normalized=cwd.split(p.sep).join('/');if(!normalized.includes('/.pi/agent/extensions/'))process.exit(0);const s=p.resolve(cwd,'../../scripts/patch-vulnerable-deps.mjs');if(!fs.existsSync(s))process.exit(0);const r=cp.spawnSync(process.execPath,[s,'--target',cwd,'--quiet'],{stdio:'inherit'});process.exit(r.status||0)\""
+  },
+  "keywords": [
+    "pi-package",
+    "pi",
+    "pi-extension",
+    "pi-coding-agent",
+    "pi-tui",
+    "coding-agent",
+    "terminal",
+    "terminal-emulator",
+    "startup",
+    "startup-fix",
+    "redraw",
+    "bugfix"
+  ],
+  "author": "MasuRii",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/MasuRii/pi-startup-redraw-fix.git"
+  },
+  "bugs": {
+    "url": "https://github.com/MasuRii/pi-startup-redraw-fix/issues"
+  },
+  "homepage": "https://github.com/MasuRii/pi-startup-redraw-fix#readme",
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "pi": {
+    "extensions": [
+      "./index.ts"
+    ]
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "^0.74.0 || ^0.75.0 || ^0.77.0 || ^0.78.0 || ^0.79.0 || ^0.80.0",
+    "@earendil-works/pi-tui": "^0.74.0 || ^0.75.0 || ^0.77.0 || ^0.78.0 || ^0.79.0 || ^0.80.0"
+  },
+  "overrides": {
+    "protobufjs": "7.6.3",
+    "ws": "8.21.0"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-coding-agent": "^0.80.3"
+  }
+}

package/src/config.ts

@@ -0,0 +1,66 @@
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+export interface StartupRedrawFixConfig {
+  enabled: boolean;
+  debug: boolean;
+}
+
+const DEFAULT_CONFIG: StartupRedrawFixConfig = {
+  enabled: true,
+  debug: false,
+};
+
+function resolveExtensionRoot(moduleUrl = import.meta.url): string {
+  return join(dirname(fileURLToPath(moduleUrl)), "..");
+}
+
+export const EXTENSION_ROOT = resolveExtensionRoot();
+export const CONFIG_PATH = join(EXTENSION_ROOT, "config.json");
+export const DEBUG_DIR = join(EXTENSION_ROOT, "debug");
+export const DEBUG_LOG_PATH = join(DEBUG_DIR, "debug.log");
+
+type ReadConfigResult =
+  | { ok: true; record: Record<string, unknown> }
+  | { ok: false; reason: "missing" | "unparseable" | "not-object" };
+
+/**
+ * Reads and validates the config file as a plain object.
+ *
+ * Returns a structured result so callers can react to each failure mode
+ * (missing, unparseable, non-object) without silently swallowing errors.
+ */
+function readConfigRecord(configPath: string): ReadConfigResult {
+  if (!existsSync(configPath)) {
+    return { ok: false, reason: "missing" };
+  }
+
+  try {
+    const raw = readFileSync(configPath, "utf8");
+    const parsed = JSON.parse(raw) as unknown;
+    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+      return { ok: false, reason: "not-object" };
+    }
+    return { ok: true, record: parsed as Record<string, unknown> };
+  } catch {
+    return { ok: false, reason: "unparseable" };
+  }
+}
+
+function readBoolean(record: Record<string, unknown>, key: keyof StartupRedrawFixConfig): boolean {
+  const value = record[key];
+  return typeof value === "boolean" ? value : DEFAULT_CONFIG[key];
+}
+
+export function loadStartupRedrawFixConfig(): StartupRedrawFixConfig {
+  const result = readConfigRecord(CONFIG_PATH);
+  if (!result.ok) {
+    return { ...DEFAULT_CONFIG };
+  }
+
+  return {
+    enabled: readBoolean(result.record, "enabled"),
+    debug: readBoolean(result.record, "debug"),
+  };
+}

package/src/constants.ts

@@ -1 +1 @@
-export { BROKEN_FULL_CLEAR_SEQUENCE, FIXED_FULL_CLEAR_SEQUENCE } from "./terminal-clear-patch.js";
+export { BROKEN_FULL_CLEAR_SEQUENCE, FIXED_FULL_CLEAR_SEQUENCE } from "./terminal-clear-patch.js";

package/src/index.ts

@@ -1,23 +1,37 @@
-import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-
-import { applyTerminalClearSequencePatch } from "./terminal-clear-patch.js";
-
-export default function startupRedrawFixExtension(pi: ExtensionAPI): void {
-  // The terminal clear-sequence patch must be installed before the first
-  // full-clear write at startup, so it is applied synchronously at registration
-  // rather than deferred. The local import graph is tiny (a few dozen lines) and
-  // the only package dependency, pi-tui, is already loaded by Pi core, so there
-  // is no meaningful startup transpile cost to defer here.
-  const patchResult = applyTerminalClearSequencePatch();
-
-  pi.on("session_start", async (_event, ctx) => {
-    if (!ctx.hasUI) {
-      return;
-    }
-
-    if (!patchResult.patched && !patchResult.alreadyPatched) {
-      const reason = patchResult.error ?? "unknown error";
-      ctx.ui.notify(`startup-redraw-fix: failed to patch terminal clear sequence (${reason})`, "warning");
-    }
-  });
-}
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+import { loadStartupRedrawFixConfig } from "./config.js";
+import { createStartupRedrawFixLogger } from "./logging.js";
+import { applyTerminalClearSequencePatch } from "./terminal-clear-patch.js";
+
+export default function startupRedrawFixExtension(pi: ExtensionAPI): void {
+  const config = loadStartupRedrawFixConfig();
+  if (!config.enabled) {
+    return;
+  }
+
+  const logger = createStartupRedrawFixLogger({ getConfig: () => config });
+
+  // The terminal clear-sequence patch must be installed before the first
+  // full-clear write at startup, so it is applied synchronously at registration
+  // rather than deferred. The local import graph is tiny (a few dozen lines) and
+  // the only package dependency, pi-tui, is already loaded by Pi core, so there
+  // is no meaningful startup transpile cost to defer here.
+  const patchResult = applyTerminalClearSequencePatch();
+  logger.debug("patch.applied", {
+    patched: patchResult.patched,
+    alreadyPatched: patchResult.alreadyPatched,
+    error: patchResult.error,
+  });
+
+  pi.on("session_start", async (_event, ctx) => {
+    if (!ctx.hasUI) {
+      return;
+    }
+
+    if (!patchResult.patched && !patchResult.alreadyPatched) {
+      const reason = patchResult.error ?? "unknown error";
+      ctx.ui.notify(`startup-redraw-fix: failed to patch terminal clear sequence (${reason})`, "warning");
+    }
+  });
+}

package/src/logging.ts

@@ -0,0 +1,76 @@
+/**
+ * Debug logging for pi-startup-redraw-fix.
+ *
+ * Appends debug output to a file inside the colocated `debug/` directory
+ * when `debug` is true. Creates the directory at runtime only when debug
+ * logging is enabled. No console or stdio output.
+ */
+import { mkdirSync } from "node:fs";
+import { appendFile } from "node:fs/promises";
+
+import { DEBUG_DIR, DEBUG_LOG_PATH } from "./config.js";
+
+export interface StartupRedrawFixLogger {
+  /** Log a debug event with optional details. No-op when debug is false. */
+  debug: (event: string, details?: Record<string, unknown>) => void;
+  /** Wait for all queued debug writes to complete. */
+  flush: () => Promise<void>;
+}
+
+interface LoggerOptions {
+  /** Function returning the current config (checked on each call for live debug state). */
+  getConfig: () => { debug: boolean };
+  /** Override path for the debug log file. */
+  debugLogPath?: string;
+  /** Override path for the debug directory. */
+  debugDir?: string;
+}
+
+/**
+ * Creates a debug logger that writes to a colocated debug/ directory.
+ *
+ * - Debug output is only written when `config.debug` is true.
+ * - The debug/ directory is created at runtime only when debug logging is enabled.
+ * - All writes are async and queued to avoid blocking the extension.
+ * - No output is written to console, stdout, or stderr.
+ */
+export function createStartupRedrawFixLogger(options: LoggerOptions): StartupRedrawFixLogger {
+  const logPath = options.debugLogPath ?? DEBUG_LOG_PATH;
+  const logDir = options.debugDir ?? DEBUG_DIR;
+  let writeQueue: Promise<void> = Promise.resolve();
+
+  const enqueueAppend = (line: string): void => {
+    writeQueue = writeQueue.then(
+      () => appendFile(logPath, `${line}\n`, "utf8"),
+      () => appendFile(logPath, `${line}\n`, "utf8"),
+    );
+    void writeQueue.catch(() => {
+      // Logging must never write to stdout/stderr or interrupt extension operation.
+    });
+  };
+
+  const debug = (event: string, details: Record<string, unknown> = {}): void => {
+    if (!options.getConfig().debug) {
+      return;
+    }
+
+    try {
+      mkdirSync(logDir, { recursive: true });
+    } catch {
+      // Cannot create debug directory — skip logging without disrupting startup.
+      return;
+    }
+
+    const line = JSON.stringify({
+      timestamp: new Date().toISOString(),
+      extension: "pi-startup-redraw-fix",
+      event,
+      ...details,
+    });
+    enqueueAppend(line);
+  };
+
+  const flush = (): Promise<void> => writeQueue.catch(() => undefined);
+
+  return { debug, flush };
+}

package/src/normalize-clear-sequence.ts

@@ -1 +1 @@
-export { normalizeTerminalClearSequence } from "./terminal-clear-patch.js";
+export { normalizeTerminalClearSequence } from "./terminal-clear-patch.js";

package/src/terminal-clear-patch.ts

@@ -1,53 +1,83 @@
-import { ProcessTerminal } from "@earendil-works/pi-tui";
-
-export const BROKEN_FULL_CLEAR_SEQUENCE = "\x1b[3J\x1b[2J\x1b[H";
-export const FIXED_FULL_CLEAR_SEQUENCE = "\x1b[H\x1b[2J\x1b[3J";
-
-const PATCH_FLAG_KEY = "__piStartupRedrawFixPatched__" as const;
-
-type ProcessTerminalPrototype = typeof ProcessTerminal.prototype & {
-  [PATCH_FLAG_KEY]?: boolean;
-};
-
-export interface PatchResult {
-  patched: boolean;
-  alreadyPatched: boolean;
-  error?: string;
-}
-
-export function normalizeTerminalClearSequence(data: string): string {
-  if (!data.includes(BROKEN_FULL_CLEAR_SEQUENCE)) {
-    return data;
-  }
-
-  return data.split(BROKEN_FULL_CLEAR_SEQUENCE).join(FIXED_FULL_CLEAR_SEQUENCE);
-}
-
-export function applyTerminalClearSequencePatch(): PatchResult {
-  const prototype = ProcessTerminal.prototype as ProcessTerminalPrototype;
-
-  if (prototype[PATCH_FLAG_KEY]) {
-    return { patched: false, alreadyPatched: true };
-  }
-
-  const originalWrite = prototype.write;
-  if (typeof originalWrite !== "function") {
-    return {
-      patched: false,
-      alreadyPatched: false,
-      error: "ProcessTerminal.write is unavailable",
-    };
-  }
-
-  prototype.write = function patchedProcessTerminalWrite(data: string): void {
-    const normalized = typeof data === "string"
-      ? normalizeTerminalClearSequence(data)
-      : data;
-
-    originalWrite.call(this, normalized);
-  };
-
-  prototype[PATCH_FLAG_KEY] = true;
-
-  return { patched: true, alreadyPatched: false };
-}
+import { ProcessTerminal } from "@earendil-works/pi-tui";
+
+export const BROKEN_FULL_CLEAR_SEQUENCE = "\x1b[3J\x1b[2J\x1b[H";
+export const FIXED_FULL_CLEAR_SEQUENCE = "\x1b[H\x1b[2J\x1b[3J";
+
+const PATCH_FLAG_KEY = "__piStartupRedrawFixPatched__" as const;
+
+type ProcessTerminalPrototype = typeof ProcessTerminal.prototype & {
+  [PATCH_FLAG_KEY]?: boolean;
+};
+
+export interface PatchResult {
+  patched: boolean;
+  alreadyPatched: boolean;
+  error?: string;
+}
+
+export function normalizeTerminalClearSequence(data: string): string {
+  if (!data.includes(BROKEN_FULL_CLEAR_SEQUENCE)) {
+    return data;
+  }
+
+  return data.split(BROKEN_FULL_CLEAR_SEQUENCE).join(FIXED_FULL_CLEAR_SEQUENCE);
+}
+
+function splitTrailingBrokenClearPrefix(data: string): { ready: string; pending: string } {
+  const maxPrefixLength = BROKEN_FULL_CLEAR_SEQUENCE.length - 1;
+  const maxCandidateLength = Math.min(maxPrefixLength, data.length);
+
+  for (let length = maxCandidateLength; length > 0; length -= 1) {
+    const suffix = data.slice(-length);
+    if (BROKEN_FULL_CLEAR_SEQUENCE.startsWith(suffix)) {
+      return {
+        ready: data.slice(0, -length),
+        pending: suffix,
+      };
+    }
+  }
+
+  return { ready: data, pending: "" };
+}
+
+export function applyTerminalClearSequencePatch(): PatchResult {
+  const prototype = ProcessTerminal.prototype as ProcessTerminalPrototype;
+
+  if (prototype[PATCH_FLAG_KEY]) {
+    return { patched: false, alreadyPatched: true };
+  }
+
+  const originalWrite = prototype.write;
+  if (typeof originalWrite !== "function") {
+    return {
+      patched: false,
+      alreadyPatched: false,
+      error: "ProcessTerminal.write is unavailable",
+    };
+  }
+
+  let pendingClearPrefix = "";
+
+  prototype.write = function patchedProcessTerminalWrite(data: string): void {
+    if (typeof data !== "string") {
+      if (pendingClearPrefix.length > 0) {
+        originalWrite.call(this, pendingClearPrefix);
+        pendingClearPrefix = "";
+      }
+      originalWrite.call(this, data);
+      return;
+    }
+
+    const combined = `${pendingClearPrefix}${data}`;
+    const { ready, pending } = splitTrailingBrokenClearPrefix(combined);
+    pendingClearPrefix = pending;
+
+    if (ready.length > 0) {
+      originalWrite.call(this, normalizeTerminalClearSequence(ready));
+    }
+  };
+
+  prototype[PATCH_FLAG_KEY] = true;
+
+  return { patched: true, alreadyPatched: false };
+}