pi-formatter 0.1.1 → 0.3.0

package/README.md

@@ -1,11 +1,11 @@
 # 🎨 pi-formatter
 
-A [pi](https://github.com/badlogic/pi-mono/tree/main/packages/coding-agent)
-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:
 
@@ -28,13 +38,48 @@ Supported file types:
 - Python
 - JavaScript/TypeScript
 
+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
 
-- `PI_FORMAT_COMMAND_TIMEOUT_MS`: timeout (ms) per formatter command (default: `10000`)
+Create `<agent-dir>/formatter.json`, where `<agent-dir>` is pi's agent config
+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`)
+
+## 🧩 Adding formatters
+
+Each formatter is a _runner_ that wraps a CLI tool behind a common interface.
+To add one:
 
-## 🧩 Contributor docs
+1. Create a file in `extensions/formatter/runners/` using `defineRunner` and a
+   launcher helper (`direct`, `pypi`, or `goTool`).
+2. Register it in `extensions/formatter/runners/index.ts`.
+3. Add its id to a group in `extensions/formatter/plan.ts`.
 
-See the [runner API contract](DOCUMENTATION.md) for how to add new formatters.
+The format plan maps file kinds to ordered runner groups. Each group runs in
+`"all"` mode (every runner) or `"fallback"` mode (first match wins).
 
 ## 📄 License
 

package/extensions/formatter/config.ts

@@ -0,0 +1,140 @@
+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";
+
+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,
+};
+
+export function getFormatterConfigPath(): string {
+  return join(getAgentDir(), FORMATTER_CONFIG_FILE);
+}
+
+function readJsonObject(filePath: string): Record<string, unknown> | undefined {
+  try {
+    if (!existsSync(filePath)) {
+      return undefined;
+    }
+
+    const content = readFileSync(filePath, "utf8");
+    const parsed = JSON.parse(content);
+
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+      return undefined;
+    }
+
+    return parsed as Record<string, unknown>;
+  } catch {
+    return undefined;
+  }
+}
+
+function parsePositiveInt(value: unknown, defaultValue: number): number {
+  if (typeof value !== "number") {
+    return defaultValue;
+  }
+
+  if (!Number.isInteger(value) || value <= 0) {
+    return defaultValue;
+  }
+
+  return value;
+}
+
+function parseBooleanValue(value: unknown, defaultValue: boolean): boolean {
+  if (typeof value !== "boolean") {
+    return defaultValue;
+  }
+
+  return value;
+}
+
+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 { ...DEFAULT_FORMATTER_CONFIG };
+  }
+
+  return {
+    commandTimeoutMs: parsePositiveInt(
+      config.commandTimeoutMs,
+      DEFAULT_COMMAND_TIMEOUT_MS,
+    ),
+    hideCallSummariesInTui: parseBooleanValue(
+      config.hideCallSummariesInTui,
+      DEFAULT_HIDE_CALL_SUMMARIES_IN_TUI,
+    ),
+    formatMode: parseFormatMode(config.formatMode, DEFAULT_FORMAT_MODE),
+    formatOnAbort: parseBooleanValue(
+      config.formatOnAbort,
+      DEFAULT_FORMAT_ON_ABORT,
+    ),
+  };
+}
+
+export function cloneFormatterConfig(
+  config: FormatterConfigSnapshot,
+): FormatterConfigSnapshot {
+  return {
+    commandTimeoutMs: config.commandTimeoutMs,
+    hideCallSummariesInTui: config.hideCallSummariesInTui,
+    formatMode: config.formatMode,
+    formatOnAbort: config.formatOnAbort,
+  };
+}
+
+export function writeFormatterConfigSnapshot(
+  config: FormatterConfigSnapshot,
+): void {
+  writeFormatterConfigFile(
+    `${JSON.stringify(toFormatterConfigObject(config), null, 2)}\n`,
+  );
+}

package/extensions/{format → formatter}/context.ts

@@ -3,7 +3,7 @@ import { dirname, join, resolve } from "node:path";
 import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
 import { getPathForGit, isWithinDirectory, pathExists } from "./path.js";
 import { hasCommand } from "./system.js";
-import type { FileKind, RequiredMajorVersion, RunnerContext, SourceTool } from "./types.js";
+import type { FileKind, RequiredMajorVersion, RunnerContext } from "./types.js";
 
 const globRegexCache = new Map<string, RegExp>();
 
@@ -66,14 +66,44 @@ async function findConfigFileFromPath(
   return undefined;
 }
 
+function getLineRangesFromDiff(diffOutput: string): string[] {
+  const ranges: string[] = [];
+
+  for (const line of diffOutput.split(/\r?\n/)) {
+    const match = line.match(/^@@ .* \+([0-9]+)(?:,([0-9]+))? @@/);
+    if (!match) {
+      continue;
+    }
+
+    const start = Number.parseInt(match[1], 10);
+    const count = match[2] ? Number.parseInt(match[2], 10) : 1;
+
+    if (!Number.isFinite(start) || !Number.isFinite(count) || count <= 0) {
+      continue;
+    }
+
+    ranges.push(`${start}:${start + count - 1}`);
+  }
+
+  return ranges;
+}
+
+function compareLineRanges(a: string, b: string): number {
+  const [aStart] = a.split(":", 1);
+  const [bStart] = b.split(":", 1);
+  return Number.parseInt(aStart, 10) - Number.parseInt(bStart, 10);
+}
+
+export type FormatWarningReporter = (message: string) => void;
+
 export class FormatRunContext implements RunnerContext {
   readonly filePath: string;
   readonly cwd: string;
-  readonly sourceTool: SourceTool;
   readonly kind: FileKind;
 
   private readonly pi: ExtensionAPI;
   private readonly timeoutMs: number;
+  private readonly warningReporter?: FormatWarningReporter;
 
   private readonly configLookupCache = new Map<
     string,
@@ -95,23 +125,25 @@ export class FormatRunContext implements RunnerContext {
     pi: ExtensionAPI,
     cwd: string,
     filePath: string,
-    sourceTool: SourceTool,
     kind: FileKind,
     timeoutMs: number,
+    warningReporter?: FormatWarningReporter,
   ) {
     this.pi = pi;
     this.cwd = cwd;
     this.filePath = filePath;
-    this.sourceTool = sourceTool;
     this.kind = kind;
     this.timeoutMs = timeoutMs;
+    this.warningReporter = warningReporter;
   }
 
   async hasCommand(command: string): Promise<boolean> {
     return hasCommand(command);
   }
 
-  async findConfigFile(patterns: readonly string[]): Promise<string | undefined> {
+  async findConfigFile(
+    patterns: readonly string[],
+  ): Promise<string | undefined> {
     const key = patterns.join("\u0000");
     let cached = this.configLookupCache.get(key);
 
@@ -136,14 +168,10 @@ export class FormatRunContext implements RunnerContext {
   }
 
   async exec(command: string, args: string[]) {
-    try {
-      return await this.pi.exec(command, args, {
-        cwd: this.cwd,
-        timeout: this.timeoutMs,
-      });
-    } catch {
-      return undefined;
-    }
+    return this.pi.exec(command, args, {
+      cwd: this.cwd,
+      timeout: this.timeoutMs,
+    });
   }
 
   async getChangedLines(): Promise<string[]> {
@@ -182,6 +210,11 @@ export class FormatRunContext implements RunnerContext {
   }
 
   warn(message: string): void {
+    if (this.warningReporter) {
+      this.warningReporter(message);
+      return;
+    }
+
     console.warn(message);
   }
 
@@ -207,37 +240,25 @@ export class FormatRunContext implements RunnerContext {
 
   private async resolveChangedLines(): Promise<string[]> {
     const gitPath = getPathForGit(this.filePath, this.cwd);
-    const diffResult = await this.exec("git", [
-      "diff",
-      "--cached",
-      "--unified=0",
-      "--",
-      gitPath,
-    ]);
-
-    if (!diffResult || diffResult.code !== 0) {
-      return [];
-    }
+    const rangeSet = new Set<string>();
 
-    const ranges: string[] = [];
+    const diffArgSets = [
+      ["diff", "--unified=0", "--", gitPath],
+      ["diff", "--cached", "--unified=0", "--", gitPath],
+    ];
 
-    for (const line of diffResult.stdout.split(/\r?\n/)) {
-      const match = line.match(/^@@ .* \+([0-9]+)(?:,([0-9]+))? @@/);
-      if (!match) {
+    for (const args of diffArgSets) {
+      const diffResult = await this.exec("git", args);
+      if (diffResult.code !== 0) {
         continue;
       }
 
-      const start = Number.parseInt(match[1], 10);
-      const count = match[2] ? Number.parseInt(match[2], 10) : 1;
-
-      if (!Number.isFinite(start) || !Number.isFinite(count) || count <= 0) {
-        continue;
+      for (const range of getLineRangesFromDiff(diffResult.stdout)) {
+        rangeSet.add(range);
       }
-
-      ranges.push(`${start}:${start + count - 1}`);
     }
 
-    return ranges;
+    return [...rangeSet].sort(compareLineRanges);
   }
 
   private async resolveRequiredMajorVersionFromConfig(
@@ -266,7 +287,7 @@ export class FormatRunContext implements RunnerContext {
     command: string,
   ): Promise<string | undefined> {
     const result = await this.exec(command, ["--version"]);
-    if (!result || result.code !== 0) {
+    if (result.code !== 0) {
       return undefined;
     }
 

package/extensions/{format → formatter}/dispatch.ts

@@ -1,28 +1,17 @@
-import type { ExtensionAPI, ExecResult } from "@mariozechner/pi-coding-agent";
-import { FormatRunContext } from "./context.js";
+import type { ExecResult, ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import { FormatRunContext, type FormatWarningReporter } from "./context.js";
 import { detectFileKind } from "./path.js";
 import { FORMAT_PLAN } from "./plan.js";
 import { RUNNERS } from "./runners/index.js";
 import {
   isDynamicRunner,
   type ResolvedLauncher,
+  type RunnerContext,
   type RunnerDefinition,
   type RunnerGroup,
   type RunnerLauncher,
-  type RunnerContext,
-  type SourceTool,
 } from "./types.js";
 
-function summarizeExecResult(result: ExecResult): string {
-  const output = `${result.stderr}\n${result.stdout}`.trim();
-  if (!output) {
-    return "";
-  }
-
-  const firstLine = output.split(/\r?\n/, 1)[0];
-  return `: ${firstLine}`;
-}
-
 async function resolveLauncher(
   launcher: RunnerLauncher,
   ctx: RunnerContext,
@@ -93,15 +82,17 @@ async function satisfiesRunnerRequirements(
     const onInvalid = requirement.onInvalid ?? "warn-skip";
     if (onInvalid === "warn-skip") {
       ctx.warn(
-        `[pi-formatter] ${runner.id} skipped: invalid version requirement in ${requirement.patterns.join(", ")}`,
+        `${runner.id} skipped: invalid version requirement in ${requirement.patterns.join(", ")}`,
       );
     }
 
     return false;
   }
 
-  const versionCommand = requirement.command ?? defaultVersionCommand(runner.launcher);
-  const installedVersion = await ctx.getInstalledToolMajorVersion(versionCommand);
+  const versionCommand =
+    requirement.command ?? defaultVersionCommand(runner.launcher);
+  const installedVersion =
+    await ctx.getInstalledToolMajorVersion(versionCommand);
 
   if (installedVersion === requiredVersion) {
     return true;
@@ -110,7 +101,7 @@ async function satisfiesRunnerRequirements(
   const onMismatch = requirement.onMismatch ?? "warn-skip";
   if (onMismatch === "warn-skip") {
     ctx.warn(
-      `[pi-formatter] ${runner.id} skipped: ${versionCommand} version mismatch (have ${installedVersion ?? "unknown"}, need ${requiredVersion})`,
+      `${runner.id} skipped: ${versionCommand} version mismatch (have ${installedVersion ?? "unknown"}, need ${requiredVersion})`,
     );
   }
 
@@ -135,9 +126,56 @@ async function resolveRunnerArgs(
 
 type RunnerOutcome = "skipped" | "failed" | "succeeded";
 
+export interface FormatCallSummary {
+  runnerId: string;
+  status: "succeeded" | "failed";
+  exitCode?: number;
+  failureMessage?: string;
+}
+
+export type FormatCallSummaryReporter = (summary: FormatCallSummary) => void;
+
+const MAX_FAILURE_MESSAGE_LENGTH = 140;
+const ANSI_ESCAPE = String.fromCharCode(27);
+const ANSI_COLOR_SEQUENCE_PATTERN = new RegExp(
+  `${ANSI_ESCAPE}\\[[0-9;]*m`,
+  "g",
+);
+
+function normalizeFailureLine(line: string): string {
+  return line
+    .replace(ANSI_COLOR_SEQUENCE_PATTERN, "")
+    .replace(/^\s*\[error\]\s*/i, "")
+    .replace(/^\s*error:\s*/i, "")
+    .replace(/^\s*[×✖✘]\s*/u, "")
+    .replace(/\s+/g, " ")
+    .trim();
+}
+
+function summarizeFailureMessage(result: ExecResult): string | undefined {
+  const lines = `${result.stderr}\n${result.stdout}`
+    .split(/\r?\n/)
+    .map((line) => normalizeFailureLine(line))
+    .filter((line) => line.length > 0);
+
+  if (lines.length === 0) {
+    return undefined;
+  }
+
+  const withMarker = lines.find((line) =>
+    /\b(error|failed|invalid|unexpected|expected|syntax)\b/i.test(line),
+  );
+  const message = withMarker ?? lines[0];
+
+  return message.length <= MAX_FAILURE_MESSAGE_LENGTH
+    ? message
+    : `${message.slice(0, MAX_FAILURE_MESSAGE_LENGTH - 1)}…`;
+}
+
 async function runRunner(
   ctx: RunnerContext,
   runner: RunnerDefinition,
+  summaryReporter?: FormatCallSummaryReporter,
 ): Promise<RunnerOutcome> {
   const launcher = await resolveLauncher(runner.launcher, ctx);
   if (!launcher) {
@@ -157,60 +195,104 @@ async function runRunner(
     return "skipped";
   }
 
-  const result = await ctx.exec(launcher.command, [...launcher.argsPrefix, ...args]);
-  if (!result) {
-    ctx.warn(`[pi-formatter] ${runner.id} failed to execute`);
-    return "failed";
-  }
+  const commandArgs = [...launcher.argsPrefix, ...args];
+
+  const result = await ctx.exec(launcher.command, commandArgs);
 
   if (result.code !== 0) {
+    const failureMessage = summarizeFailureMessage(result);
+
+    summaryReporter?.({
+      runnerId: runner.id,
+      status: "failed",
+      exitCode: result.code,
+      failureMessage,
+    });
+
     ctx.warn(
-      `[pi-formatter] ${runner.id} exited with code ${result.code}${summarizeExecResult(result)}`,
+      `${runner.id} failed (${result.code})${failureMessage ? `: ${failureMessage}` : ""}`,
     );
     return "failed";
   }
 
+  summaryReporter?.({
+    runnerId: runner.id,
+    status: "succeeded",
+  });
+
   return "succeeded";
 }
 
 async function runRunnerGroup(
   ctx: RunnerContext,
   group: RunnerGroup,
+  summaryReporter?: FormatCallSummaryReporter,
 ): Promise<void> {
   if (group.mode === "all") {
     for (const runnerId of group.runnerIds) {
       const runner = RUNNERS.get(runnerId);
       if (!runner) {
-        ctx.warn(`[pi-formatter] unknown runner in format plan: ${runnerId}`);
+        ctx.warn(`unknown runner in format plan: ${runnerId}`);
         continue;
       }
 
-      await runRunner(ctx, runner);
+      await runRunner(ctx, runner, summaryReporter);
     }
 
     return;
   }
 
+  const fallbackSummaries: FormatCallSummary[] = [];
+  const fallbackSummaryReporter = summaryReporter
+    ? (summary: FormatCallSummary) => {
+        fallbackSummaries.push(summary);
+      }
+    : undefined;
+
   for (const runnerId of group.runnerIds) {
     const runner = RUNNERS.get(runnerId);
     if (!runner) {
-      ctx.warn(`[pi-formatter] unknown runner in format plan: ${runnerId}`);
+      ctx.warn(`unknown runner in format plan: ${runnerId}`);
       continue;
     }
 
-    const outcome = await runRunner(ctx, runner);
+    const outcome = await runRunner(ctx, runner, fallbackSummaryReporter);
     if (outcome === "succeeded") {
-      break;
+      if (!summaryReporter) {
+        return;
+      }
+
+      const successSummary = [...fallbackSummaries]
+        .reverse()
+        .find((summary) => summary.status === "succeeded");
+      if (successSummary) {
+        summaryReporter(successSummary);
+      }
+
+      return;
     }
   }
+
+  if (!summaryReporter) {
+    return;
+  }
+
+  const lastFailureSummary = [...fallbackSummaries]
+    .reverse()
+    .find((summary) => summary.status === "failed");
+
+  if (lastFailureSummary) {
+    summaryReporter(lastFailureSummary);
+  }
 }
 
 export async function formatFile(
   pi: ExtensionAPI,
   cwd: string,
-  sourceTool: SourceTool,
   filePath: string,
   timeoutMs: number,
+  summaryReporter?: FormatCallSummaryReporter,
+  warningReporter?: FormatWarningReporter,
 ): Promise<void> {
   const kind = detectFileKind(filePath);
   if (!kind) {
@@ -226,12 +308,12 @@ export async function formatFile(
     pi,
     cwd,
     filePath,
-    sourceTool,
     kind,
     timeoutMs,
+    warningReporter,
   );
 
   for (const group of groups) {
-    await runRunnerGroup(runContext, group);
+    await runRunnerGroup(runContext, group, summaryReporter);
   }
 }

package/extensions/{format → formatter}/path.ts

@@ -3,8 +3,17 @@ import { homedir } from "node:os";
 import { basename, isAbsolute, join, relative, resolve } from "node:path";
 import type { FileKind } from "./types.js";
 
+const UNICODE_SPACES = /[\u00A0\u2000-\u200A\u202F\u205F\u3000]/g;
+
+function normalizeUnicodeSpaces(value: string): string {
+  return value.replace(UNICODE_SPACES, " ");
+}
+
 export function normalizeToolPath(filePath: string): string {
-  const normalizedAt = filePath.startsWith("@") ? filePath.slice(1) : filePath;
+  const normalizedInput = normalizeUnicodeSpaces(filePath);
+  const normalizedAt = normalizedInput.startsWith("@")
+    ? normalizedInput.slice(1)
+    : normalizedInput;
 
   if (normalizedAt === "~") {
     return homedir();
@@ -33,7 +42,10 @@ export async function pathExists(path: string): Promise<boolean> {
   }
 }
 
-export function isWithinDirectory(pathToCheck: string, directory: string): boolean {
+export function isWithinDirectory(
+  pathToCheck: string,
+  directory: string,
+): boolean {
   const relPath = relative(directory, pathToCheck);
   return (
     relPath === "" ||
@@ -57,7 +69,11 @@ export function getPathForGit(filePath: string, cwd: string): string {
 }
 
 export function detectFileKind(filePath: string): FileKind | undefined {
-  if (/\.(cpp|hpp|cpp\.in|hpp\.in)$/.test(filePath)) {
+  if (
+    /(\.(c|h|cc|hh|cpp|hpp|cxx|hxx|ixx|ipp|inl|tpp)|\.(c|h|cc|hh|cpp|hpp|cxx|hxx)\.in)$/i.test(
+      filePath,
+    )
+  ) {
     return "cxx";
   }