pi-startup-redraw-fix 0.1.13 → 0.2.0

package/CHANGELOG.md

@@ -2,6 +2,16 @@
 
 ## [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

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,6 +1,6 @@
 {
   "name": "pi-startup-redraw-fix",
-  "version": "0.1.13",
+  "version": "0.2.0",
   "description": "Pi extension that patches terminal full-clear ordering to avoid startup redraw glitches.",
   "type": "module",
   "main": "./index.ts",
@@ -20,7 +20,8 @@
     "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"
+    "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",
@@ -58,7 +59,14 @@
     ]
   },
   "peerDependencies": {
-    "@earendil-works/pi-coding-agent": "^0.74.0 || ^0.75.0 || ^0.77.0 || ^0.78.0 || ^0.79.0",
-    "@earendil-works/pi-tui": "^0.74.0 || ^0.75.0 || ^0.77.0 || ^0.78.0 || ^0.79.0"
+    "@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/index.ts

@@ -1,14 +1,28 @@
 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) {

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 };
+}