@cortexkit/aft-pi 0.14.0

package/README.md

@@ -0,0 +1,143 @@
+# @cortexkit/aft-pi
+
+**AFT (Agent File Tools) extension for the [Pi coding agent](https://github.com/badlogic/pi-mono)**
+
+AFT is a high-performance file-manipulation toolkit for AI coding agents. It replaces Pi's built-in `read`, `write`, `edit`, and `grep` tools with an indexed Rust backend that adds trigram search, semantic search, fuzzy edits, auto-format, LSP diagnostics, call-graph navigation, and more — all backed by one warm long-running `aft` process per session.
+
+## Install
+
+```bash
+pi install npm:@cortexkit/aft-pi
+```
+
+That's it. The extension auto-downloads the right AFT binary for your platform on first run (cached at `~/.cache/aft/bin/v<version>/aft`).
+
+Prefer to pin a specific version?
+
+```bash
+pi install npm:@cortexkit/aft-pi@0.13.1
+```
+
+## What you get
+
+### Hoisted built-in overrides
+
+Pi's default `read`, `write`, `edit`, and `grep` are replaced with AFT-backed versions.
+
+| Tool    | Pi built-in              | AFT replacement                                                                              |
+| ------- | ------------------------ | -------------------------------------------------------------------------------------------- |
+| `read`  | Node `fs.readFile`       | Rust reader with line-numbered output, directory listing, binary/image detection              |
+| `write` | Node `fs.writeFile`      | Atomic write with per-file backup, auto-format (biome/prettier/ruff/rustfmt), LSP diagnostics |
+| `edit`  | Plain substring replace  | Progressive fuzzy match (handles whitespace/Unicode drift), dry-run, glob-wide edits          |
+| `grep`  | ripgrep shell-out        | Trigram-indexed search in-project, ripgrep fallback outside project root                      |
+
+All four keep the same agent-facing parameters as Pi's built-ins, so your prompts, skills, and muscle memory don't change.
+
+### AFT-specific tools
+
+| Tool                | What it does                                                                      |
+| ------------------- | --------------------------------------------------------------------------------- |
+| `aft_outline`       | Structural outline (functions, classes, headings) for files or directories        |
+| `aft_zoom`          | Symbol-level inspection with call-graph annotations                               |
+| `aft_search`        | Semantic code search (embeddings, local ONNX or OpenAI-compatible)                |
+| `aft_navigate`      | Call-graph navigation: callers, call_tree, impact, trace_to, trace_data           |
+| `aft_conflicts`     | One-call merge-conflict inspection across all conflicted files                    |
+| `aft_import`        | Language-aware import add / remove / organize (TS, JS, Python, Rust, Go)          |
+| `aft_safety`        | Per-file undo, named checkpoints, restore                                         |
+| `ast_grep_search`   | AST-aware pattern search across the filesystem                                    |
+| `ast_grep_replace`  | AST-aware pattern rewrite                                                         |
+| `lsp_diagnostics`   | On-demand LSP diagnostics (edit/write already inline diagnostics automatically)   |
+| `aft_delete`        | Delete a file with backup (surface: `all`)                                        |
+| `aft_move`          | Move/rename a file (surface: `all`)                                               |
+| `aft_transform`     | Scope-aware structural transformations (surface: `all`)                           |
+| `aft_refactor`      | Workspace-wide refactor: move symbol, extract function, inline call (surface: `all`) |
+
+### Slash command
+
+- `/aft-status` — show AFT version, search/semantic index state, LSP servers, storage paths
+
+## Configure
+
+AFT reads config from two levels, project overrides user:
+
+- **User:** `~/.pi/agent/aft.jsonc` (or `.json`)
+- **Project:** `<project>/.pi/aft.jsonc` (or `.json`)
+
+All keys are optional. Example:
+
+```jsonc
+{
+  // "minimal" | "recommended" (default) | "all"
+  "tool_surface": "recommended",
+
+  // Auto-format on write/edit using project formatter config.
+  "format_on_edit": true,
+
+  // "syntax" (tree-sitter parse) | "full" (LSP typecheck)
+  "validate_on_edit": "syntax",
+
+  // When true, write-capable commands reject paths outside project_root.
+  // Defaults to false to match Pi's built-in behavior.
+  "restrict_to_project_root": false,
+
+  // Enable the trigram-indexed grep/glob (hoists them when true).
+  "experimental_search_index": true,
+
+  // Enable semantic search (aft_search). Requires ONNX runtime for local
+  // embeddings; downloaded automatically on supported platforms.
+  "experimental_semantic_search": true,
+
+  // Disable specific tool names (applied after tool_surface selection).
+  "disabled_tools": ["aft_transform", "aft_refactor"],
+
+  "formatter": {
+    "typescript": "biome",
+    "python": "ruff",
+    "rust": "rustfmt"
+  },
+  "checker": {
+    "typescript": "biome"
+  },
+
+  // Semantic backend (when experimental_semantic_search=true).
+  // "fastembed" (default, local ONNX) | "openai_compatible" | "ollama"
+  "semantic": {
+    "backend": "fastembed",
+    "model": "all-MiniLM-L6-v2",
+    "timeout_ms": 25000,
+    "max_batch_size": 64
+  }
+}
+```
+
+Sensitive semantic backend fields (`backend`, `base_url`, `api_key_env`) are only read from **user-level** config. Project configs that try to set them are ignored with a warning to prevent credential-exfiltration via malicious repos.
+
+### Tool surface tiers
+
+| Tier              | Tools                                                                                                                   |
+| ----------------- | ----------------------------------------------------------------------------------------------------------------------- |
+| `minimal`         | `aft_outline`, `aft_zoom`, `aft_safety`                                                                                 |
+| `recommended` (default) | `minimal` + hoisted `read`/`write`/`edit` + `aft_import` + `ast_grep_*` + `lsp_diagnostics` + `aft_conflicts` + (optional) `grep` + (optional) `aft_search` |
+| `all`             | `recommended` + `aft_navigate` + `aft_delete` + `aft_move` + `aft_transform` + `aft_refactor`                           |
+
+## Architecture
+
+- **One persistent Rust process per session.** Pi loads the extension once per session; AFT spawns one `aft` binary for the session's working directory and keeps it alive. Trigram index, semantic index, tree-sitter caches, and LSP servers all stay warm.
+- **NDJSON bridge.** The TypeScript extension talks to the Rust binary over stdin/stdout using a versioned JSON-RPC-style protocol.
+- **Session isolation.** Pi's `session_shutdown` event triggers clean bridge shutdown — undo history, checkpoints, and LSP state don't leak across sessions.
+- **Auto-download + version check.** Each plugin version pins a compatible binary version and resolves it in order: versioned cache → platform npm package → `PATH` → `~/.cargo/bin/aft` → GitHub release download. Mismatched binaries hot-swap transparently.
+
+## Logs
+
+Plugin logs go to `$TMPDIR/aft-pi.log`. Rust backend logs are forwarded into the same file with an `[aft]` tag.
+
+Set `AFT_LOG_STDERR=1` to route logs to stderr instead (useful for piping or subprocess tests).
+
+## License
+
+MIT
+
+---
+
+**Main project:** https://github.com/cortexkit/aft
+**Issues / feature requests:** https://github.com/cortexkit/aft/issues

package/dist/bridge.d.ts

@@ -0,0 +1,63 @@
+export interface BridgeOptions {
+    /** Request timeout in milliseconds. Default: 30000 */
+    timeoutMs?: number;
+    /** Maximum restart attempts before giving up. Default: 3 */
+    maxRestarts?: number;
+    /** Minimum binary version required (semver). If the binary is older, onVersionMismatch is called. */
+    minVersion?: string;
+    /** Called when binary version is older than minVersion. Receives (binaryVersion, minVersion). */
+    onVersionMismatch?: (binaryVersion: string, minVersion: string) => void;
+}
+/**
+ * Manages a persistent `aft` child process, communicating via NDJSON over
+ * stdin/stdout. Lazy-spawns on first `send()` call. Handles crash detection
+ * with exponential backoff auto-restart.
+ */
+export declare class BinaryBridge {
+    private static readonly RESTART_RESET_MS;
+    /** How many recent stderr lines to keep for crash diagnostics. */
+    private static readonly STDERR_TAIL_MAX;
+    private binaryPath;
+    private cwd;
+    private process;
+    private pending;
+    private nextId;
+    private stdoutBuffer;
+    /** Ring buffer of the last N stderr lines, cleared on every spawn. */
+    private stderrTail;
+    private _restartCount;
+    private _shuttingDown;
+    private timeoutMs;
+    private maxRestarts;
+    private configured;
+    private _configurePromise;
+    private configOverrides;
+    private minVersion;
+    private onVersionMismatch;
+    private restartResetTimer;
+    constructor(binaryPath: string, cwd: string, options?: BridgeOptions, configOverrides?: Record<string, unknown>);
+    /** Number of times the binary has been restarted after a crash. */
+    get restartCount(): number;
+    /** Whether the child process is currently alive. */
+    isAlive(): boolean;
+    /**
+     * Send a command to the binary and return the parsed response.
+     * Lazy-spawns the binary on first call.
+     */
+    send(command: string, params?: Record<string, unknown>): Promise<Record<string, unknown>>;
+    /** Kill the child process and reject all pending requests. */
+    shutdown(): Promise<void>;
+    /** Query binary version and compare against minVersion. Calls onVersionMismatch if outdated. */
+    private checkVersion;
+    private ensureSpawned;
+    private spawnProcess;
+    private pushStderrLine;
+    private formatStderrTail;
+    private onStdoutData;
+    private handleTimeout;
+    private handleCrash;
+    private rejectAllPending;
+    private scheduleRestartCountReset;
+    private clearRestartResetTimer;
+}
+//# sourceMappingURL=bridge.d.ts.map

package/dist/bridge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bridge.d.ts","sourceRoot":"","sources":["../src/bridge.ts"],"names":[],"mappings":"AA0EA,MAAM,WAAW,aAAa;IAC5B,sDAAsD;IACtD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,4DAA4D;IAC5D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,qGAAqG;IACrG,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,iGAAiG;IACjG,iBAAiB,CAAC,EAAE,CAAC,aAAa,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,KAAK,IAAI,CAAC;CACzE;AAED;;;;GAIG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,gBAAgB,CAAiB;IACzD,kEAAkE;IAClE,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,eAAe,CAAM;IAE7C,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,GAAG,CAAS;IACpB,OAAO,CAAC,OAAO,CAA6B;IAC5C,OAAO,CAAC,OAAO,CAAqC;IACpD,OAAO,CAAC,MAAM,CAAK;IACnB,OAAO,CAAC,YAAY,CAAM;IAC1B,sEAAsE;IACtE,OAAO,CAAC,UAAU,CAAgB;IAClC,OAAO,CAAC,aAAa,CAAK;IAC1B,OAAO,CAAC,aAAa,CAAS;IAC9B,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,WAAW,CAAS;IAC5B,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,iBAAiB,CAA8B;IACvD,OAAO,CAAC,eAAe,CAA0B;IACjD,OAAO,CAAC,UAAU,CAAqB;IACvC,OAAO,CAAC,iBAAiB,CAAoE;IAC7F,OAAO,CAAC,iBAAiB,CAA8C;gBAGrE,UAAU,EAAE,MAAM,EAClB,GAAG,EAAE,MAAM,EACX,OAAO,CAAC,EAAE,aAAa,EACvB,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAW3C,mEAAmE;IACnE,IAAI,YAAY,IAAI,MAAM,CAEzB;IAED,oDAAoD;IACpD,OAAO,IAAI,OAAO;IAIlB;;;OAGG;IACG,IAAI,CACR,OAAO,EAAE,MAAM,EACf,MAAM,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,GACnC,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAsFnC,8DAA8D;IACxD,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;IA4B/B,gGAAgG;YAClF,YAAY;IAoB1B,OAAO,CAAC,aAAa;IAKrB,OAAO,CAAC,YAAY;IA0GpB,OAAO,CAAC,cAAc;IAOtB,OAAO,CAAC,gBAAgB;IAMxB,OAAO,CAAC,YAAY;IA4BpB,OAAO,CAAC,aAAa;IAkBrB,OAAO,CAAC,WAAW;IAoCnB,OAAO,CAAC,gBAAgB;IAQxB,OAAO,CAAC,yBAAyB;IAQjC,OAAO,CAAC,sBAAsB;CAM/B"}

package/dist/commands/aft-status.d.ts

@@ -0,0 +1,11 @@
+/**
+ * /aft-status — show AFT status (version, indexes, LSP, storage).
+ *
+ * In interactive mode this opens as an input dialog (read-only preview of
+ * a formatted snapshot). When UI is unavailable (print / RPC mode), we fall
+ * back to a notification.
+ */
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import type { PluginContext } from "../types.js";
+export declare function registerStatusCommand(pi: ExtensionAPI, ctx: PluginContext): void;
+//# sourceMappingURL=aft-status.d.ts.map

package/dist/commands/aft-status.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"aft-status.d.ts","sourceRoot":"","sources":["../../src/commands/aft-status.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,YAAY,EAA2B,MAAM,+BAA+B,CAAC;AAG3F,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAEjD,wBAAgB,qBAAqB,CAAC,EAAE,EAAE,YAAY,EAAE,GAAG,EAAE,aAAa,GAAG,IAAI,CA4BhF"}

package/dist/config.d.ts

@@ -0,0 +1,33 @@
+export type Formatter = "biome" | "prettier" | "deno" | "ruff" | "black" | "rustfmt" | "goimports" | "gofmt" | "none";
+export type Checker = "tsc" | "biome" | "pyright" | "ruff" | "cargo" | "go" | "staticcheck" | "none";
+export type SemanticBackend = "fastembed" | "openai_compatible" | "ollama";
+export interface SemanticConfig {
+    backend?: SemanticBackend;
+    model?: string;
+    base_url?: string;
+    api_key_env?: string;
+    timeout_ms?: number;
+    max_batch_size?: number;
+}
+export type ToolSurface = "minimal" | "recommended" | "all";
+export interface AftConfig {
+    format_on_edit?: boolean;
+    validate_on_edit?: "syntax" | "full";
+    formatter?: Record<string, Formatter>;
+    checker?: Record<string, Checker>;
+    tool_surface?: ToolSurface;
+    disabled_tools?: string[];
+    restrict_to_project_root?: boolean;
+    experimental_search_index?: boolean;
+    experimental_semantic_search?: boolean;
+    semantic?: SemanticConfig;
+}
+/**
+ * Load AFT config:
+ *   1. User-level:    ~/.pi/agent/aft.jsonc (or .json)
+ *   2. Project-level: <project>/.pi/aft.jsonc (or .json)
+ *
+ * Project config merges on top of user config.
+ */
+export declare function loadAftConfig(projectDirectory: string): AftConfig;
+//# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AASA,MAAM,MAAM,SAAS,GACjB,OAAO,GACP,UAAU,GACV,MAAM,GACN,MAAM,GACN,OAAO,GACP,SAAS,GACT,WAAW,GACX,OAAO,GACP,MAAM,CAAC;AAEX,MAAM,MAAM,OAAO,GACf,KAAK,GACL,OAAO,GACP,SAAS,GACT,MAAM,GACN,OAAO,GACP,IAAI,GACJ,aAAa,GACb,MAAM,CAAC;AAEX,MAAM,MAAM,eAAe,GAAG,WAAW,GAAG,mBAAmB,GAAG,QAAQ,CAAC;AAE3E,MAAM,WAAW,cAAc;IAC7B,OAAO,CAAC,EAAE,eAAe,CAAC;IAC1B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,MAAM,WAAW,GAAG,SAAS,GAAG,aAAa,GAAG,KAAK,CAAC;AAE5D,MAAM,WAAW,SAAS;IACxB,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,gBAAgB,CAAC,EAAE,QAAQ,GAAG,MAAM,CAAC;IACrC,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;IACtC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,YAAY,CAAC,EAAE,WAAW,CAAC;IAC3B,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B,wBAAwB,CAAC,EAAE,OAAO,CAAC;IACnC,yBAAyB,CAAC,EAAE,OAAO,CAAC;IACpC,4BAA4B,CAAC,EAAE,OAAO,CAAC;IACvC,QAAQ,CAAC,EAAE,cAAc,CAAC;CAC3B;AAuID;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,gBAAgB,EAAE,MAAM,GAAG,SAAS,CA4BjE"}

package/dist/downloader.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Auto-download the AFT binary from GitHub releases.
+ *
+ * Resolution order (in resolver.ts):
+ *   1. Cached binary in ~/.cache/aft/bin/
+ *   2. npm platform package (@cortexkit/aft-darwin-arm64, etc.)
+ *   3. PATH lookup (which aft)
+ *   4. ~/.cargo/bin/aft
+ *   5. Auto-download from GitHub releases (this module)
+ *
+ * Cache dir respects XDG_CACHE_HOME on Linux/macOS and LOCALAPPDATA on Windows.
+ */
+/** Get the cache directory, respecting XDG_CACHE_HOME / LOCALAPPDATA. */
+export declare function getCacheDir(): string;
+/** Binary name for the current platform. */
+export declare function getBinaryName(): string;
+/** Return the cached binary path if it exists, otherwise null.
+ *  Checks the version-specific cache directory only.
+ *  The legacy flat cache (~/.cache/aft/bin/aft) is intentionally NOT checked
+ *  because it can be overwritten by other instances, corrupting running processes. */
+export declare function getCachedBinaryPath(version?: string): string | null;
+/**
+ * Download the AFT binary for the current platform from GitHub releases.
+ *
+ * @param version - Git tag to download from (e.g. "v0.1.0"). If omitted,
+ *   fetches the latest release tag via the GitHub API.
+ * @returns Absolute path to the downloaded binary, or null on failure.
+ */
+export declare function downloadBinary(version?: string): Promise<string | null>;
+/**
+ * Ensure the AFT binary is available: check cache, then download if needed.
+ * This is the main entry point called by the resolver.
+ */
+export declare function ensureBinary(version?: string): Promise<string | null>;
+//# sourceMappingURL=downloader.d.ts.map

package/dist/downloader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"downloader.d.ts","sourceRoot":"","sources":["../src/downloader.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAUH,yEAAyE;AACzE,wBAAgB,WAAW,IAAI,MAAM,CASpC;AAED,4CAA4C;AAC5C,wBAAgB,aAAa,IAAI,MAAM,CAEtC;AAED;;;sFAGsF;AACtF,wBAAgB,mBAAmB,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAInE;AAED;;;;;;GAMG;AACH,wBAAsB,cAAc,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAgH7E;AAED;;;GAGG;AACH,wBAAsB,YAAY,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAqB3E"}

package/dist/index.d.ts

@@ -0,0 +1,39 @@
+/**
+ * AFT (Agent File Tools) extension for Pi coding agent.
+ *
+ * Config is loaded from two levels (project overrides user):
+ * - User:    ~/.pi/agent/aft.jsonc (or .json)
+ * - Project: <project>/.pi/aft.jsonc (or .json)
+ *
+ * Tools registered:
+ *
+ * Hoisting (replace Pi's built-in tools):
+ *   - read   → AFT's indexed Rust reader
+ *   - write  → AFT's atomic writer with backup + auto-format + LSP diagnostics
+ *   - edit   → AFT's fuzzy-match edit with backup + diagnostics
+ *   - grep   → AFT's trigram-indexed grep (falls back to ripgrep outside project root)
+ *
+ * AFT-specific:
+ *   - aft_outline    Structural outline (symbols, headings) for files/URLs
+ *   - aft_zoom       Symbol-level inspection with call-graph annotations
+ *   - aft_search     Semantic search (when experimental_semantic_search=true)
+ *   - aft_navigate   Call-graph navigation (callers, call_tree, impact, trace_to, trace_data)
+ *   - aft_conflicts  One-call merge conflict inspection
+ *   - aft_import     Language-aware import add/remove/organize
+ *   - aft_safety     Per-file undo, checkpoints, restore
+ *   - aft_delete     Delete file with backup
+ *   - aft_move       Move/rename file
+ *   - ast_grep_search / ast_grep_replace  AST-aware pattern search/rewrite
+ *   - lsp_diagnostics On-demand LSP diagnostics
+ *
+ * Commands:
+ *   - /aft-status    Status dialog (index states, LSP servers, storage dir)
+ */
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+/**
+ * Pi extension default export.
+ *
+ * Called once per session. Registers tools, commands, and session shutdown hooks.
+ */
+export default function (pi: ExtensionAPI): Promise<void>;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAKH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,+BAA+B,CAAC;AA8HlE;;;;GAIG;AACH,yBAA+B,EAAE,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAiH9D"}