pi-formatter 0.2.0 → 1.0.0

package/README.md

@@ -1,11 +1,13 @@
 # 🎨 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 once per turn. You can also format after each tool
+call or defer formatting until the current session shuts down.
+
+This default changed from the previous immediate-per-tool behavior. If you want
+the old default, set `"formatMode": "tool"`.
 
 ## 📦 Install
 
@@ -15,8 +17,24 @@ 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:
+
+- `tool`: format immediately after each successful `write` or `edit` tool
+  result.
+  Use this mode when you want the file on disk to stay formatted after every
+  edit, even while the agent is still working.
+- `turn`: collect files touched during the current turn and format them once at
+  `turn_end`. This is the default.
+  Use this mode when you want to avoid mid-turn formatter drift while still
+  keeping files formatted throughout the run.
+- `session`: collect files touched during the current session and format them
+  once at `session_shutdown`.
+  Use this mode when you want the fewest formatter interruptions and are okay
+  with formatting only when the session exits, reloads, or switches. Interrupted
+  runs stay pending until the session ends or changes.
 
 Supported file types:
 
@@ -31,6 +49,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 +61,17 @@ folder (default: `~/.pi/agent`, overridable via `PI_CODING_AGENT_DIR`):
 
 ```json
 {
+  "formatMode": "turn",
   "commandTimeoutMs": 10000,
   "hideCallSummariesInTui": false
 }
 ```
 
+- `formatMode`: formatting strategy (`"tool"` | `"turn"` | `"session"`,
+  default: `"turn"`). Use `"tool"` to restore the old immediate default.
 - `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,27 @@
-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 = "tool" | "turn" | "session";
+
 const DEFAULT_COMMAND_TIMEOUT_MS = 10_000;
 const DEFAULT_HIDE_CALL_SUMMARIES_IN_TUI = false;
+const DEFAULT_FORMAT_MODE: FormatMode = "turn";
 const FORMATTER_CONFIG_FILE = "formatter.json";
 
-type FormatterConfig = {
+export type FormatterConfigSnapshot = {
   commandTimeoutMs: number;
   hideCallSummariesInTui: boolean;
+  formatMode: FormatMode;
+};
+
+export const DEFAULT_FORMATTER_CONFIG: FormatterConfigSnapshot = {
+  commandTimeoutMs: DEFAULT_COMMAND_TIMEOUT_MS,
+  hideCallSummariesInTui: DEFAULT_HIDE_CALL_SUMMARIES_IN_TUI,
+  formatMode: DEFAULT_FORMAT_MODE,
 };
 
-function getFormatterConfigPath(): string {
+export function getFormatterConfigPath(): string {
   return join(getAgentDir(), FORMATTER_CONFIG_FILE);
 }
 
@@ -54,14 +64,34 @@ function parseBooleanValue(value: unknown, defaultValue: boolean): boolean {
   return value;
 }
 
-function loadFormatterConfig(): FormatterConfig {
+function parseFormatMode(value: unknown, defaultValue: FormatMode): FormatMode {
+  if (value === "tool" || value === "turn" || value === "session") {
+    return value;
+  }
+
+  return defaultValue;
+}
+
+function toFormatterConfigObject(
+  config: FormatterConfigSnapshot,
+): Record<string, unknown> {
+  return {
+    commandTimeoutMs: config.commandTimeoutMs,
+    hideCallSummariesInTui: config.hideCallSummariesInTui,
+    formatMode: config.formatMode,
+  };
+}
+
+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 +103,24 @@ function loadFormatterConfig(): FormatterConfig {
       config.hideCallSummariesInTui,
       DEFAULT_HIDE_CALL_SUMMARIES_IN_TUI,
     ),
+    formatMode: parseFormatMode(config.formatMode, DEFAULT_FORMAT_MODE),
   };
 }
 
-const formatterConfig = loadFormatterConfig();
+export function cloneFormatterConfig(
+  config: FormatterConfigSnapshot,
+): FormatterConfigSnapshot {
+  return {
+    commandTimeoutMs: config.commandTimeoutMs,
+    hideCallSummariesInTui: config.hideCallSummariesInTui,
+    formatMode: config.formatMode,
+  };
+}
 
-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/formatter/context.ts

@@ -1,7 +1,11 @@
 import { readdir, readFile } from "node:fs/promises";
 import { dirname, join, resolve } from "node:path";
 import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
-import { getPathForGit, isWithinDirectory, pathExists } from "./path.js";
+import {
+  getRelativePathOrAbsolute,
+  isWithinDirectory,
+  pathExists,
+} from "./path.js";
 import { hasCommand } from "./system.js";
 import type { FileKind, RequiredMajorVersion, RunnerContext } from "./types.js";
 
@@ -239,12 +243,12 @@ export class FormatRunContext implements RunnerContext {
   }
 
   private async resolveChangedLines(): Promise<string[]> {
-    const gitPath = getPathForGit(this.filePath, this.cwd);
+    const diffPath = getRelativePathOrAbsolute(this.filePath, this.cwd);
     const rangeSet = new Set<string>();
 
     const diffArgSets = [
-      ["diff", "--unified=0", "--", gitPath],
-      ["diff", "--cached", "--unified=0", "--", gitPath],
+      ["diff", "--unified=0", "--", diffPath],
+      ["diff", "--cached", "--unified=0", "--", diffPath],
     ];
 
     for (const args of diffArgSets) {

package/extensions/formatter/path.ts

@@ -54,8 +54,11 @@ export function isWithinDirectory(
   );
 }
 
-export function getPathForGit(filePath: string, cwd: string): string {
-  const relPath = relative(cwd, filePath);
+export function getRelativePathOrAbsolute(
+  filePath: string,
+  directory: string,
+): string {
+  const relPath = relative(directory, filePath);
   if (
     !relPath ||
     relPath === "." ||

package/extensions/index.ts

@@ -1,49 +1,119 @@
-import { basename } from "node:path";
 import {
   type ExtensionAPI,
+  getSettingsListTheme,
   isEditToolResult,
   isWriteToolResult,
 } from "@mariozechner/pi-coding-agent";
 import {
-  commandTimeoutMs,
-  hideCallSummariesInTui,
+  Container,
+  type SettingItem,
+  SettingsList,
+  Text,
+} from "@mariozechner/pi-tui";
+import {
+  cloneFormatterConfig,
+  type FormatterConfigSnapshot,
+  getFormatterConfigPath,
+  loadFormatterConfig,
+  writeFormatterConfigSnapshot,
 } from "./formatter/config.js";
 import { type FormatCallSummary, formatFile } from "./formatter/dispatch.js";
 import {
-  getPathForGit,
+  getRelativePathOrAbsolute,
   pathExists,
   resolveToolPath,
 } from "./formatter/path.js";
 
+function normalizeSummaryMessage(message: string): string {
+  return message.replace(/\s+/g, " ").trim();
+}
+
 function formatError(error: unknown): string {
   return error instanceof Error ? error.message : String(error);
 }
 
-function formatSummaryPath(filePath: string, cwd: string): string {
-  const pathForDisplay = getPathForGit(filePath, cwd);
-  return pathForDisplay.startsWith("/")
-    ? basename(pathForDisplay)
-    : pathForDisplay;
-}
+function formatCallSummary(
+  summary: FormatCallSummary,
+  fileLabel: string,
+): string {
+  const prefix = summary.status === "succeeded" ? "✔︎" : "✘";
+  const base = `${prefix} ${summary.runnerId}: ${fileLabel}`;
 
-function formatCallSuccessSummary(summary: FormatCallSummary): string {
-  return `✔︎ ${summary.runnerId}`;
-}
+  if (summary.status === "succeeded") {
+    return base;
+  }
 
-function formatCallFailureSummary(summary: FormatCallSummary): string {
   if (summary.failureMessage) {
-    return `✘ ${summary.runnerId}: ${summary.failureMessage}`;
+    return `${base}: ${normalizeSummaryMessage(summary.failureMessage)}`;
   }
 
   if (summary.exitCode !== undefined) {
-    return `✘ ${summary.runnerId} (exit ${summary.exitCode})`;
+    return `${base} (exit ${summary.exitCode})`;
+  }
+
+  return base;
+}
+
+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 `✘ ${summary.runnerId}`;
+  return [
+    {
+      id: "formatMode",
+      label: "Format mode",
+      description:
+        "Choose whether formatting runs after each successful write/edit tool call, once after each turn, or once when the session shuts down.",
+      currentValue: config.formatMode,
+      values: ["tool", "turn", "session"],
+    },
+    {
+      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"],
+    },
+  ];
 }
 
+type FormatterContext = {
+  cwd: string;
+  hasUI: boolean;
+  ui: {
+    notify(message: string, level: "info" | "warning" | "error"): void;
+  };
+};
+
 export default function (pi: ExtensionAPI) {
+  let formatterConfig = loadFormatterConfig();
   const formatQueueByPath = new Map<string, Promise<void>>();
+  const pendingTurnPaths = new Set<string>();
+  const pendingSessionPaths = new Set<string>();
 
   const enqueueFormat = async (
     filePath: string,
@@ -65,29 +135,17 @@ 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: FormatterContext,
+  ): 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();
+      const normalizedMessage = normalizeSummaryMessage(message);
 
       if (ctx.hasUI) {
         ctx.ui.notify(normalizedMessage, "warning");
@@ -105,24 +163,23 @@ export default function (pi: ExtensionAPI) {
           }
         : undefined;
 
-      const runnerWarningReporter =
-        showSummaries && ctx.hasUI
-          ? () => {
-              // Summary mode already reports failures compactly.
-            }
-          : notifyWarning;
+      const runnerWarningReporter = showSummaries
+        ? () => {
+            // Summary mode already reports failures compactly.
+          }
+        : notifyWarning;
 
       try {
         await formatFile(
           pi,
           ctx.cwd,
           filePath,
-          commandTimeoutMs,
+          formatterConfig.commandTimeoutMs,
           summaryReporter,
           runnerWarningReporter,
         );
       } catch (error) {
-        const fileLabel = formatSummaryPath(filePath, ctx.cwd);
+        const fileLabel = getRelativePathOrAbsolute(filePath, ctx.cwd);
         notifyWarning(`Failed to format ${fileLabel}: ${formatError(error)}`);
       }
 
@@ -130,14 +187,189 @@ export default function (pi: ExtensionAPI) {
         return;
       }
 
-      for (const summary of summaries) {
-        if (summary.status === "succeeded") {
-          ctx.ui.notify(formatCallSuccessSummary(summary), "info");
-          continue;
-        }
+      const fileLabel = getRelativePathOrAbsolute(filePath, ctx.cwd);
 
-        ctx.ui.notify(formatCallFailureSummary(summary), "info");
+      for (const summary of summaries) {
+        ctx.ui.notify(formatCallSummary(summary, fileLabel), "info");
       }
     });
+  };
+
+  const flushPaths = async (
+    paths: Set<string>,
+    ctx: FormatterContext,
+  ): Promise<void> => {
+    const batch = [...paths];
+    paths.clear();
+
+    for (const filePath of batch) {
+      await formatResolvedPath(filePath, ctx);
+    }
+  };
+
+  const flushPendingPaths = async (ctx: FormatterContext): Promise<void> => {
+    await flushPaths(pendingTurnPaths, ctx);
+    await flushPaths(pendingSessionPaths, ctx);
+  };
+
+  const reloadFormatterConfig = () => {
+    formatterConfig = loadFormatterConfig();
+  };
+
+  pi.on("tool_result", async (event, ctx) => {
+    if (!isWriteToolResult(event) && !isEditToolResult(event)) {
+      return;
+    }
+
+    if (event.isError) {
+      return;
+    }
+
+    const filePath = resolveEventPath(event.input.path, ctx.cwd);
+    if (!filePath) {
+      return;
+    }
+
+    if (formatterConfig.formatMode === "tool") {
+      await formatResolvedPath(filePath, ctx);
+      return;
+    }
+
+    if (formatterConfig.formatMode === "turn") {
+      pendingTurnPaths.add(filePath);
+      return;
+    }
+
+    pendingSessionPaths.add(filePath);
+  });
+
+  pi.on("turn_end", async (_event, ctx) => {
+    if (pendingTurnPaths.size === 0) {
+      return;
+    }
+
+    await flushPaths(pendingTurnPaths, ctx);
+  });
+
+  pi.on("agent_end", async (_event, ctx) => {
+    if (pendingTurnPaths.size === 0) {
+      return;
+    }
+
+    await flushPaths(pendingTurnPaths, ctx);
+  });
+
+  pi.on("session_switch", async (_event, ctx) => {
+    if (pendingTurnPaths.size === 0 && pendingSessionPaths.size === 0) {
+      return;
+    }
+
+    await flushPendingPaths(ctx);
+  });
+
+  pi.on("session_shutdown", async (_event, ctx) => {
+    if (pendingTurnPaths.size === 0 && pendingSessionPaths.size === 0) {
+      return;
+    }
+
+    await flushPendingPaths(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(
+            "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 === "commandTimeoutMs") {
+              draft.commandTimeoutMs = Number.parseInt(newValue, 10);
+            } else if (id === "hideCallSummariesInTui") {
+              draft.hideCallSummariesInTui = newValue === "on";
+            }
+
+            try {
+              writeFormatterConfigSnapshot(draft);
+              reloadFormatterConfig();
+
+              if (
+                id === "formatMode" &&
+                previous.formatMode !== draft.formatMode
+              ) {
+                void flushPendingPaths(ctx).catch((error) => {
+                  const message =
+                    error instanceof Error ? error.message : String(error);
+                  ctx.ui.notify(
+                    `Failed to flush pending formats: ${message}`,
+                    "error",
+                  );
+                });
+              }
+            } catch (error) {
+              const message =
+                error instanceof Error ? error.message : String(error);
+              draft.commandTimeoutMs = previous.commandTimeoutMs;
+              draft.hideCallSummariesInTui = previous.hideCallSummariesInTui;
+              draft.formatMode = previous.formatMode;
+              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": "1.0.0",
   "description": "Pi extension that auto-formats files after write/edit tool calls.",
   "type": "module",
   "files": [