@gotgenes/pi-autoformat 0.1.0 → 4.0.3

package/docs/retro/0022-pi-coding-agent-types.md

@@ -0,0 +1,62 @@
+---
+issue: 22
+issue_title: "Depend on @mariozechner/pi-coding-agent for runtime types instead of duck-typing"
+---
+
+# Retro: #22 — Depend on `@mariozechner/pi-coding-agent` for runtime types instead of duck-typing
+
+## Final Retrospective (2026-05-02T02:45:00Z)
+
+### Session summary
+
+Planned and shipped issue #22 — replaced the duck-typed `*Like` aliases in `src/extension.ts` with real types imported from `@mariozechner/pi-coding-agent@^0.72.0` (added as a `devDependency`).
+Four implementation commits (`2d93a5e`, `304bd68`, `f9ef728`, `261bd05`), one biome fixup amended into the test commit, CI green, issue closed, release-please PR `#21` (pre-existing 2.3.1) merged.
+The planned `ExtensionAPIWithEvents` workaround turned out to be unnecessary — Pi 0.72.0's `ExtensionAPI` already declares `events: EventBus` — and was dropped in the implementation commit.
+
+### Observations
+
+#### What went well
+
+- The planning gate caught one real ambiguity (full `ExtensionContext` vs `Pick<...>` at internal helpers) and used `ask-user` once with three concrete options.
+  The chosen narrow-`Pick` shape kept the test-stub diff tractable.
+- `pnpm exec tsc --noEmit` filled in for vitest as the red/green signal on a typing-only refactor — vitest's esbuild transform strips types, so runtime tests passed even when `src/extension.ts` and `test/extension.test.ts` had real type errors mid-step.
+  Splitting the work into `refactor: import Pi types from pi-coding-agent` (`f9ef728`, intentional broken `tsc`) and `test: adopt class-based Theme stubs and Pi event types` (`261bd05`, green) preserved a coherent commit-by-commit story even though one intermediate commit didn't typecheck.
+  Worth promoting as a project pattern: add a `typecheck` script so future type-only refactors don't have to remember the incantation.
+- The user's mid-flight question — "We're confident that's the latest release of the npm package, right?" — was a clean trust gate.
+  I had checked `npm view @mariozechner/pi-coding-agent version` during planning, but hadn't restated it.
+  A 30-second re-verify (`dist-tags.latest = 0.72.0`, last modified the same day) closed the loop with no rework.
+
+#### What caused friction (agent side)
+
+- `missing-context` (self-identified, mid-execution) — The plan claimed "Pi's `events` channel is **not** part of `ExtensionAPI` today" and prescribed an `ExtensionAPIWithEvents` intersection alias as the workaround.
+  In implementation I grepped `node_modules/.../types.d.ts` more carefully and found `events: EventBus` declared right under the `on(...)` overloads.
+  Impact: dropped the workaround in the same `f9ef728` commit, simplified `subscribeToEventBus`, recorded it as a deviation in the close comment.
+  No rework cycles, but the plan was wrong about a load-bearing design detail.
+  Root cause: during plan-phase research I read `dist/index.d.ts`'s re-export line and `dist/core/extensions/index.d.ts`'s `export type` list, then jumped to interface bodies via `grep -A 30 "interface ExtensionAPI"` — but the `events` declaration sits below the long `on(...)` overload block, outside the 30-line window.
+  The lesson: when a plan asserts something *isn't* in an upstream type, grep the full interface body, not the first N lines.
+- `premature-convergence` (self-identified, low-impact) — Plan step 2 prescribed a `// @ts-expect-error` block that "currently red-flags against the duck type" and "goes green in step 4".
+  In practice the typecheck-only file (`test/types/theme-stub.test-d.ts`) imports `Theme` directly from `@mariozechner/pi-coding-agent`, so its assertion is independent of `src/extension.ts` typing — green from the moment it's written.
+  Impact: a slightly misleading TDD-ordering note in the plan; no commit churn.
+- `wrong-abstraction` (small, self-identified) — Plan claimed `TestPi.on` could be typed as `ExtensionAPI["on"]`.
+  In practice, `ExtensionAPI["on"]` is a 26-overload signature that `TestPi`'s narrow harness can't structurally satisfy without modelling every event union.
+  Resolution: cast through `unknown` once on `TestPi.on`, expose an `asExtensionAPI()` helper, and `sed` 28 call sites to use it.
+  Impact: one mechanical bulk substitution; the test-side type fidelity is weaker than the plan implied (we're casting at the boundary, not type-anchored).
+  Acceptable per the plan's stated goal — what matters is `ctx.ui.theme: Theme` catches plain-arrow stubs, which still works.
+
+#### What caused friction (user side)
+
+- None observed.
+  The trust-gate question on the npm version was useful, not friction.
+  No premature corrections, no scope changes mid-flight.
+
+### Novel wins
+
+- First time on this repo a typing-only refactor was structured around `tsc --noEmit` as the test signal.
+  Pattern worked cleanly; the only friction was that no `typecheck` script exists in `package.json`, so each red/green cycle required `pnpm exec tsc --noEmit` typed by hand.
+
+### Changes made
+
+1. Added `"typecheck": "tsc --noEmit"` to `package.json` `scripts`.
+2. Added a one-line `AGENTS.md` § Testing note pointing future type-only changes at `pnpm run typecheck`.
+3. Updated `.github/workflows/ci.yml` to call `pnpm run typecheck` instead of inlining `pnpm exec tsc --noEmit`.
+4. Created `docs/retro/0022-pi-coding-agent-types.md`.

package/docs/testing.md

@@ -0,0 +1,95 @@
+# Testing
+
+`pi-autoformat` ships three layers of tests:
+
+1. Unit tests under `test/*.test.ts` — fast, hermetic, cover individual modules (config loader, formatter executor, prompt autoformatter, shell mutation detector, etc.).
+2. Acceptance tests that spawn the real `pi` CLI in `--mode rpc` — covered below.
+3. (Future) LLM-gated acceptance tests — designed but not yet implemented.
+
+Run everything with:
+
+```bash
+pnpm test
+```
+
+Vitest does not type-check.
+For type-only changes use:
+
+```bash
+pnpm run typecheck
+```
+
+## Acceptance tests
+
+Files: `test/acceptance.test.ts`, `test/acceptance-event-bus.test.ts`, `test/fallback-acceptance.test.ts`.
+
+Acceptance tests spawn the real `pi` binary in `--mode rpc` and assert behavior against actual Pi runtime events.
+They catch regressions that pure unit tests cannot: extension load failures, payload-shape drift on real Pi events, and EventBus contract drift.
+
+### Resolving the `pi` binary
+
+`@mariozechner/pi-coding-agent` is a `devDependency` of this package, and `pnpm install` produces a working `node_modules/.bin/pi`.
+The shared harness in `test/helpers/rpc.ts` resolves `pi` from that path explicitly rather than relying on the global `PATH`:
+
+```typescript
+export const PI_BIN = resolve("node_modules/.bin/pi");
+export const piAvailable = existsSync(PI_BIN);
+```
+
+Benefits:
+
+- CI runs the acceptance suite under the existing `pnpm install --frozen-lockfile` step — no workflow changes needed.
+- The Pi version is pinned by `pnpm-lock.yaml`, so CI and local runs use the same binary.
+- Contributors who ran `pnpm install` get the acceptance suite for free; no separate global install.
+
+### Skip semantics
+
+`describeIfPi` is a safety net: it skips when `node_modules/.bin/pi` is missing (for example, after a partial checkout without `pnpm install`).
+In normal usage every contributor runs the full suite.
+
+### Test fixtures
+
+`test/fixtures/` holds small companion extensions and helpers used by the acceptance suite:
+
+- `event-bus-emitter.ts` — registers `/emit-touched <path...>` and forwards the paths onto the `autoformat:touched` channel via `pi.events.emit`.
+- `formatter-recorder.mjs` — a stand-in "formatter" that appends `{ argv, cwd }` to the file pointed at by the `PI_AUTOFORMAT_RECORDER_LOG` env var.
+  Tests configure this script as the formatter command and read the log to assert what Pi actually invoked.
+
+### EventBus acceptance test
+
+`test/acceptance-event-bus.test.ts` exercises the production extension's `pi.events` subscription end to end:
+
+1. Writes a project config that wires the recorder formatter to `.ts` files and sets `formatMode: "session"` so the flush runs on session shutdown.
+2. Loads `src/extension.ts` and `event-bus-emitter.ts` together via `-e` flags.
+3. Sends `{ type: "prompt", message: "/emit-touched <path>" }` over RPC.
+4. Closes stdin; `session_shutdown` triggers the flush.
+5. Reads the recorder log and asserts the formatter ran on the emitted absolute path.
+
+This test is the primary safeguard against EventBus payload-shape drift between this extension and Pi.
+
+## What is *not* covered by the default suite
+
+Several scenarios named in issue #10 are not in the default acceptance suite because Pi's RPC mode does not surface the events they depend on:
+
+- **`bash` shell mutation.** Pi's RPC `bash` command stores a `BashExecutionMessage` for the next prompt's LLM context but does not emit `tool_call` or `tool_result` events.
+  Our extension's snapshot tracker is wired to those events, so an RPC `bash` command does not drive the shell-mutation path.
+  Coverage today: `test/shell-mutation-detector.test.ts` (unit).
+- **`write` / `edit` payload-shape validation.** These tools are only invoked by the LLM; there is no documented non-LLM trigger.
+  Coverage today: `test/extension.test.ts` (integration with a stubbed `ExtensionAPI`).
+- **`customMutationTools` real `tool_result` events.** Same constraint as `write`/`edit`: the registered tool only fires when an LLM calls it.
+  Coverage today: `test/custom-mutation-tools.test.ts` (unit).
+
+These gaps are real but bounded.
+The unit / integration tests pin the handler logic; the EventBus acceptance test pins the runtime wiring; LLM-gated tests (below) will eventually pin the tool-result payload contract.
+
+## LLM-gated acceptance suite (future)
+
+The natural way to drive `bash` / `write` / `edit` / `customMutationTools` end to end is to send a real `prompt` and let an LLM call the tool.
+That is intentionally out of scope for default `pnpm test`:
+
+- requires a provider API key,
+- costs money,
+- is non-deterministic.
+
+When implemented, these tests will live under `test/acceptance-llm/` and skip unless `PI_AUTOFORMAT_LLM_TESTS=1` is set in the environment plus the relevant provider credential (e.g. `ANTHROPIC_API_KEY`).
+They will not run in default CI; an explicit, manually triggered workflow may run them on a schedule.

package/package.json

@@ -1,18 +1,43 @@
 {
   "name": "@gotgenes/pi-autoformat",
-  "version": "0.1.0",
+  "version": "4.0.3",
   "description": "Pi extension package for prompt-end auto-formatting",
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "pi-coding-agent",
+    "autoformat",
+    "formatter",
+    "prompt-end",
+    "biome",
+    "prettier",
+    "typescript"
+  ],
   "author": {
     "name": "Chris Lasher"
   },
   "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/gotgenes/pi-autoformat"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
   "type": "module",
   "pi": {
     "extensions": [
       "./src/extension.ts"
     ]
   },
-  "packageManager": "pnpm@10.33.2",
+  "devDependencies": {
+    "@biomejs/biome": "^2.4.14",
+    "@mariozechner/pi-coding-agent": "^0.73.0",
+    "@types/node": "^25.6.0",
+    "markdownlint-cli2": "^0.22.1",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.5"
+  },
   "scripts": {
     "lint": "pnpm exec biome check . && pnpm run lint:md",
     "lint:fix": "pnpm exec biome check --write --files-ignore-unknown=true . && pnpm run lint:md:fix",
@@ -20,13 +45,7 @@
     "lint:md:fix": "pnpm exec markdownlint-cli2 --fix '*.md' 'docs/**/*.md'",
     "format": "pnpm exec biome check --write --files-ignore-unknown=true .",
     "test": "vitest run",
-    "test:watch": "vitest"
-  },
-  "devDependencies": {
-    "@biomejs/biome": "^2.4.13",
-    "@types/node": "^25.6.0",
-    "markdownlint-cli2": "^0.22.1",
-    "typescript": "^6.0.3",
-    "vitest": "^4.1.5"
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit"
   }
-}
+}

package/prek.toml

@@ -13,12 +13,12 @@ hooks = [
 [[repos]]
 repo = "local"
 hooks = [
-    { id = "biome", name = "biome", entry = "pnpm exec biome check --write --files-ignore-unknown=true", language = "system", types_or = ["javascript", "jsx", "ts", "tsx", "json"] },
+    { id = "biome", name = "biome", entry = "pnpm exec biome check --files-ignore-unknown=true", language = "system", types_or = ["javascript", "jsx", "ts", "tsx", "json"] },
 ]
 
 [[repos]]
 repo = "https://github.com/DavidAnson/markdownlint-cli2"
 rev = "v0.22.1"
 hooks = [
-    { id = "markdownlint-cli2", args = ["--fix"] },
+    { id = "markdownlint-cli2" },
 ]

package/schemas/pi-autoformat.schema.json

@@ -10,11 +10,6 @@
       "type": "string",
       "description": "Optional schema URL for editor validation and autocomplete."
     },
-    "formatMode": {
-      "type": "string",
-      "enum": ["tool", "prompt", "session"],
-      "description": "When formatting should run."
-    },
     "commandTimeoutMs": {
       "type": "integer",
       "minimum": 1,
@@ -24,6 +19,71 @@
       "type": "boolean",
       "description": "Hide formatter summaries in the interactive TUI."
     },
+    "formatScope": {
+      "description": "Boundary for files eligible for formatting. 'repoRoot' (default) detects the Git toplevel and falls back to cwd; 'cwd' restricts to the strict cwd subtree; an array of paths is an explicit allowlist of roots resolved relative to cwd.",
+      "oneOf": [
+        { "type": "string", "enum": ["repoRoot", "cwd"] },
+        {
+          "type": "array",
+          "items": { "type": "string", "minLength": 1 },
+          "minItems": 1
+        }
+      ]
+    },
+    "shellMutationDetection": {
+      "type": "object",
+      "description": "Opt-in detection of file mutations performed by shell commands.",
+      "additionalProperties": false,
+      "properties": {
+        "enabled": {
+          "type": "boolean",
+          "description": "Master switch for shell mutation detection. Defaults to false."
+        },
+        "argumentParsing": {
+          "type": "boolean",
+          "description": "Parse known mutating commands (sed -i, mv, cp, touch, tee, redirections). Defaults to true once detection is enabled."
+        },
+        "snapshotGlobs": {
+          "type": "array",
+          "description": "Globs whose mtimes are snapshotted before/after each bash invocation. Files whose mtime advanced are treated as touched.",
+          "items": { "type": "string", "minLength": 1 }
+        },
+        "wrappers": {
+          "type": "array",
+          "description": "Shell command prefixes that print touched files on stdout.",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["prefix"],
+            "properties": {
+              "prefix": { "type": "string", "minLength": 1 },
+              "outputFormat": { "type": "string", "enum": ["lines"] }
+            }
+          }
+        }
+      }
+    },
+    "customMutationTools": {
+      "type": "array",
+      "description": "Declare non-built-in tools that mutate files. Each entry maps a tool name to the field(s) on the tool's input payload that contain the touched path(s). Use for extension- or MCP-provided tools (e.g. mcp_files_write). Built-in tool names (write, edit, bash, read, grep, find, ls) are rejected.",
+      "items": { "$ref": "#/$defs/customMutationToolSpec" }
+    },
+    "eventBusMutationChannel": {
+      "type": "object",
+      "description": "Subscribe to a Pi EventBus channel for touched-file notifications from peer extensions.",
+      "additionalProperties": false,
+      "properties": {
+        "enabled": {
+          "type": "boolean",
+          "description": "Whether to subscribe to the channel. Default: true."
+        },
+        "channel": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Channel name. Default: \"autoformat:touched\". Payload: { path: string } or { paths: string[] }."
+        }
+      }
+    },
     "formatters": {
       "type": "object",
       "description": "Formatter registry keyed by formatter name.",
@@ -31,44 +91,108 @@
         "$ref": "#/$defs/formatterDefinition"
       }
     },
+    "formatterOutput": {
+      "$ref": "#/$defs/formatterOutputReportingConfig"
+    },
     "chains": {
       "type": "object",
-      "description": "Ordered formatter chains keyed by file extension.",
+      "description": "Ordered formatter chains keyed by file extension or the literal wildcard '*'. The wildcard chain runs first against the full batch of touched files; files reported as unhandled by built-in dispatchers (treefmt, treefmt-nix) fall through to their per-extension chain. Each step is either a formatter name (string) or a fallback group ({ \"fallback\": [name, ...] }) that runs the first listed formatter whose command is found on PATH.",
       "propertyNames": {
         "type": "string",
-        "pattern": "^\\..+"
+        "pattern": "^(\\..+|\\*)$"
       },
       "additionalProperties": {
         "type": "array",
         "items": {
-          "type": "string",
-          "minLength": 1
+          "oneOf": [
+            {
+              "type": "string",
+              "minLength": 1,
+              "description": "Single formatter name."
+            },
+            {
+              "type": "object",
+              "additionalProperties": false,
+              "required": ["fallback"],
+              "description": "Fallback group: the first formatter whose command is on PATH runs. Non-zero exit codes are not masked by falling through.",
+              "properties": {
+                "fallback": {
+                  "type": "array",
+                  "minItems": 1,
+                  "items": {
+                    "type": "string",
+                    "minLength": 1
+                  }
+                }
+              }
+            }
+          ]
         }
       }
     }
   },
   "$defs": {
+    "formatterOutputReportingConfig": {
+      "type": "object",
+      "description": "Optional surfacing of formatter stdout/stderr in failure reports. Successful runs are never annotated. Defaults preserve concise reporting.",
+      "additionalProperties": false,
+      "properties": {
+        "onFailure": {
+          "type": "string",
+          "enum": ["none", "stderr", "both"],
+          "description": "Which streams of a failed run to include in the failure report. Default: \"none\"."
+        },
+        "maxBytes": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "Hard byte cap per stream per failed run (UTF-8). Tail is preserved. Default: 4096."
+        },
+        "maxLines": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "Hard line cap per stream per failed run, applied after byte trimming. Default: 40."
+        }
+      }
+    },
+    "customMutationToolSpec": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["toolName"],
+      "properties": {
+        "toolName": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Exact match against the tool's name. Cannot be a Pi built-in tool."
+        },
+        "pathField": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Single dotted path into the tool's input payload (e.g. 'path' or 'args.target'). The resolved value may be a string or string array."
+        },
+        "pathFields": {
+          "type": "array",
+          "minItems": 1,
+          "items": { "type": "string", "minLength": 1 },
+          "description": "Multiple dotted paths into the tool's input payload. Each resolved value may be a string or string array; arrays are flattened."
+        }
+      },
+      "oneOf": [
+        { "required": ["pathField"], "not": { "required": ["pathFields"] } },
+        { "required": ["pathFields"], "not": { "required": ["pathField"] } }
+      ]
+    },
     "formatterDefinition": {
       "type": "object",
       "additionalProperties": false,
       "properties": {
         "command": {
           "type": "array",
-          "description": "Command argv used to format a file. Use $FILE as the file placeholder.",
-          "items": {
-            "type": "string"
-          },
-          "minItems": 1
-        },
-        "extensions": {
-          "type": "array",
-          "description": "File extensions this formatter applies to.",
+          "description": "Command argv used to format files. The executor appends touched file paths to the end of this command, so do not include file paths or the legacy $FILE token here.",
           "items": {
             "type": "string",
-            "pattern": "^\\..+"
+            "not": { "pattern": "\\$FILE" }
           },
-          "minItems": 1,
-          "uniqueItems": true
+          "minItems": 1
         },
         "environment": {
           "type": "object",

package/src/builtin-formatters.ts

@@ -0,0 +1,205 @@
+import { existsSync } from "node:fs";
+import path from "node:path";
+
+import type { BatchRun } from "./formatter-executor.js";
+
+export type DiscoveryCache = Map<string, string | null>;
+
+export type BuiltinPartition = {
+  handled: string[];
+  unhandled: string[];
+  /** When true, the run is treated as a no-op skip (not a failed run). */
+  treatAsSkip: boolean;
+};
+
+export type BuiltinDiscoveryContext = {
+  cache?: DiscoveryCache;
+};
+
+export type BuiltinFormatter = {
+  name: string;
+  /**
+   * Discover the dispatcher's config root by walking up from each touched
+   * file's directory. Returns undefined when no config applies, in which
+   * case the built-in is skipped for that flush. Cached per session via the
+   * provided cache.
+   */
+  discoverRoot(
+    files: string[],
+    context?: BuiltinDiscoveryContext,
+  ): Promise<string | undefined>;
+  /** Build the argv to invoke given the discovered root and the file batch. */
+  buildCommand(
+    root: string,
+    files: string[],
+  ): { command: string[]; cwd: string };
+  /**
+   * Inspect a completed BatchRun and return the subset of input files the
+   * dispatcher reported as "no formatter matched". Those files fall through
+   * to subsequent chain steps / per-extension chains.
+   */
+  partitionUnhandled(run: BatchRun, files: string[]): BuiltinPartition;
+};
+
+/**
+ * Walk up from each file's directory looking for the first directory whose
+ * `match(dir)` returns true. Memoizes results in the optional cache, keyed
+ * by visited directory, so repeated calls within a session avoid redundant
+ * stat work.
+ */
+function walkUp(
+  files: string[],
+  match: (dir: string) => boolean,
+  cache?: DiscoveryCache,
+): string | undefined {
+  for (const file of files) {
+    let dir = path.dirname(path.resolve(file));
+    const visited: string[] = [];
+    while (true) {
+      if (cache?.has(dir)) {
+        const cached = cache.get(dir) ?? null;
+        for (const v of visited) {
+          cache.set(v, cached);
+        }
+        if (cached) return cached;
+        break;
+      }
+      visited.push(dir);
+      if (match(dir)) {
+        if (cache) {
+          for (const v of visited) cache.set(v, dir);
+        }
+        return dir;
+      }
+      const parent = path.dirname(dir);
+      if (parent === dir) {
+        if (cache) {
+          for (const v of visited) cache.set(v, null);
+        }
+        break;
+      }
+      dir = parent;
+    }
+  }
+  return undefined;
+}
+
+function hasTreefmtConfig(dir: string): boolean {
+  return (
+    existsSync(path.join(dir, "treefmt.toml")) ||
+    existsSync(path.join(dir, ".treefmt.toml"))
+  );
+}
+
+function hasTreefmtNixConfig(dir: string): boolean {
+  if (!existsSync(path.join(dir, "flake.nix"))) {
+    return false;
+  }
+  return (
+    existsSync(path.join(dir, "treefmt.nix")) ||
+    existsSync(path.join(dir, "nix", "treefmt.nix"))
+  );
+}
+
+function treefmtConfigPath(root: string): string {
+  // treefmt itself prefers treefmt.toml over .treefmt.toml. Default to the
+  // canonical name when both/neither exist so callers that haven't created
+  // the file on disk still get a sensible argv.
+  const canonical = path.join(root, "treefmt.toml");
+  const dotted = path.join(root, ".treefmt.toml");
+  if (!existsSync(canonical) && existsSync(dotted)) {
+    return dotted;
+  }
+  return canonical;
+}
+
+const treefmt: BuiltinFormatter = {
+  name: "treefmt",
+  async discoverRoot(files, context) {
+    return walkUp(files, hasTreefmtConfig, context?.cache);
+  },
+  buildCommand(root, files) {
+    return {
+      command: [
+        "treefmt",
+        "--config-file",
+        treefmtConfigPath(root),
+        "--",
+        ...files,
+      ],
+      cwd: root,
+    };
+  },
+  partitionUnhandled(run, files) {
+    const stderr = run.stderr ?? "";
+    const unhandled = new Set<string>();
+    // treefmt logs lines like "WARN no formatter for path: /repo/x.bin".
+    const re = /no formatter for path[: ]+(\S+)/g;
+    for (const match of stderr.matchAll(re)) {
+      unhandled.add(match[1]);
+    }
+    const handled = files.filter((f) => !unhandled.has(f));
+    const treatAsSkip =
+      run.exitCode === 0 && unhandled.size > 0 && handled.length === 0;
+    return {
+      handled,
+      unhandled: files.filter((f) => unhandled.has(f)),
+      treatAsSkip,
+    };
+  },
+};
+
+const NIX_TRANSIENT_PATTERNS: readonly string[] = [
+  "cannot connect to socket",
+  "error: build of",
+  "error: unable to start any build",
+];
+
+function looksLikeNixTransient(stderr: string): boolean {
+  return NIX_TRANSIENT_PATTERNS.some((p) => stderr.includes(p));
+}
+
+const treefmtNix: BuiltinFormatter = {
+  name: "treefmt-nix",
+  async discoverRoot(files, context) {
+    return walkUp(files, hasTreefmtNixConfig, context?.cache);
+  },
+  buildCommand(root, files) {
+    return {
+      command: [
+        "nix",
+        "fmt",
+        "--no-update-lock-file",
+        "--no-write-lock-file",
+        "--",
+        ...files,
+      ],
+      cwd: root,
+    };
+  },
+  partitionUnhandled(run, files) {
+    const stderr = run.stderr ?? "";
+    if (
+      stderr.includes("emitted 0 files for processing") ||
+      looksLikeNixTransient(stderr)
+    ) {
+      return { handled: [], unhandled: [...files], treatAsSkip: true };
+    }
+    return { handled: [...files], unhandled: [], treatAsSkip: false };
+  },
+};
+
+export const BUILTIN_FORMATTERS: Record<string, BuiltinFormatter> = {
+  treefmt,
+  "treefmt-nix": treefmtNix,
+};
+
+export function isBuiltinFormatterName(name: string): boolean {
+  return Object.hasOwn(BUILTIN_FORMATTERS, name);
+}
+
+export function getBuiltinFormatter(
+  name: string,
+): BuiltinFormatter | undefined {
+  return BUILTIN_FORMATTERS[name];
+}