pi-formatter 0.2.0 → 0.3.0

package/README.md

@@ -1,11 +1,11 @@
 # 🎨 pi-formatter
 
-A [pi](https://pi.dev) extension that auto-formats files after every `write` and
-`edit` tool call.
+A [pi](https://pi.dev) extension that auto-formats files after `write` and
+`edit` tool calls.
 
-The extension hooks into successful tool results, detects the file type, and
-runs the appropriate formatter. Failures never block the tool result, so
-formatting is always best-effort.
+By default, formatting runs after each successful tool result. It can also be
+configured to defer formatting until the agent stops and yields back to the
+user.
 
 ## 📦 Install
 
@@ -15,8 +15,18 @@ pi install npm:pi-formatter
 
 ## ⚙️ What it does
 
-`pi-formatter` listens to successful `write` and `edit` tool calls and applies
-best-effort formatting. Formatter failures never block tool results.
+`pi-formatter` detects file types and runs the appropriate formatter as
+best-effort post-processing. Formatter failures never block tool results.
+
+Formatting modes:
+
+- `afterEachToolCall`: format immediately after each successful `write` or
+  `edit` tool result. This is the default.
+- `afterAgentStop`: collect touched files during the run and format them once
+  the agent stops. This avoids mid-run model drift from formatter edits.
+
+When `afterAgentStop` is active, interrupted or canceled runs are not formatted
+unless `formatOnAbort` is enabled.
 
 Supported file types:
 
@@ -31,6 +41,11 @@ Supported file types:
 For JS/TS and JSON, project-configured tools are preferred first (Biome,
 ESLint), with Prettier as a fallback.
 
+## 🎮 Commands
+
+- `/formatter`: open the interactive formatter settings editor and save changes
+  to `formatter.json`
+
 ## 🔧 Configuration
 
 Create `<agent-dir>/formatter.json`, where `<agent-dir>` is pi's agent config
@@ -38,13 +53,20 @@ folder (default: `~/.pi/agent`, overridable via `PI_CODING_AGENT_DIR`):
 
 ```json
 {
+  "formatMode": "afterEachToolCall",
+  "formatOnAbort": false,
   "commandTimeoutMs": 10000,
   "hideCallSummariesInTui": false
 }
 ```
 
+- `formatMode`: formatting strategy
+  (`"afterEachToolCall"` | `"afterAgentStop"`, default: `"afterEachToolCall"`)
+- `formatOnAbort`: in deferred mode, also format files after an interrupted or
+  canceled run (default: `false`)
 - `commandTimeoutMs`: timeout (ms) per formatter command (default: `10000`)
-- `hideCallSummariesInTui`: hide formatter pass/fail summaries in the TUI (default: `false`)
+- `hideCallSummariesInTui`: hide formatter pass/fail summaries in the TUI
+  (default: `false`)
 
 ## 🧩 Adding formatters
 

package/extensions/formatter/config.ts

@@ -1,17 +1,35 @@
-import { existsSync, readFileSync } from "node:fs";
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  writeFileSync,
+} from "node:fs";
 import { join } from "node:path";
 import { getAgentDir } from "@mariozechner/pi-coding-agent";
 
+export type FormatMode = "afterEachToolCall" | "afterAgentStop";
+
 const DEFAULT_COMMAND_TIMEOUT_MS = 10_000;
 const DEFAULT_HIDE_CALL_SUMMARIES_IN_TUI = false;
+const DEFAULT_FORMAT_MODE: FormatMode = "afterEachToolCall";
+const DEFAULT_FORMAT_ON_ABORT = false;
 const FORMATTER_CONFIG_FILE = "formatter.json";
 
-type FormatterConfig = {
+export type FormatterConfigSnapshot = {
   commandTimeoutMs: number;
   hideCallSummariesInTui: boolean;
+  formatMode: FormatMode;
+  formatOnAbort: boolean;
+};
+
+export const DEFAULT_FORMATTER_CONFIG: FormatterConfigSnapshot = {
+  commandTimeoutMs: DEFAULT_COMMAND_TIMEOUT_MS,
+  hideCallSummariesInTui: DEFAULT_HIDE_CALL_SUMMARIES_IN_TUI,
+  formatMode: DEFAULT_FORMAT_MODE,
+  formatOnAbort: DEFAULT_FORMAT_ON_ABORT,
 };
 
-function getFormatterConfigPath(): string {
+export function getFormatterConfigPath(): string {
   return join(getAgentDir(), FORMATTER_CONFIG_FILE);
 }
 
@@ -54,14 +72,35 @@ function parseBooleanValue(value: unknown, defaultValue: boolean): boolean {
   return value;
 }
 
-function loadFormatterConfig(): FormatterConfig {
+function parseFormatMode(value: unknown, defaultValue: FormatMode): FormatMode {
+  if (value === "afterEachToolCall" || value === "afterAgentStop") {
+    return value;
+  }
+
+  return defaultValue;
+}
+
+function toFormatterConfigObject(
+  config: FormatterConfigSnapshot,
+): Record<string, unknown> {
+  return {
+    commandTimeoutMs: config.commandTimeoutMs,
+    hideCallSummariesInTui: config.hideCallSummariesInTui,
+    formatMode: config.formatMode,
+    formatOnAbort: config.formatOnAbort,
+  };
+}
+
+function writeFormatterConfigFile(content: string): void {
+  mkdirSync(getAgentDir(), { recursive: true });
+  writeFileSync(getFormatterConfigPath(), content, "utf8");
+}
+
+export function loadFormatterConfig(): FormatterConfigSnapshot {
   const config = readJsonObject(getFormatterConfigPath());
 
   if (!config) {
-    return {
-      commandTimeoutMs: DEFAULT_COMMAND_TIMEOUT_MS,
-      hideCallSummariesInTui: DEFAULT_HIDE_CALL_SUMMARIES_IN_TUI,
-    };
+    return { ...DEFAULT_FORMATTER_CONFIG };
   }
 
   return {
@@ -73,10 +112,29 @@ function loadFormatterConfig(): FormatterConfig {
       config.hideCallSummariesInTui,
       DEFAULT_HIDE_CALL_SUMMARIES_IN_TUI,
     ),
+    formatMode: parseFormatMode(config.formatMode, DEFAULT_FORMAT_MODE),
+    formatOnAbort: parseBooleanValue(
+      config.formatOnAbort,
+      DEFAULT_FORMAT_ON_ABORT,
+    ),
   };
 }
 
-const formatterConfig = loadFormatterConfig();
+export function cloneFormatterConfig(
+  config: FormatterConfigSnapshot,
+): FormatterConfigSnapshot {
+  return {
+    commandTimeoutMs: config.commandTimeoutMs,
+    hideCallSummariesInTui: config.hideCallSummariesInTui,
+    formatMode: config.formatMode,
+    formatOnAbort: config.formatOnAbort,
+  };
+}
 
-export const commandTimeoutMs = formatterConfig.commandTimeoutMs;
-export const hideCallSummariesInTui = formatterConfig.hideCallSummariesInTui;
+export function writeFormatterConfigSnapshot(
+  config: FormatterConfigSnapshot,
+): void {
+  writeFormatterConfigFile(
+    `${JSON.stringify(toFormatterConfigObject(config), null, 2)}\n`,
+  );
+}

package/extensions/index.ts

@@ -1,12 +1,17 @@
 import { basename } from "node:path";
 import {
   type ExtensionAPI,
+  getSettingsListTheme,
   isEditToolResult,
   isWriteToolResult,
 } from "@mariozechner/pi-coding-agent";
+import { Container, type SettingItem, SettingsList, Text } from "@mariozechner/pi-tui";
 import {
-  commandTimeoutMs,
-  hideCallSummariesInTui,
+  cloneFormatterConfig,
+  type FormatterConfigSnapshot,
+  getFormatterConfigPath,
+  loadFormatterConfig,
+  writeFormatterConfigSnapshot,
 } from "./formatter/config.js";
 import { type FormatCallSummary, formatFile } from "./formatter/dispatch.js";
 import {
@@ -42,8 +47,66 @@ function formatCallFailureSummary(summary: FormatCallSummary): string {
   return `✘ ${summary.runnerId}`;
 }
 
+function resolveEventPath(rawPath: unknown, cwd: string): string | undefined {
+  if (typeof rawPath !== "string" || rawPath.length === 0) {
+    return undefined;
+  }
+
+  return resolveToolPath(rawPath, cwd);
+}
+
+function getFormatterSettingItems(
+  config: FormatterConfigSnapshot,
+): SettingItem[] {
+  const timeoutValues = ["2000", "5000", "10000", "30000", "60000"];
+
+  if (!timeoutValues.includes(String(config.commandTimeoutMs))) {
+    timeoutValues.push(String(config.commandTimeoutMs));
+    timeoutValues.sort(
+      (a, b) => Number.parseInt(a, 10) - Number.parseInt(b, 10),
+    );
+  }
+
+  return [
+    {
+      id: "formatMode",
+      label: "Format mode",
+      description:
+        "Choose whether formatting runs after each successful write/edit tool call or once after the agent stops.",
+      currentValue: config.formatMode,
+      values: ["afterEachToolCall", "afterAgentStop"],
+    },
+    {
+      id: "formatOnAbort",
+      label: "Format on abort",
+      description:
+        "When enabled, deferred formatting also runs if the model is interrupted or cancelled.",
+      currentValue: config.formatOnAbort ? "on" : "off",
+      values: ["off", "on"],
+    },
+    {
+      id: "commandTimeoutMs",
+      label: "Command timeout",
+      description: "Maximum runtime per formatter command in milliseconds.",
+      currentValue: String(config.commandTimeoutMs),
+      values: timeoutValues,
+    },
+    {
+      id: "hideCallSummariesInTui",
+      label: "Hide TUI summaries",
+      description:
+        "Hide per-run formatter pass/fail summaries in the interactive UI.",
+      currentValue: config.hideCallSummariesInTui ? "on" : "off",
+      values: ["off", "on"],
+    },
+  ];
+}
+
 export default function (pi: ExtensionAPI) {
+  let formatterConfig = loadFormatterConfig();
   const formatQueueByPath = new Map<string, Promise<void>>();
+  const candidatePaths = new Set<string>();
+  const successfulPaths = new Set<string>();
 
   const enqueueFormat = async (
     filePath: string,
@@ -65,27 +128,21 @@ export default function (pi: ExtensionAPI) {
     await next;
   };
 
-  pi.on("tool_result", async (event, ctx) => {
-    if (event.isError) {
-      return;
-    }
-
-    if (!isWriteToolResult(event) && !isEditToolResult(event)) {
-      return;
-    }
-
-    const rawPath = event.input.path;
-    if (rawPath.length === 0) {
-      return;
-    }
-
-    const filePath = resolveToolPath(rawPath, ctx.cwd);
-
+  const formatResolvedPath = async (
+    filePath: string,
+    ctx: {
+      cwd: string;
+      hasUI: boolean;
+      ui: {
+        notify(message: string, level: "info" | "warning" | "error"): void;
+      };
+    },
+  ): Promise<void> => {
     if (!(await pathExists(filePath))) {
       return;
     }
 
-    const showSummaries = !hideCallSummariesInTui && ctx.hasUI;
+    const showSummaries = !formatterConfig.hideCallSummariesInTui && ctx.hasUI;
     const notifyWarning = (message: string) => {
       const normalizedMessage = message.replace(/\s+/g, " ").trim();
 
@@ -117,7 +174,7 @@ export default function (pi: ExtensionAPI) {
           pi,
           ctx.cwd,
           filePath,
-          commandTimeoutMs,
+          formatterConfig.commandTimeoutMs,
           summaryReporter,
           runnerWarningReporter,
         );
@@ -139,5 +196,182 @@ export default function (pi: ExtensionAPI) {
         ctx.ui.notify(formatCallFailureSummary(summary), "info");
       }
     });
+  };
+
+  const reloadFormatterConfig = () => {
+    formatterConfig = loadFormatterConfig();
+  };
+
+  pi.on("agent_start", async () => {
+    candidatePaths.clear();
+    successfulPaths.clear();
+  });
+
+  pi.on("tool_call", async (event, ctx) => {
+    if (formatterConfig.formatMode !== "afterAgentStop") {
+      return;
+    }
+
+    if (event.toolName !== "write" && event.toolName !== "edit") {
+      return;
+    }
+
+    const filePath = resolveEventPath(event.input.path, ctx.cwd);
+    if (filePath) {
+      candidatePaths.add(filePath);
+    }
+  });
+
+  pi.on("tool_result", async (event, ctx) => {
+    if (!isWriteToolResult(event) && !isEditToolResult(event)) {
+      return;
+    }
+
+    const filePath = resolveEventPath(event.input.path, ctx.cwd);
+    if (!filePath) {
+      return;
+    }
+
+    if (!event.isError) {
+      successfulPaths.add(filePath);
+    }
+
+    if (formatterConfig.formatMode !== "afterEachToolCall" || event.isError) {
+      return;
+    }
+
+    await formatResolvedPath(filePath, ctx);
+  });
+
+  pi.on("agent_end", async (event, ctx) => {
+    if (formatterConfig.formatMode !== "afterAgentStop") {
+      candidatePaths.clear();
+      successfulPaths.clear();
+      return;
+    }
+
+    let lastAssistantStopReason: string | undefined;
+    for (let index = event.messages.length - 1; index >= 0; index -= 1) {
+      const message = event.messages[index];
+      if (message.role !== "assistant") {
+        continue;
+      }
+
+      lastAssistantStopReason = message.stopReason;
+      break;
+    }
+
+    const pathsToFormat = new Set<string>();
+    if (lastAssistantStopReason === "aborted") {
+      if (formatterConfig.formatOnAbort) {
+        for (const filePath of candidatePaths) {
+          pathsToFormat.add(filePath);
+        }
+        for (const filePath of successfulPaths) {
+          pathsToFormat.add(filePath);
+        }
+      }
+    } else {
+      for (const filePath of successfulPaths) {
+        pathsToFormat.add(filePath);
+      }
+    }
+
+    candidatePaths.clear();
+    successfulPaths.clear();
+
+    for (const filePath of pathsToFormat) {
+      await formatResolvedPath(filePath, ctx);
+    }
+  });
+
+  pi.registerCommand("formatter", {
+    description: "Configure formatter behavior.",
+    handler: async (_args, ctx) => {
+      if (!ctx.hasUI) {
+        console.warn("/formatter requires interactive UI mode");
+        return;
+      }
+
+      const configPath = getFormatterConfigPath();
+      reloadFormatterConfig();
+      const draft = cloneFormatterConfig(formatterConfig);
+
+      await ctx.ui.custom((tui, theme, _kb, done) => {
+        const container = new Container();
+        container.addChild(
+          new Text(theme.fg("accent", theme.bold("Formatter Settings")), 1, 0),
+        );
+        container.addChild(new Text(theme.fg("dim", configPath), 1, 0));
+        container.addChild(new Text("", 0, 0));
+
+        const syncDraftToSettingsList = (settingsList: SettingsList) => {
+          settingsList.updateValue("formatMode", draft.formatMode);
+          settingsList.updateValue(
+            "formatOnAbort",
+            draft.formatOnAbort ? "on" : "off",
+          );
+          settingsList.updateValue(
+            "commandTimeoutMs",
+            String(draft.commandTimeoutMs),
+          );
+          settingsList.updateValue(
+            "hideCallSummariesInTui",
+            draft.hideCallSummariesInTui ? "on" : "off",
+          );
+        };
+
+        const settingsList = new SettingsList(
+          getFormatterSettingItems(draft),
+          8,
+          getSettingsListTheme(),
+          (id, newValue) => {
+            const previous = cloneFormatterConfig(draft);
+
+            if (id === "formatMode") {
+              draft.formatMode = newValue as FormatterConfigSnapshot["formatMode"];
+            } else if (id === "formatOnAbort") {
+              draft.formatOnAbort = newValue === "on";
+            } else if (id === "commandTimeoutMs") {
+              draft.commandTimeoutMs = Number.parseInt(newValue, 10);
+            } else if (id === "hideCallSummariesInTui") {
+              draft.hideCallSummariesInTui = newValue === "on";
+            }
+
+            try {
+              writeFormatterConfigSnapshot(draft);
+              reloadFormatterConfig();
+            } catch (error) {
+              const message =
+                error instanceof Error ? error.message : String(error);
+              draft.commandTimeoutMs = previous.commandTimeoutMs;
+              draft.hideCallSummariesInTui = previous.hideCallSummariesInTui;
+              draft.formatMode = previous.formatMode;
+              draft.formatOnAbort = previous.formatOnAbort;
+              syncDraftToSettingsList(settingsList);
+              ctx.ui.notify(`Failed to save config: ${message}`, "error");
+            }
+          },
+          () => {
+            done(undefined);
+          },
+        );
+
+        container.addChild(settingsList);
+
+        return {
+          render(width: number) {
+            return container.render(width);
+          },
+          invalidate() {
+            container.invalidate();
+          },
+          handleInput(data: string) {
+            settingsList.handleInput?.(data);
+            tui.requestRender();
+          },
+        };
+      });
+    },
   });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-formatter",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Pi extension that auto-formats files after write/edit tool calls.",
   "type": "module",
   "files": [