pi-formatter 0.1.0 → 0.2.0

package/README.md

@@ -1,7 +1,7 @@
 # 🎨 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 every `write` and
+`edit` tool call.
 
 The extension hooks into successful tool results, detects the file type, and
 runs the appropriate formatter. Failures never block the tool result, so
@@ -28,13 +28,36 @@ Supported file types:
 - Python
 - JavaScript/TypeScript
 
+For JS/TS and JSON, project-configured tools are preferred first (Biome,
+ESLint), with Prettier as a fallback.
+
 ## 🔧 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
+{
+  "commandTimeoutMs": 10000,
+  "hideCallSummariesInTui": 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,82 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { getAgentDir } from "@mariozechner/pi-coding-agent";
+
+const DEFAULT_COMMAND_TIMEOUT_MS = 10_000;
+const DEFAULT_HIDE_CALL_SUMMARIES_IN_TUI = false;
+const FORMATTER_CONFIG_FILE = "formatter.json";
+
+type FormatterConfig = {
+  commandTimeoutMs: number;
+  hideCallSummariesInTui: boolean;
+};
+
+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 loadFormatterConfig(): FormatterConfig {
+  const config = readJsonObject(getFormatterConfigPath());
+
+  if (!config) {
+    return {
+      commandTimeoutMs: DEFAULT_COMMAND_TIMEOUT_MS,
+      hideCallSummariesInTui: DEFAULT_HIDE_CALL_SUMMARIES_IN_TUI,
+    };
+  }
+
+  return {
+    commandTimeoutMs: parsePositiveInt(
+      config.commandTimeoutMs,
+      DEFAULT_COMMAND_TIMEOUT_MS,
+    ),
+    hideCallSummariesInTui: parseBooleanValue(
+      config.hideCallSummariesInTui,
+      DEFAULT_HIDE_CALL_SUMMARIES_IN_TUI,
+    ),
+  };
+}
+
+const formatterConfig = loadFormatterConfig();
+
+export const commandTimeoutMs = formatterConfig.commandTimeoutMs;
+export const hideCallSummariesInTui = formatterConfig.hideCallSummariesInTui;

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

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

@@ -5,22 +5,22 @@ export const FORMAT_PLAN: Record<FileKind, RunnerGroup[]> = {
   cmake: [{ mode: "all", runnerIds: ["cmake-format"] }],
   markdown: [
     {
-      mode: "all",
-      runnerIds: ["markdownlint-fix", "prettier-markdown"],
+      mode: "fallback",
+      runnerIds: ["prettier", "markdownlint"],
     },
   ],
   json: [
     {
       mode: "fallback",
-      runnerIds: ["biome-check-write", "prettier-config-write"],
+      runnerIds: ["biome", "prettier"],
     },
   ],
   shell: [{ mode: "all", runnerIds: ["shfmt"] }],
-  python: [{ mode: "all", runnerIds: ["ruff-format", "ruff-check-fix"] }],
+  python: [{ mode: "all", runnerIds: ["ruff-format", "ruff-check"] }],
   jsts: [
     {
       mode: "fallback",
-      runnerIds: ["biome-check-write", "eslint-fix", "prettier-config-write"],
+      runnerIds: ["biome", "eslint", "prettier"],
     },
   ],
 };

package/extensions/{format/runners/biome-check-write.ts → formatter/runners/biome.ts}

@@ -1,11 +1,11 @@
-import { defineRunner, direct } from "./helpers.js";
 import { BIOME_CONFIG_PATTERNS } from "./config-patterns.js";
+import { defineRunner, direct } from "./helpers.js";
 
-const biomeCheckWriteRunner = defineRunner({
-  id: "biome-check-write",
+const biomeRunner = defineRunner({
+  id: "biome",
   launcher: direct("biome"),
   when: (ctx) => ctx.hasConfig(BIOME_CONFIG_PATTERNS),
   args: ["check", "--write"],
 });
 
-export default biomeCheckWriteRunner;
+export default biomeRunner;

package/extensions/formatter/runners/config-patterns.ts

@@ -0,0 +1,5 @@
+export const BIOME_CONFIG_PATTERNS = ["biome.json", "biome.jsonc"] as const;
+export const ESLINT_CONFIG_PATTERNS = [
+  "eslint.config.*",
+  ".eslintrc*",
+] as const;

package/extensions/{format/runners/eslint-fix.ts → formatter/runners/eslint.ts}

@@ -1,11 +1,11 @@
 import { ESLINT_CONFIG_PATTERNS } from "./config-patterns.js";
 import { defineRunner, direct } from "./helpers.js";
 
-const eslintFixRunner = defineRunner({
-  id: "eslint-fix",
+const eslintRunner = defineRunner({
+  id: "eslint",
   launcher: direct("eslint"),
   when: (ctx) => ctx.hasConfig(ESLINT_CONFIG_PATTERNS),
   args: ["--fix"],
 });
 
-export default eslintFixRunner;
+export default eslintRunner;

package/extensions/{format → formatter}/runners/index.ts

@@ -1,26 +1,24 @@
 import type { RunnerDefinition } from "../types.js";
-import biomeCheckWriteRunner from "./biome-check-write.js";
+import biomeRunner from "./biome.js";
 import clangFormatRunner from "./clang-format.js";
 import cmakeFormatRunner from "./cmake-format.js";
-import eslintFixRunner from "./eslint-fix.js";
-import markdownlintFixRunner from "./markdownlint-fix.js";
-import prettierConfigWriteRunner from "./prettier-config-write.js";
-import prettierMarkdownRunner from "./prettier-markdown.js";
-import ruffCheckFixRunner from "./ruff-check-fix.js";
+import eslintRunner from "./eslint.js";
+import markdownlintRunner from "./markdownlint.js";
+import prettierRunner from "./prettier.js";
+import ruffCheckRunner from "./ruff-check.js";
 import ruffFormatRunner from "./ruff-format.js";
 import shfmtRunner from "./shfmt.js";
 
 export const RUNNER_DEFINITIONS: RunnerDefinition[] = [
   clangFormatRunner,
   cmakeFormatRunner,
-  markdownlintFixRunner,
-  prettierMarkdownRunner,
-  biomeCheckWriteRunner,
-  eslintFixRunner,
-  prettierConfigWriteRunner,
+  markdownlintRunner,
+  biomeRunner,
+  eslintRunner,
+  prettierRunner,
   shfmtRunner,
   ruffFormatRunner,
-  ruffCheckFixRunner,
+  ruffCheckRunner,
 ];
 
 function buildRunnerRegistry(

package/extensions/{format/runners/markdownlint-fix.ts → formatter/runners/markdownlint.ts}

@@ -1,9 +1,9 @@
 import { defineRunner, direct } from "./helpers.js";
 
-const markdownlintFixRunner = defineRunner({
-  id: "markdownlint-fix",
+const markdownlintRunner = defineRunner({
+  id: "markdownlint",
   launcher: direct("markdownlint"),
   args: ["--fix"],
 });
 
-export default markdownlintFixRunner;
+export default markdownlintRunner;

package/extensions/{format/runners/prettier-markdown.ts → formatter/runners/prettier.ts}

@@ -1,9 +1,9 @@
 import { defineRunner, direct } from "./helpers.js";
 
-const prettierMarkdownRunner = defineRunner({
-  id: "prettier-markdown",
+const prettierRunner = defineRunner({
+  id: "prettier",
   launcher: direct("prettier"),
   args: ["--write"],
 });
 
-export default prettierMarkdownRunner;
+export default prettierRunner;

package/extensions/{format/runners/ruff-check-fix.ts → formatter/runners/ruff-check.ts}

@@ -1,9 +1,9 @@
 import { defineRunner, pypi } from "./helpers.js";
 
-const ruffCheckFixRunner = defineRunner({
-  id: "ruff-check-fix",
+const ruffCheckRunner = defineRunner({
+  id: "ruff-check",
   launcher: pypi("ruff"),
   args: ["check", "--fix"],
 });
 
-export default ruffCheckFixRunner;
+export default ruffCheckRunner;

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

@@ -1,7 +1,5 @@
 import type { ExecResult } from "@mariozechner/pi-coding-agent";
 
-export type SourceTool = "write" | "edit";
-
 export type FileKind =
   | "cxx"
   | "cmake"
@@ -40,7 +38,6 @@ export interface ResolvedLauncher {
 export interface RunnerContext {
   readonly filePath: string;
   readonly cwd: string;
-  readonly sourceTool: SourceTool;
   readonly kind: FileKind;
 
   hasCommand(command: string): Promise<boolean>;
@@ -48,7 +45,7 @@ export interface RunnerContext {
   findConfigFile(patterns: readonly string[]): Promise<string | undefined>;
   hasEditorConfigInCwd(): Promise<boolean>;
 
-  exec(command: string, args: string[]): Promise<ExecResult | undefined>;
+  exec(command: string, args: string[]): Promise<ExecResult>;
   getChangedLines(): Promise<string[]>;
   getRequiredMajorVersionFromConfig(
     patterns: readonly string[],
@@ -94,8 +91,9 @@ export interface StaticRunnerDefinition extends RunnerBase {
 }
 
 export interface DynamicRunnerDefinition extends RunnerBase {
-  buildArgs:
-    (ctx: RunnerContext) => Promise<string[] | undefined> | string[] | undefined;
+  buildArgs: (
+    ctx: RunnerContext,
+  ) => Promise<string[] | undefined> | string[] | undefined;
 }
 
 export type RunnerDefinition = StaticRunnerDefinition | DynamicRunnerDefinition;

package/extensions/index.ts

@@ -1,13 +1,47 @@
-import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
-import { commandTimeoutMs } from "./format/config.js";
-import { formatFile } from "./format/dispatch.js";
-import { pathExists, resolveToolPath } from "./format/path.js";
-import type { SourceTool } from "./format/types.js";
+import { basename } from "node:path";
+import {
+  type ExtensionAPI,
+  isEditToolResult,
+  isWriteToolResult,
+} from "@mariozechner/pi-coding-agent";
+import {
+  commandTimeoutMs,
+  hideCallSummariesInTui,
+} from "./formatter/config.js";
+import { type FormatCallSummary, formatFile } from "./formatter/dispatch.js";
+import {
+  getPathForGit,
+  pathExists,
+  resolveToolPath,
+} from "./formatter/path.js";
 
 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 formatCallSuccessSummary(summary: FormatCallSummary): string {
+  return `✔︎ ${summary.runnerId}`;
+}
+
+function formatCallFailureSummary(summary: FormatCallSummary): string {
+  if (summary.failureMessage) {
+    return `✘ ${summary.runnerId}: ${summary.failureMessage}`;
+  }
+
+  if (summary.exitCode !== undefined) {
+    return `✘ ${summary.runnerId} (exit ${summary.exitCode})`;
+  }
+
+  return `✘ ${summary.runnerId}`;
+}
+
 export default function (pi: ExtensionAPI) {
   const formatQueueByPath = new Map<string, Promise<void>>();
 
@@ -36,29 +70,73 @@ export default function (pi: ExtensionAPI) {
       return;
     }
 
-    if (event.toolName !== "write" && event.toolName !== "edit") {
+    if (!isWriteToolResult(event) && !isEditToolResult(event)) {
       return;
     }
 
-    const rawPath = (event.input as { path?: unknown }).path;
-    if (typeof rawPath !== "string" || rawPath.length === 0) {
+    const rawPath = event.input.path;
+    if (rawPath.length === 0) {
       return;
     }
 
-    const sourceTool = event.toolName as SourceTool;
     const filePath = resolveToolPath(rawPath, ctx.cwd);
 
     if (!(await pathExists(filePath))) {
       return;
     }
 
+    const showSummaries = !hideCallSummariesInTui && ctx.hasUI;
+    const notifyWarning = (message: string) => {
+      const normalizedMessage = message.replace(/\s+/g, " ").trim();
+
+      if (ctx.hasUI) {
+        ctx.ui.notify(normalizedMessage, "warning");
+        return;
+      }
+
+      console.warn(normalizedMessage);
+    };
+
     await enqueueFormat(filePath, async () => {
+      const summaries: FormatCallSummary[] = [];
+      const summaryReporter = showSummaries
+        ? (summary: FormatCallSummary) => {
+            summaries.push(summary);
+          }
+        : undefined;
+
+      const runnerWarningReporter =
+        showSummaries && ctx.hasUI
+          ? () => {
+              // Summary mode already reports failures compactly.
+            }
+          : notifyWarning;
+
       try {
-        await formatFile(pi, ctx.cwd, sourceTool, filePath, commandTimeoutMs);
-      } catch (error) {
-        console.warn(
-          `[pi-formatter] Failed to format ${filePath}: ${formatError(error)}`,
+        await formatFile(
+          pi,
+          ctx.cwd,
+          filePath,
+          commandTimeoutMs,
+          summaryReporter,
+          runnerWarningReporter,
         );
+      } catch (error) {
+        const fileLabel = formatSummaryPath(filePath, ctx.cwd);
+        notifyWarning(`Failed to format ${fileLabel}: ${formatError(error)}`);
+      }
+
+      if (!showSummaries || summaries.length === 0) {
+        return;
+      }
+
+      for (const summary of summaries) {
+        if (summary.status === "succeeded") {
+          ctx.ui.notify(formatCallSuccessSummary(summary), "info");
+          continue;
+        }
+
+        ctx.ui.notify(formatCallFailureSummary(summary), "info");
       }
     });
   });

package/package.json

@@ -1,11 +1,10 @@
 {
   "name": "pi-formatter",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Pi extension that auto-formats files after write/edit tool calls.",
   "type": "module",
   "files": [
     "extensions",
-    "DOCUMENTATION.md",
     "README.md",
     "LICENSE"
   ],

package/DOCUMENTATION.md

@@ -1,120 +0,0 @@
-# Runner API
-
-A *runner* wraps a single formatting tool (for example, `prettier` or `ruff`).
-This document describes how runners work and how to add new ones.
-
-## File layout
-
-| File | Purpose |
-| ---- | ------- |
-| `extensions/format/runners/*.ts` | One file per runner |
-| `extensions/format/runners/helpers.ts` | Helper constructors (`direct`, `pypi`, `goTool`, `defineRunner`) |
-| `extensions/format/runners/index.ts` | Runner registry |
-| `extensions/format/plan.ts` | File-kind → runner-group mapping |
-| `extensions/format/types.ts` | Shared types |
-
-## Add a new runner
-
-1. Create a file under `extensions/format/runners/`.
-2. Define the runner with the helper constructors from `helpers.ts`.
-3. Register it in `extensions/format/runners/index.ts`.
-4. Add its `id` to one or more groups in `extensions/format/plan.ts`.
-
-## Runner definition
-
-Every runner needs two things:
-
-- `id`: a unique identifier
-- `launcher`: how to locate and execute the tool
-
-### Launchers
-
-Use the helper constructors to create a launcher:
-
-| Constructor | Behavior |
-| ----------- | -------- |
-| `direct("prettier")` | Run the command directly |
-| `pypi("ruff")` | Run the tool natively, fall back to `uv tool run` |
-| `goTool("shfmt", "mvdan.cc/sh/v3/cmd/shfmt@v3.10.0")` | Run the tool natively, fall back to `go run` |
-
-All commands execute in the project working directory and respect the
-configured timeout.
-
-### Arguments
-
-There are two ways to supply arguments:
-
-- **Static** (preferred): Set `args: string[]`. The file path is appended
-  automatically unless you set `appendFile: false`.
-- **Dynamic**: Implement `buildArgs(ctx)` and return the argument array, or
-  `undefined` to skip the runner.
-
-### Optional predicates and requirements
-
-- `when(ctx)`: Return `false` to skip the runner based on an extra condition.
-- `requires.majorVersionFromConfig`: Gate execution on a major version match:
-  - `patterns`: Config-file globs to read the required major version from.
-  - `command` (optional): Command to inspect with `--version`.
-  - `onInvalid` / `onMismatch`: `"warn-skip"` (default) or `"skip"`.
-
-### Runner context
-
-The `ctx` object passed to `when` and `buildArgs` exposes:
-
-| Member | Description |
-| ------ | ----------- |
-| `filePath`, `cwd`, `sourceTool`, `kind` | Current invocation metadata |
-| `hasCommand(cmd)` | Check whether a command is available |
-| `hasConfig(patterns)`, `findConfigFile(patterns)` | Look up configuration files |
-| `hasEditorConfigInCwd()` | Check for an `.editorconfig` in the working directory |
-| `getChangedLines()` | Get the line ranges that changed |
-| `warn(msg)` | Emit a warning without failing the run |
-
-## Format plan
-
-`extensions/format/plan.ts` maps each file kind to an ordered list of runner
-groups. Each group has a mode:
-
-- **`"all"`**: Run every qualifying runner in order.
-- **`"fallback"`**: Run the first qualifying runner and stop.
-
-## Examples
-
-### Static runner
-
-```ts
-import { defineRunner, direct } from "./helpers.js";
-
-const myRunner = defineRunner({
-  id: "my-formatter",
-  launcher: direct("my-formatter"),
-  args: ["--write"],
-});
-
-export default myRunner;
-```
-
-### Dynamic runner with a version requirement
-
-```ts
-import { defineRunner, direct } from "./helpers.js";
-
-const clangFormatRunner = defineRunner({
-  id: "clang-format",
-  launcher: direct("clang-format"),
-  requires: {
-    majorVersionFromConfig: {
-      patterns: [".clang-format-version"],
-    },
-  },
-  async buildArgs(ctx) {
-    const lines = await ctx.getChangedLines();
-    if (lines.length > 0) {
-      return [...lines.map((line) => `--lines=${line}`), "-i", ctx.filePath];
-    }
-    return ["-i", ctx.filePath];
-  },
-});
-
-export default clangFormatRunner;
-```

package/extensions/format/config.ts

@@ -1,11 +0,0 @@
-const DEFAULT_COMMAND_TIMEOUT_MS = 10_000;
-
-const configuredTimeoutMs = Number.parseInt(
-  process.env.PI_FORMAT_COMMAND_TIMEOUT_MS ?? "",
-  10,
-);
-
-export const commandTimeoutMs =
-  Number.isFinite(configuredTimeoutMs) && configuredTimeoutMs > 0
-    ? configuredTimeoutMs
-    : DEFAULT_COMMAND_TIMEOUT_MS;

package/extensions/format/runners/config-patterns.ts

@@ -1,6 +0,0 @@
-export const BIOME_CONFIG_PATTERNS = ["biome.json", "biome.jsonc"] as const;
-export const ESLINT_CONFIG_PATTERNS = ["eslint.config.*", ".eslintrc*"] as const;
-export const PRETTIER_CONFIG_PATTERNS = [
-  ".prettierrc*",
-  "prettier.config.*",
-] as const;

package/extensions/format/runners/prettier-config-write.ts

@@ -1,11 +0,0 @@
-import { PRETTIER_CONFIG_PATTERNS } from "./config-patterns.js";
-import { defineRunner, direct } from "./helpers.js";
-
-const prettierConfigWriteRunner = defineRunner({
-  id: "prettier-config-write",
-  launcher: direct("prettier"),
-  when: (ctx) => ctx.hasConfig(PRETTIER_CONFIG_PATTERNS),
-  args: ["--write"],
-});
-
-export default prettierConfigWriteRunner;