@gotgenes/pi-autoformat 0.1.0

package/.github/workflows/ci.yml

@@ -0,0 +1,35 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+env:
+  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: pnpm/action-setup@v4
+        with:
+          version: latest
+
+      - uses: actions/setup-node@v6
+        with:
+          node-version: 24
+          cache: "pnpm"
+
+      - run: pnpm install --frozen-lockfile
+
+      - name: Type check
+        run: pnpm exec tsc --noEmit
+
+      - name: Lint
+        run: pnpm run lint
+
+      - name: Test
+        run: pnpm run test

package/.github/workflows/release-please.yml

@@ -0,0 +1,22 @@
+name: release-please
+
+on:
+  push:
+    branches:
+      - main
+
+env:
+  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  release-please:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: googleapis/release-please-action@v4.4.1
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+          config-file: release-please-config.json

package/.markdownlint-cli2.yaml

@@ -0,0 +1,3 @@
+config:
+  default: true
+  MD013: false

package/.pi/extensions/pi-autoformat/config.json

@@ -0,0 +1,28 @@
+{
+  "$schema": "https://raw.githubusercontent.com/gotgenes/pi-autoformat/main/schemas/pi-autoformat.schema.json",
+  "formatMode": "prompt",
+  "hideSummariesInTui": false,
+  "formatters": {
+    "biome": {
+      "command": [
+        "pnpm",
+        "exec",
+        "biome",
+        "check",
+        "--write",
+        "--files-ignore-unknown=true",
+        "$FILE"
+      ],
+      "extensions": [".ts", ".json"]
+    },
+    "markdownlint-cli2": {
+      "command": ["pnpm", "exec", "markdownlint-cli2", "--fix", "$FILE"],
+      "extensions": [".md"]
+    }
+  },
+  "chains": {
+    ".ts": ["biome"],
+    ".json": ["biome"],
+    ".md": ["markdownlint-cli2"]
+  }
+}

package/.release-please-manifest.json

@@ -0,0 +1,3 @@
+{
+  ".": "0.1.0"
+}

package/AGENTS.md

@@ -0,0 +1,71 @@
+# AGENTS.md
+
+## Project Purpose
+
+This repository is for a Pi extension that auto-formats files after agent edits so formatting does not fail late at commit time.
+
+Read `docs/plans/` before making architectural changes.
+
+## Workflow
+
+- Keep scope tight.
+- Prefer small, reversible changes.
+- Preserve intentional behavior unless there is a clear reason to change it.
+- Ask before removing functionality or changing defaults.
+
+## Implementation Priorities
+
+- Prefer prompt-end formatting over immediate per-tool formatting unless the task explicitly requires otherwise.
+- Favor repository-configured formatter commands over hardcoded formatter behavior.
+- Prefer extension-owned config files over Pi `settings.json` keys for package-specific behavior.
+- Format only files touched by the agent, not the whole repository.
+- Make formatter failures visible, but do not block the original file edit by default.
+
+## Code Style
+
+- Use TypeScript.
+- Avoid `any` unless absolutely necessary.
+- Use standard top-level imports only.
+- Keep modules focused and composable.
+- Prefer explicit configuration over hidden behavior.
+
+## Configuration
+
+- Use extension-owned config files:
+  - global: `~/.pi/agent/extensions/pi-autoformat/config.json`
+  - project: `.pi/extensions/pi-autoformat/config.json`
+- Project config overrides global config.
+- Do not move package configuration into Pi `settings.json` without explicit discussion.
+- Keep `schemas/pi-autoformat.schema.json`, `docs/configuration.md`, `README.md`, and the TypeScript config loader aligned.
+
+## Testing
+
+- Add focused tests for formatter resolution, execution order, and failure handling.
+- Test prompt-end batching behavior.
+- Test custom formatter command configuration.
+- Test multiple formatter chains for the same file type.
+- Add focused tests for config loading, merge precedence, and validation issues.
+- Add extension lifecycle tests once the runtime entrypoint exists.
+
+## Commits
+
+- Use Conventional Commits.
+- Commit at meaningful checkpoints without waiting for an explicit reminder.
+- Prefer small, reviewable commits that leave the repository in a valid state.
+- Examples:
+  - `feat: add prompt-end formatter queue`
+  - `fix: preserve formatter order for markdown chains`
+  - `test: cover custom formatter override`
+  - `docs: refine initial implementation plan`
+
+## Notes for Agents
+
+Before implementing, understand:
+
+1. the problem being solved
+2. the timing tradeoffs between tool-mode and prompt-mode formatting
+3. the need to support repository-specific formatter chains
+4. the chosen config layout and merge precedence
+5. the need to keep schema, config loader, and docs aligned
+
+Do not assume commit-time hooks are an acceptable primary formatting mechanism.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Christopher D. Lasher
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,178 @@
+# pi-autoformat
+
+`pi-autoformat` is a Pi extension package that automatically formats files after the agent edits them.
+
+## The problem this package solves
+
+Pi agents often make correct code changes that still fail at commit time because formatting was never run.
+
+That creates a frustrating workflow:
+
+1. the agent edits files
+2. the agent appears done
+3. pre-commit hooks or CI run formatters later
+4. files mutate after the fact
+5. commits fail or the agent has to recover from surprise formatting changes
+
+This package moves formatting earlier in the workflow so the agent is less likely to leave behind unformatted files.
+
+## How it works
+
+`pi-autoformat` watches files touched by Pi mutation tools and runs configured formatter commands for just those files.
+
+Design goals:
+
+- format only files the agent touched
+- prefer prompt-end batching over per-edit formatting by default
+- support repository-specific formatter commands
+- support ordered formatter chains for the same extension
+- surface formatter failures without blocking the original edit by default
+- keep reporting concise by default, with interactive summaries and non-interactive logs
+
+Default behavior is **prompt mode**:
+
+- collect files touched during the agent's work
+- run formatters once after the prompt finishes
+
+This is safer than formatting immediately after every edit because prompt-end batching avoids mutating a file in between sibling exact-text edits.
+
+## Installation
+
+### From npm
+
+```bash
+pi install npm:@gotgenes/pi-autoformat
+```
+
+### Local development checkout
+
+```bash
+pi install /absolute/path/to/pi-autoformat
+```
+
+## Configuration
+
+`pi-autoformat` uses extension-owned config files.
+
+Configuration is loaded in this order:
+
+1. global: `~/.pi/agent/extensions/pi-autoformat/config.json`
+2. project: `.pi/extensions/pi-autoformat/config.json`
+
+Project config overrides global config.
+
+Example:
+
+```json
+{
+  "$schema": "https://raw.githubusercontent.com/gotgenes/pi-autoformat/main/schemas/pi-autoformat.schema.json",
+  "formatMode": "prompt",
+  "commandTimeoutMs": 10000,
+  "hideSummariesInTui": false,
+  "formatters": {
+    "prettier": {
+      "command": ["prettier", "--write", "$FILE"],
+      "extensions": [".js", ".ts", ".tsx", ".json", ".md"]
+    },
+    "markdownlint-cli2": {
+      "command": ["markdownlint-cli2", "--fix", "$FILE"],
+      "extensions": [".md"]
+    }
+  },
+  "chains": {
+    ".md": ["prettier", "markdownlint-cli2"],
+    ".ts": ["prettier"],
+    ".tsx": ["prettier"]
+  }
+}
+```
+
+See [docs/configuration.md](docs/configuration.md) for the full configuration reference.
+
+Formatter command resolution in v1 stays intentionally simple:
+
+- built-in formatter commands run from the project `cwd`
+- the extension uses the inherited environment and `PATH`
+- if your environment manager already resolves the right tool for that directory, plain commands like `prettier` can work as-is
+- if your repo needs wrappers such as `pnpm exec`, `npx`, `mise x`, or similar, configure those commands explicitly in `formatters`
+
+## Reporting behavior
+
+By default, `pi-autoformat` reports:
+
+- concise success summaries after formatting runs
+- per-file failure summaries when one or more formatter commands fail
+- config validation issues detected while loading global or project config
+
+In the interactive TUI, these appear as notifications.
+
+Outside the TUI, they are written as prefixed log lines.
+
+Set `hideSummariesInTui` to `true` if you want to suppress interactive success summaries while still surfacing failures.
+
+## Formatter model
+
+Each formatter entry can define:
+
+- `command: string[]`
+- `extensions: string[]`
+- `environment?: Record<string, string>`
+- `disabled?: boolean`
+
+`$FILE` is replaced with the absolute path of the touched file.
+
+Chains are configured separately so formatter order is explicit.
+
+For v1, `pi-autoformat` runs formatters only when a `chains` entry exists for the file extension.
+
+Example Markdown chain:
+
+1. `prettier --write`
+2. `markdownlint-cli2 --fix`
+
+## Validation and autocomplete
+
+The config file supports JSON Schema-based validation and editor autocomplete.
+
+You can use either:
+
+- the default-branch URL for the latest schema
+- a pinned release-tag URL for reproducible validation
+
+Examples:
+
+```json
+{
+  "$schema": "https://raw.githubusercontent.com/gotgenes/pi-autoformat/main/schemas/pi-autoformat.schema.json"
+}
+```
+
+```json
+{
+  "$schema": "https://raw.githubusercontent.com/gotgenes/pi-autoformat/v1.0.0/schemas/pi-autoformat.schema.json"
+}
+```
+
+## Status
+
+This project is under active development.
+
+The current repository includes the formatter registry, execution pipeline, touched-file queue, config loading and validation, and the Pi extension runtime wiring for prompt-, tool-, and session-mode flushing.
+
+Known v1 limitations:
+
+- only Pi `write` and `edit` mutations are tracked automatically
+- arbitrary shell-driven file mutations are not detected yet
+- reporting is intentionally concise and does not yet expose full formatter stdout/stderr by default
+
+## Development
+
+```bash
+pnpm install
+pnpm test
+pnpm run lint
+```
+
+## License
+
+MIT

package/biome.json

@@ -0,0 +1,17 @@
+{
+  "$schema": "https://biomejs.dev/schemas/2.4.13/schema.json",
+  "formatter": {
+    "enabled": true,
+    "indentStyle": "space",
+    "indentWidth": 2
+  },
+  "linter": {
+    "enabled": true
+  },
+  "javascript": {
+    "formatter": {
+      "quoteStyle": "double",
+      "semicolons": "always"
+    }
+  }
+}

package/docs/configuration.md

@@ -0,0 +1,177 @@
+# Configuration
+
+`pi-autoformat` uses extension-owned config files.
+
+## Config locations
+
+Configuration is loaded from these files, in order:
+
+1. global: `~/.pi/agent/extensions/pi-autoformat/config.json`
+2. project: `.pi/extensions/pi-autoformat/config.json`
+
+Project config overrides global config.
+
+## Schema validation
+
+The config file is designed to support JSON Schema validation and autocomplete.
+
+You can point `$schema` at either:
+
+- the default-branch URL for the latest published schema
+- a pinned release-tag URL for reproducible validation
+
+Examples:
+
+Latest:
+
+```json
+{
+  "$schema": "https://raw.githubusercontent.com/gotgenes/pi-autoformat/main/schemas/pi-autoformat.schema.json",
+  "formatMode": "prompt",
+  "commandTimeoutMs": 10000,
+  "hideSummariesInTui": false,
+  "formatters": {
+    "prettier": {
+      "command": ["prettier", "--write", "$FILE"],
+      "extensions": [".js", ".ts", ".tsx", ".json", ".md"]
+    },
+    "markdownlint-cli2": {
+      "command": ["markdownlint-cli2", "--fix", "$FILE"],
+      "extensions": [".md"]
+    }
+  },
+  "chains": {
+    ".md": ["prettier", "markdownlint-cli2"],
+    ".ts": ["prettier"],
+    ".tsx": ["prettier"]
+  }
+}
+```
+
+Pinned tag:
+
+```json
+{
+  "$schema": "https://raw.githubusercontent.com/gotgenes/pi-autoformat/v1.0.0/schemas/pi-autoformat.schema.json"
+}
+```
+
+## Settings reference
+
+### `formatMode`
+
+When formatting should run.
+
+Allowed values:
+
+- `"prompt"` — format once after the agent finishes the prompt. Recommended default.
+- `"tool"` — format immediately after each successful mutation tool call.
+- `"session"` — accumulate touched files and format on session shutdown.
+
+### `commandTimeoutMs`
+
+Timeout in milliseconds for each formatter command.
+
+Example:
+
+```json
+{
+  "commandTimeoutMs": 10000
+}
+```
+
+### `hideSummariesInTui`
+
+Whether formatter summaries should be hidden in the interactive TUI.
+
+Example:
+
+```json
+{
+  "hideSummariesInTui": false
+}
+```
+
+### `formatters`
+
+Formatter registry keyed by formatter name.
+
+Each formatter can define:
+
+- `command: string[]`
+- `extensions: string[]`
+- `environment?: Record<string, string>`
+- `disabled?: boolean`
+
+`$FILE` is replaced with the absolute path to the touched file.
+
+For v1, formatter command resolution stays intentionally simple:
+
+- commands run from the project `cwd`
+- commands inherit the extension process environment and `PATH`
+- the extension does not try to auto-detect and invoke project-local binaries on its own
+- if your repo needs wrappers such as `pnpm exec`, `npx`, or `mise x`, configure them explicitly in `command`
+
+Example:
+
+```json
+{
+  "formatters": {
+    "prettier": {
+      "command": ["pnpm", "exec", "prettier", "--write", "$FILE"],
+      "extensions": [".js", ".ts", ".tsx", ".json", ".md"]
+    },
+    "markdownlint-cli2": {
+      "command": ["pnpm", "exec", "markdownlint-cli2", "--fix", "$FILE"],
+      "extensions": [".md"],
+      "environment": {
+        "CI": "1"
+      }
+    }
+  }
+}
+```
+
+### `chains`
+
+Ordered formatter chains keyed by file extension.
+
+For v1, formatter execution is driven by explicit `chains` only.
+If an extension has no `chains` entry, `pi-autoformat` does not run any formatter for that extension.
+
+The chain order is explicit and should be preserved.
+
+Example:
+
+```json
+{
+  "chains": {
+    ".md": ["prettier", "markdownlint-cli2"],
+    ".ts": ["prettier"],
+    ".tsx": ["prettier"]
+  }
+}
+```
+
+## Merge behavior
+
+Merge order:
+
+1. built-in defaults
+2. global config
+3. project config
+
+Recommended merge semantics:
+
+- top-level scalar values override by precedence
+- `formatters` merge by formatter name
+- `chains` merge by extension key
+- when a project config defines a formatter or chain key, that key replaces the lower-precedence value for that entry
+
+This keeps repo-local formatter behavior explicit while still allowing users to set global defaults such as `formatMode`.
+
+## Notes
+
+- Config is intentionally separate from Pi's shared `settings.json`.
+- A dedicated config file avoids collisions with Pi core settings and makes strict schema validation practical.
+- Schema URLs can point at either the default branch or pinned release tags depending on whether you want latest or reproducible validation behavior.