pi-tree-sitter 0.1.0

package/LICENSE

@@ -0,0 +1,314 @@
+Copyright (c) 2026 - present Marko Kocic <marko@euptera.com>
+
+All rights reserved. This program and the accompanying materials
+are made available under the terms of the Eclipse Public License 2.0
+which accompanies this distribution, and is available at
+https://www.eclipse.org/legal/epl-2.0/
+
+SPDX-License-Identifier: EPL-2.0
+
+Eclipse Public License - v 2.0
+
+    THE ACCOMPANYING PROGRAM IS PROVIDED UNDER THE TERMS OF THIS ECLIPSE
+    PUBLIC LICENSE ("AGREEMENT"). ANY USE, REPRODUCTION OR DISTRIBUTION
+    OF THE PROGRAM CONSTITUTES RECIPIENT'S ACCEPTANCE OF THIS AGREEMENT.
+
+1. DEFINITIONS
+
+"Contribution" means:
+
+  (a) in the case of the initial Contributor, the initial content
+      Distributed under this Agreement, and
+
+  (b) in the case of each subsequent Contributor:
+      i) changes to the Program, and
+      ii) additions to the Program;
+  where such changes and/or additions to the Program originate from
+  and are Distributed by that particular Contributor. A Contribution
+  "originates" from a Contributor if it was added to the Program by
+  such Contributor itself or anyone acting on such Contributor's behalf.
+  Contributions do not include changes or additions to the Program that
+  are not Modified Works.
+
+"Contributor" means any person or entity that Distributes the Program.
+
+"Licensed Patents" mean patent claims licensable by a Contributor which
+are necessarily infringed by the use or sale of its Contribution alone
+or when combined with the Program.
+
+"Program" means the Contributions Distributed in accordance with this
+Agreement.
+
+"Recipient" means anyone who receives the Program under this Agreement
+or any Secondary License (as applicable), including Contributors.
+
+"Derivative Works" shall mean any work, whether in Source Code or other
+form, that is based on (or derived from) the Program and for which the
+editorial revisions, annotations, elaborations, or other modifications
+represent, as a whole, an original work of authorship.
+
+"Modified Works" shall mean any work in Source Code or other form that
+results from an addition to, deletion from, or modification of the
+contents of the Program, including, for purposes of clarity any new file
+in Source Code form that contains any contents of the Program. Modified
+Works shall not include works that contain only the Program or a portion
+thereof.
+
+"Distribute" means the acts of a) distributing or b) making available
+in any manner that enables the transfer of a copy.
+
+"Source Code" means the form of a Program preferred for making
+modifications, including but not limited to software source code,
+documentation source, and configuration files.
+
+"Secondary License" means either the GNU General Public License,
+Version 2.0, or any later versions of that license, including any
+exceptions or additional permissions as identified by the initial
+Contributor.
+
+2. GRANT OF RIGHTS
+
+  a) Subject to the terms of this Agreement, each Contributor hereby
+  grants Recipient a non-exclusive, worldwide, royalty-free copyright
+  license to reproduce, prepare Derivative Works of, publicly display,
+  publicly perform, Distribute and sublicense the Contribution of such
+  Contributor, if any, and such Derivative Works.
+
+  b) Subject to the terms of this Agreement, each Contributor hereby
+  grants Recipient a non-exclusive, worldwide, royalty-free patent
+  license under Licensed Patents to make, use, sell, offer to sell,
+  import and otherwise transfer the Program in whole or in part, in
+  or without combination with the Contribution of such Contributor, if
+  any, and such Derivative Works. The patent license granted shall not
+  apply to: (a) any other combinations that include the Contribution,
+  or (b) any patent claims that are infringed by the Contribution alone
+  or by the combination of the Contribution with the Program to which
+  such Contribution was added. If Recipient institutes patent litigation
+  against any entity (including a cross-claim or counterclaim in a
+  lawsuit) alleging that the Contribution itself (in combination with
+  the Program to which such Contribution was added) constitutes direct
+  or contributory patent infringement, then any patent licenses granted
+  to that Recipient under this Agreement shall terminate as of the date
+  such litigation is filed.
+
+  c) Recipient understands that although each Contributor grants the
+  licenses to its Contributions set forth herein, no assurances are
+  provided by any Contributor that the Program does not infringe the
+  patent or other intellectual property rights of any other entity.
+  Each Contributor disclaims any liability to Recipient for claims
+  brought by any other entity based on infringement of intellectual
+  property rights or otherwise. As a condition to exercising the
+  rights and licenses granted hereunder, each Recipient hereby assumes
+  sole responsibility to secure any other intellectual property rights
+  needed, if any. For example, if a third party patent license is
+  required to allow Recipient to Distribute the Program, it is
+  Recipient's responsibility to acquire that license before
+  distributing the Program.
+
+  d) Each Contributor represents that to its knowledge it has
+  sufficient copyright rights in its Contribution, if any, to grant
+  the copyright license set forth in this Agreement.
+
+  e) Notwithstanding the terms of any Secondary License, no
+  Contributor makes additional grants to any Recipient (other than
+  those set forth in this Agreement) as a result of such Recipient's
+  receipt of the Program under a Secondary License (if permitted under
+  the terms of Section 3).
+
+3. REQUIREMENTS
+
+3.1 If a Contributor Distributes the Program in any form, then:
+
+  a) the Program must also be made available as Source Code, in
+  accordance with section 3.2, and the Contributor must accompany
+  the Program with a statement that the Source Code for the Program
+  is available under this Agreement, and informs Recipients how to
+  obtain it in a reasonable manner on or through a medium customarily
+  used for software exchange; and
+
+  b) the Contributor may Distribute the Program under a license
+  different than this Agreement, provided that such license:
+     i) effectively disclaims on behalf of all other Contributors all
+     warranties and conditions, express and implied, including
+     warranties or conditions of title and non-infringement, and
+     implied warranties or conditions of merchantability and fitness
+     for a particular purpose;
+
+     ii) effectively excludes on behalf of all other Contributors all
+     liability for damages, including direct, indirect, special,
+     incidental and consequential damages, such as lost profits;
+
+     iii) does not attempt to limit or alter the recipients' rights
+     in the Source Code under section 3.2; and
+
+     iv) requires any subsequent distribution of the Program by any
+     party to be under a license that satisfies the requirements
+     of this section 3.
+
+3.2 When the Program is Distributed as Source Code:
+
+  a) it must be made available under this Agreement, or if the
+  Program (i) is combined with other material in a separate file or
+  files made available under a Secondary License, and (ii) the initial
+  Contributor attached to the Source Code the notice described in
+  Exhibit A of this Agreement, then the Program may be made available
+  under the terms of such Secondary Licenses, and
+
+  b) a copy of this Agreement must be included with each copy of
+  the Program.
+
+3.3 Contributors may not remove or alter any copyright, patent,
+trademark, attribution notices, disclaimers of warranty, or limitations
+of liability ("notices") contained within the Program from any copy or
+distribution of the Program, provided that Contributors may add their
+own appropriate notices.
+
+4. COMMERCIAL DISTRIBUTION
+
+Commercial distributors of software may accept certain
+responsibilities with respect to end users, business partners and the
+like. While this license is intended to facilitate the commercial use
+of the Program, the Contributor who includes the Program in a
+commercial product offering should do so in a manner which does not
+create potential liability for other Contributors. Therefore, if a
+Contributor includes the Program in a commercial product offering,
+such Contributor ("Commercial Contributor") hereby agrees to defend
+and indemnify every other Contributor ("Indemnified Contributor")
+against any losses, damages and costs (collectively "Losses") arising
+from claims, lawsuits and other legal actions brought by a third party
+against the Indemnified Contributor to the extent caused by the acts
+or omissions of such Commercial Contributor in connection with its
+distribution of the Program in a commercial product offering. The
+obligations in this section do not apply to any claims or Losses
+relating to any actual or alleged intellectual property infringement.
+In order to qualify, an Indemnified Contributor must: a) promptly
+notify the Commercial Contributor in writing of such claim, and b)
+allow the Commercial Contributor to control, and cooperate with the
+Commercial Contributor in, the defense and any related settlement
+negotiations. The Indemnified Contributor may participate in any such
+claim at its own expense.
+
+For example, a Contributor might include the Program in a commercial
+product offering, Product X. That Contributor is then a Commercial
+Contributor. If that Commercial Contributor then makes performance
+claims, or offers warranties related to Product X, those performance
+claims and warranties are solely the responsibility of that Commercial
+Contributor. Under this section, the Commercial Contributor would have
+to defend claims against the other Contributors related to those
+performance claims and warranties, and if a court requires any other
+Contributor to pay any damages as a result, the Commercial Contributor
+must pay those damages.
+
+5. NO WARRANTY
+
+EXCEPT AS EXPRESSLY SET FORTH IN THIS AGREEMENT, AND TO THE EXTENT
+PERMITTED BY APPLICABLE LAW, THE PROGRAM IS PROVIDED ON AN "AS IS"
+BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, EITHER EXPRESS OR
+IMPLIED INCLUDING, WITHOUT LIMITATION, ANY WARRANTIES OR CONDITIONS OF
+TITLE, NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR A PARTICULAR
+PURPOSE. Each Recipient is solely responsible for determining the
+appropriateness of using and distributing the Program and assumes all
+risks associated with its exercise of rights under this Agreement,
+including but not limited to the risks and costs of program errors,
+compliance with applicable laws, damage to or loss of data, programs
+or equipment, and unavailability or interruption of operations.
+
+6. DISCLAIMER OF LIABILITY
+
+EXCEPT AS EXPRESSLY SET FORTH IN THIS AGREEMENT, AND TO THE EXTENT
+PERMITTED BY APPLICABLE LAW, NEITHER RECIPIENT NOR ANY CONTRIBUTORS
+SHALL HAVE ANY LIABILITY FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
+EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING WITHOUT LIMITATION LOST
+PROFITS), HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ARISING IN ANY WAY OUT OF THE USE OR DISTRIBUTION OF THE PROGRAM OR THE
+EXERCISE OF ANY RIGHTS GRANTED HEREUNDER, EVEN IF ADVISED OF THE
+POSSIBILITY OF SUCH DAMAGES.
+
+7. GENERAL
+
+If any provision of this Agreement is invalid or unenforceable under
+applicable law, it shall not affect the validity or enforceability of
+the remainder of the terms of this Agreement, and without further
+action by the parties hereto, such provision shall be reformed to the
+minimum extent necessary to make such provision valid and enforceable.
+
+If Recipient institutes patent litigation against any entity (including
+a cross-claim or counterclaim in a lawsuit) alleging that the Program
+itself (excluding combinations of the Program with other software or
+hardware) infringes such Recipient's patent(s), then such Recipient's
+rights granted under Section 2(b) shall terminate as of the date such
+litigation is filed.
+
+All Recipient's rights under this Agreement shall terminate if it
+fails to comply with any of the material terms or conditions of this
+Agreement and does not cure such failure in a reasonable period of
+time after becoming aware thereof. Notwithstanding the above, if
+Recipient's rights under this Agreement terminate, Recipient agrees to
+cease use and distribution of the Program as soon as reasonably
+practicable. However, Recipient's obligations under this Agreement and
+any licenses granted by Recipient relating to the Program shall
+continue and survive.
+
+Everyone is permitted to copy and distribute copies of this Agreement,
+but in order to avoid inconsistency the Agreement is copyrighted and
+may only be modified in the following manner. The Agreement Steward
+reserves the right to publish new versions (including revisions) of
+this Agreement from time to time. No one other than the Agreement
+Steward has the right to modify this Agreement. The Eclipse Foundation
+is the initial Agreement Steward. The Eclipse Foundation may assign the
+responsibility to serve as the Agreement Steward to a suitable separate
+entity. Each new version of the Agreement will be given a distinguishing
+version number. The Program (including Contributions) may always be
+Distributed subject to the version of the Agreement under which it was
+received. In addition, after a new version of the Agreement is published,
+Contributor may elect to Distribute the Program (including its
+Contributions) under the new version.
+
+Except as expressly stated in Sections 2(a) and 2(b) above, Recipient
+receives no rights or licenses to the intellectual property of any
+Contributor under this Agreement, whether expressly, by implication,
+estoppel or otherwise. All rights in the Program not expressly granted
+under this Agreement are reserved.
+
+Nothing in this Agreement shall be deemed to create an agency between
+the parties. No partnership, joint venture, or employment relationship
+is created. Neither party shall have the power to bind the other
+without the other party's prior written consent. If any provision of
+this Agreement is found by a court of competent jurisdiction to be
+invalid, illegal, or unenforceable, the remaining provisions shall
+continue in full force and effect and the parties shall replace the
+invalid, illegal, or unenforceable provision with a provision that
+reflects the parties' original intent and is valid, legal, and
+enforceable.
+
+Neither party shall be liable for any failure or delay in performance
+due to causes beyond its reasonable control. The terms of this
+Agreement shall be governed by the laws of the State of New York,
+USA, without regard to its conflict of laws provisions. Each party
+hereby consents to the exclusive jurisdiction of the federal and state
+courts located in New York, New York, USA, except that either party may
+seek injunctive or other equitable relief in any court of competent
+jurisdiction to protect its intellectual property rights.
+
+If any provision of this Agreement is invalid or unenforceable under
+applicable law, it shall not affect the validity or enforceability of
+the remainder of the terms of this Agreement.
+
+EXHIBIT A - Form of Secondary Licenses Notice
+
+"This Source Code may also be made available under the following
+Secondary Licenses when the conditions for such availability set forth
+in the Eclipse Public License, v. 2.0 are satisfied: {name license(s),
+version(s), and exceptions or additional permissions here}."
+
+  Simply including a copy of this Agreement, including this Exhibit A
+  is not sufficient to license the Source Code under Secondary
+  Licenses.
+
+  If it is not possible or desirable to put the notice in a particular
+  file, then You may include the notice in a location (such as a
+  LICENSE file in a relevant directory) where a recipient would be
+  likely to look for such a notice.
+
+  You may add additional accurate notices of copyright ownership.

package/README.md

@@ -0,0 +1,119 @@
+# pi-tree-sitter
+
+Pre-write syntax validation for [pi](https://pi.dev) using tree-sitter WASM grammars.
+
+Hooks into `write` and `edit` tools to validate file content before it hits disk.
+If tree-sitter finds syntax errors, the extension blocks the tool with actionable
+feedback — line, column, source snippet, and for `MISSING` nodes, what token was
+expected. The LLM sees the error in the same turn and self-corrects.
+
+Inspired by [dirge](https://github.com/dirge-code/dirge)'s `syntax_validator.rs`.
+
+## Installation
+
+```bash
+npm install pi-tree-sitter
+```
+
+Then register with pi:
+
+```bash
+pi install npm:pi-tree-sitter
+```
+
+### Git version
+
+Install directly from GitHub:
+
+```bash
+pi install git:github.com/markokocic/pi-tree-sitter
+```
+
+Or clone and use locally:
+
+```bash
+git clone https://github.com/markokocic/pi-tree-sitter.git
+cd pi-tree-sitter
+npm install
+pi install .
+```
+
+Run ad-hoc without installing:
+
+```bash
+pi -e ./path/to/pi-tree-sitter
+```
+
+## Supported Languages
+
+| Extension(s) | Grammar | WASM |
+|-------------|---------|------|
+| `.rs` | Rust | ✅ |
+| `.py`, `.pyi` | Python | ✅ |
+| `.ts`, `.mts`, `.cts` | TypeScript | ✅ |
+| `.tsx` | TSX | ✅ |
+| `.js`, `.jsx`, `.mjs`, `.cjs` | JavaScript | ✅ |
+| `.go` | Go | ✅ |
+| `.java` | Java | ✅ |
+| `.rb` | Ruby | ✅ |
+| `.c`, `.h` | C | ✅ |
+| `.cpp`, `.cc`, `.hpp`, `.hh`, `.hxx` | C++ | ✅ |
+| `.sh`, `.bash` | Bash | ✅ |
+| `.css` | CSS | ✅ |
+| `.ex`, `.exs` | Elixir | ✅ |
+| `.hs`, `.lhs` | Haskell | ✅ |
+| `.htm`, `.html` | HTML | ✅ |
+| `.json` | JSON | ✅ |
+| `.kt`, `.kts` | Kotlin | ✅ |
+| `.zig` | Zig | ✅ |
+| `.clj`, `.cljs`, `.cljc`, `.cljd`, `.edn`, `.bb` | Clojure | 🔶 (delimiter balance) |
+| `.fnl` | Fennel | 🔶 (delimiter balance) |
+| `.janet`, `.jdn` | Janet | 🔶 (delimiter balance) |
+| `.scm`, `.ss`, `.rkt` | Scheme | 🔶 (delimiter balance) |
+| `.lisp`, `.lsp`, `.cl` | Common Lisp | 🔶 (delimiter balance) |
+| `.el` | Emacs Lisp | 🔶 (delimiter balance) |
+
+Languages marked with 🔶 use a comment/string-aware delimiter-balance scanner
+as a fallback (no standalone WASM grammar available on npm).
+
+WASM grammars are loaded on first use via a hybrid strategy:
+local `node_modules` → disk cache (`~/.cache/pi-tree-sitter/`) → CDN.
+No explicit `npm install` of individual grammar packages is required.
+
+## How it works
+
+1. Extension hooks `tool_call` events for `write` and `edit` tools
+2. Maps file extension to a tree-sitter WASM grammar
+3. Parses the content with tree-sitter
+4. Walks the syntax tree collecting `ERROR` and `MISSING` nodes (capped at 10)
+5. On errors: blocks the tool with `{ block: true, reason: "..." }` — the LLM
+   sees the errors and self-corrects in the same turn
+6. Unknown extensions silently pass through (no validation)
+
+### For `edit` tools
+
+The extension reads the current file, applies the edits, and validates the
+resulting content. This is a best-effort check: if an edit can't be applied
+(oldText not found), that edit is skipped and the edit tool's own error
+handling takes over.
+
+## Error Format
+
+```
+Syntax check failed for src/main.rs: 2 error(s) detected by tree-sitter.
+Fix and re-submit. (This is a pre-write guard — the file was NOT modified.)
+  missing `}` at 42:1: fn main() {
+  syntax error at 15:8: let x =
+```
+
+For delimiter-based languages (Clojure, Fennel, etc.):
+
+```
+Syntax check failed for core.clj: delimiters are unbalanced.
+Fix and re-submit. (This is a pre-write guard — the file was NOT modified.)
+  1 unclosed `(` — add 1 matching `)`
+```
+
+## License
+
+EPL-2.0 — Copyright 2026 Marko Kocic

package/index.ts

@@ -0,0 +1,455 @@
+/**
+ * pi-tree-sitter — Pre-write syntax validation for pi
+ *
+ * Hooks into `write` and `edit` tools. Parses content with tree-sitter WASM
+ * grammars and blocks the tool when syntax errors are found. The LLM sees the
+ * actionable feedback (line:col, snippet, expected token) in the same turn and
+ * self-corrects.
+ *
+ * Languages without a WASM grammar (Clojure, Janet, Fennel, Scheme, Elisp)
+ * fall back to a comment/string-aware delimiter-balance scanner.
+ *
+ * Inspired by dirge's syntax_validator.rs.
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { readFile, writeFile, mkdir } from "node:fs/promises";
+import { resolve, dirname } from "node:path";
+import { homedir } from "node:os";
+import { createRequire } from "node:module";
+import { Parser, Language, type Node, type Tree } from "web-tree-sitter";
+
+// ── Grammar map ──────────────────────────────────────────────────────────
+// Maps file extension → { npm package, wasm filename } for lazy loading.
+
+interface GrammarEntry {
+  pkg: string;
+  wasm: string;
+}
+
+const LANGUAGE_MAP: Record<string, GrammarEntry> = {
+  ".rs":   { pkg: "tree-sitter-rust", wasm: "tree-sitter-rust.wasm" },
+  ".py":   { pkg: "tree-sitter-python", wasm: "tree-sitter-python.wasm" },
+  ".pyi":  { pkg: "tree-sitter-python", wasm: "tree-sitter-python.wasm" },
+  ".ts":   { pkg: "tree-sitter-typescript", wasm: "tree-sitter-typescript.wasm" },
+  ".tsx":  { pkg: "tree-sitter-typescript", wasm: "tree-sitter-tsx.wasm" },
+  ".mts":  { pkg: "tree-sitter-typescript", wasm: "tree-sitter-typescript.wasm" },
+  ".cts":  { pkg: "tree-sitter-typescript", wasm: "tree-sitter-typescript.wasm" },
+  ".js":   { pkg: "tree-sitter-javascript", wasm: "tree-sitter-javascript.wasm" },
+  ".jsx":  { pkg: "tree-sitter-javascript", wasm: "tree-sitter-javascript.wasm" },
+  ".mjs":  { pkg: "tree-sitter-javascript", wasm: "tree-sitter-javascript.wasm" },
+  ".cjs":  { pkg: "tree-sitter-javascript", wasm: "tree-sitter-javascript.wasm" },
+  ".go":   { pkg: "tree-sitter-go", wasm: "tree-sitter-go.wasm" },
+  ".java": { pkg: "tree-sitter-java", wasm: "tree-sitter-java.wasm" },
+  ".rb":   { pkg: "tree-sitter-ruby", wasm: "tree-sitter-ruby.wasm" },
+  ".c":    { pkg: "tree-sitter-c", wasm: "tree-sitter-c.wasm" },
+  ".h":    { pkg: "tree-sitter-c", wasm: "tree-sitter-c.wasm" },
+  ".cpp":  { pkg: "tree-sitter-cpp", wasm: "tree-sitter-cpp.wasm" },
+  ".cc":   { pkg: "tree-sitter-cpp", wasm: "tree-sitter-cpp.wasm" },
+  ".hpp":  { pkg: "tree-sitter-cpp", wasm: "tree-sitter-cpp.wasm" },
+  ".hh":   { pkg: "tree-sitter-cpp", wasm: "tree-sitter-cpp.wasm" },
+  ".hxx":  { pkg: "tree-sitter-cpp", wasm: "tree-sitter-cpp.wasm" },
+  ".sh":   { pkg: "tree-sitter-bash", wasm: "tree-sitter-bash.wasm" },
+  ".bash": { pkg: "tree-sitter-bash", wasm: "tree-sitter-bash.wasm" },
+  ".css":  { pkg: "tree-sitter-css", wasm: "tree-sitter-css.wasm" },
+  ".ex":   { pkg: "tree-sitter-elixir", wasm: "tree-sitter-elixir.wasm" },
+  ".exs":  { pkg: "tree-sitter-elixir", wasm: "tree-sitter-elixir.wasm" },
+  ".hs":   { pkg: "tree-sitter-haskell", wasm: "tree-sitter-haskell.wasm" },
+  ".htm":  { pkg: "tree-sitter-html", wasm: "tree-sitter-html.wasm" },
+  ".html": { pkg: "tree-sitter-html", wasm: "tree-sitter-html.wasm" },
+  ".json": { pkg: "tree-sitter-json", wasm: "tree-sitter-json.wasm" },
+  ".kt":   { pkg: "@tree-sitter-grammars/tree-sitter-kotlin", wasm: "tree-sitter-kotlin.wasm" },
+  ".kts":  { pkg: "@tree-sitter-grammars/tree-sitter-kotlin", wasm: "tree-sitter-kotlin.wasm" },
+  ".lhs":  { pkg: "tree-sitter-haskell", wasm: "tree-sitter-haskell.wasm" },
+  ".zig":  { pkg: "@tree-sitter-grammars/tree-sitter-zig", wasm: "tree-sitter-zig.wasm" },
+};
+
+// ── Grammar cache (hybrid: local → disk cache → CDN) ─────────────────────
+
+const WASM_CDN = "https://cdn.jsdelivr.net/npm";
+const CACHE_DIR = resolve(homedir(), ".cache", "pi-tree-sitter");
+
+const require_ = createRequire(import.meta.url);
+const grammarCache = new Map<string, Language | null>();
+
+/** Resolve a WASM file: local node_modules → disk cache → CDN fetch. */
+async function loadGrammar(entry: GrammarEntry): Promise<Language | null> {
+  const key = `${entry.pkg}/${entry.wasm}`;
+  const cached = grammarCache.get(key);
+  if (cached !== undefined) return cached;
+
+  let wasmBytes: Buffer | Uint8Array | null = null;
+
+  // 1. Local node_modules (zero latency)
+  try {
+    const wasmPath = require_.resolve(key);
+    wasmBytes = await readFile(wasmPath);
+  } catch {
+    // 2. Persistent disk cache (offline reuse)
+    const cachePath = resolve(CACHE_DIR, entry.pkg, entry.wasm);
+    try {
+      wasmBytes = await readFile(cachePath);
+    } catch {
+      // 3. CDN fetch (always works, no npm dependency)
+      try {
+        const url = `${WASM_CDN}/${key}`;
+        console.log(`[pi-tree-sitter] downloading ${key} from CDN...`);
+        const res = await fetch(url);
+        if (!res.ok) throw new Error(`HTTP ${res.status}`);
+        wasmBytes = new Uint8Array(await res.arrayBuffer());
+        console.log(`[pi-tree-sitter] ${key} downloaded (${(wasmBytes.length / 1024).toFixed(0)} KB)`);
+        // Persist to disk cache for next time
+        await mkdir(dirname(cachePath), { recursive: true });
+        await writeFile(cachePath, wasmBytes);
+      } catch {
+        console.log(`[pi-tree-sitter] failed to download ${key}, skipping validation`);
+        // All sources exhausted
+      }
+    }
+  }
+
+  if (wasmBytes) {
+    try {
+      const lang = await Language.load(wasmBytes);
+      grammarCache.set(key, lang);
+      return lang;
+    } catch {
+      grammarCache.set(key, null);
+      return null;
+    }
+  }
+
+  grammarCache.set(key, null);
+  return null;
+}
+
+// ── Error collection ─────────────────────────────────────────────────────
+
+const MAX_ERRORS = 10;
+
+/** Collect ERROR/MISSING nodes from a syntax tree, capped at MAX_ERRORS. */
+function collectErrors(tree: Tree, source: string): string[] {
+  const errors: string[] = [];
+  const stack: Node[] = [tree.rootNode];
+
+  while (stack.length > 0 && errors.length < MAX_ERRORS) {
+    const node = stack.pop()!;
+
+    if (node.isError || node.isMissing) {
+      const pos = node.startPosition;
+      const raw = source.slice(node.startIndex, Math.min(node.endIndex, source.length));
+      const snippet = raw.split("\n")[0].slice(0, 80).trimEnd();
+
+      if (node.isMissing) {
+        // For MISSING nodes, `.type` is the grammar-level expected token
+        // (e.g. "}", ")", ";"). This is the most actionable detail.
+        errors.push(`  missing \`${node.type}\` at ${pos.row + 1}:${pos.column + 1}: ${snippet}`);
+      } else {
+        errors.push(`  syntax error at ${pos.row + 1}:${pos.column + 1}: ${snippet}`);
+      }
+      // Don't descend into error nodes — their children are noise.
+      continue;
+    }
+
+    // Push children in reverse order so the walk is left-to-right.
+    const children = node.children;
+    for (let i = children.length - 1; i >= 0; i--) {
+      stack.push(children[i]);
+    }
+  }
+
+  return errors;
+}
+
+// ── Delimiter-balance scanner (fallback for Lisp-like languages) ─────────
+
+/**
+ * Simple line/column counter for the balance scanner.
+ * Tracks absolute position for error reporting but is simple enough that
+ * we compute line numbers inline for human-readable messages.
+ */
+interface LexRules {
+  lineComment: string | null;              // e.g. ";"
+  blockComment: [string, string] | null;   // e.g. ["#|", "|#"]
+  nestedBlock: boolean;
+  backtickLongString: boolean;
+  charLiteral: "?" | null;                 // e.g. Elisp uses ?x for char literals
+}
+
+const RULES_LISP: LexRules     = { lineComment: ";", blockComment: null, nestedBlock: false, backtickLongString: false, charLiteral: null };
+const RULES_JANET: LexRules    = { lineComment: "#", blockComment: ["#|", "|#"], nestedBlock: false, backtickLongString: true, charLiteral: null };
+const RULES_SCHEME: LexRules   = { lineComment: ";", blockComment: ["#|", "|#"], nestedBlock: true, backtickLongString: false, charLiteral: null };
+
+const BALANCE_RULES: Record<string, LexRules> = {
+  ".clj":   RULES_LISP,
+  ".cljs":  RULES_LISP,
+  ".cljc":  RULES_LISP,
+  ".cljd":  RULES_LISP,
+  ".edn":   RULES_LISP,
+  ".bb":    RULES_LISP,
+  ".fnl":   RULES_LISP,
+  ".janet": RULES_JANET,
+  ".jdn":   RULES_JANET,
+  ".scm":   RULES_SCHEME,
+  ".ss":    RULES_SCHEME,
+  ".rkt":   RULES_SCHEME,
+  ".lisp":  RULES_SCHEME,
+  ".lsp":   RULES_SCHEME,
+  ".cl":    RULES_SCHEME,
+  ".el":    { lineComment: ";", blockComment: null, nestedBlock: false, backtickLongString: false, charLiteral: "?" },
+};
+
+/** Count delimiters skipping comments, strings, and char literals. */
+function checkDelimiterBalance(path: string, content: string, rules: LexRules): string | null {
+  const b = content;
+  const n = b.length;
+  let i = 0;
+  const lineStarts: number[] = [0];
+  for (let j = 0; j < n; j++) {
+    if (b[j] === "\n") lineStarts.push(j + 1);
+  }
+
+  function lineFor(pos: number): number {
+    // Binary search for the nearest line start ≤ pos
+    let lo = 0, hi = lineStarts.length - 1;
+    while (lo < hi) {
+      const mid = (lo + hi + 1) >> 1;
+      if (lineStarts[mid] <= pos) lo = mid;
+      else hi = mid - 1;
+    }
+    return lo + 1; // 1-based
+  }
+
+  const stack: Array<{ ch: string; line: number; col: number }> = [];
+
+  while (i < n) {
+    const c = b[i];
+    const next = i + 1 < n ? b[i + 1] : null;
+
+    // Line comment
+    if (rules.lineComment && c === rules.lineComment[0]) {
+      const eol = b.indexOf("\n", i);
+      i = eol === -1 ? n : eol + 1;
+      continue;
+    }
+
+    // Block comment
+    if (rules.blockComment) {
+      const [open, close] = rules.blockComment;
+      if (c === open[0] && next === open[1]) {
+        i += 2;
+        let depth = 1;
+        while (i < n && depth > 0) {
+          const cc = b[i];
+          const nn = i + 1 < n ? b[i + 1] : null;
+          if (rules.nestedBlock && cc === open[0] && nn === open[1]) {
+            depth++;
+            i += 2;
+          } else if (cc === close[0] && nn === close[1]) {
+            depth--;
+            i += 2;
+          } else {
+            i++;
+          }
+        }
+        continue;
+      }
+    }
+
+    // String
+    if (c === '"') {
+      i++;
+      while (i < n) {
+        if (b[i] === "\\") { i += 2; continue; }
+        if (b[i] === '"') { i++; break; }
+        i++;
+      }
+      continue;
+    }
+
+    // Backtick long-string (Janet)
+    if (rules.backtickLongString && c === "`") {
+      // Count opening backticks
+      let k = 0;
+      while (i + k < n && b[i + k] === "`") k++;
+      i += k;
+      while (i < n) {
+        if (b[i] === "`") {
+          let j = 0;
+          while (i + j < n && b[i + j] === "`") j++;
+          if (j >= k) { i += k; break; }
+          i += j;
+        } else {
+          i++;
+        }
+      }
+      continue;
+    }
+
+    // Escape: skip \ and the following character
+    if (c === "\\" && i + 1 < n) {
+      i += 2;
+      continue;
+    }
+
+    // Char literal (e.g., Elisp: ?x, ?\()
+    if (rules.charLiteral === "?" && c === "?" && i + 1 < n) {
+      if (b[i + 1] === "\\" && i + 2 < n) {
+        i += 3; // skip ?\X
+      } else {
+        i += 2; // skip ?X
+      }
+      continue;
+    }
+
+    // Count delimiters
+    switch (c) {
+      case "(": {
+        const ln = lineFor(i);
+        stack.push({ ch: "(", line: ln, col: i - lineStarts[ln - 1] + 1 });
+        break;
+      }
+      case ")": {
+        const top = stack.pop();
+        if (!top) return `${path}: stray \`)\` at line ${lineFor(i)} — no matching \`(\` before it`;
+        break;
+      }
+      case "[": {
+        const ln = lineFor(i);
+        stack.push({ ch: "[", line: ln, col: i - lineStarts[ln - 1] + 1 });
+        break;
+      }
+      case "]": {
+        const top = stack.pop();
+        if (!top) return `${path}: stray \`]\` at line ${lineFor(i)} — no matching \`[\` before it`;
+        if (top.ch !== "[") return `${path}: mismatch at line ${lineFor(i)}: expected \`]\` for \`${top.ch}\` at line ${top.line}`;
+        break;
+      }
+      case "{": {
+        const ln = lineFor(i);
+        stack.push({ ch: "{", line: ln, col: i - lineStarts[ln - 1] + 1 });
+        break;
+      }
+      case "}": {
+        const top = stack.pop();
+        if (!top) return `${path}: stray \`}\` at line ${lineFor(i)} — no matching \`{\` before it`;
+        if (top.ch !== "{") return `${path}: mismatch at line ${lineFor(i)}: expected \`}\` for \`${top.ch}\` at line ${top.line}`;
+        break;
+      }
+    }
+
+    i++;
+  }
+
+  if (stack.length > 0) {
+    const top = stack[0];
+    const opener = top.ch;
+    return `${path}: ${stack.length} unclosed \`${opener}\` — the one at line ${top.line} is never closed; add ${stack.length} matching \`${{ "(": ")", "[": "]", "{": "}" }[opener]}\``;
+  }
+
+  return null;
+}
+
+// ── Validation helpers ──────────────────────────────────────────────────
+
+function formatError(path: string, errors: string[]): string {
+  let msg = `Syntax check failed for ${path}: ${errors.length} error(s) detected by tree-sitter.
+Fix and re-submit. (This is a pre-write guard — the file was NOT modified.)
+`;
+  msg += errors.join("\n");
+  if (errors.length >= MAX_ERRORS) {
+    msg += `\n  …(truncated at ${MAX_ERRORS} errors; fix the listed issues and re-check)`;
+  }
+  return msg;
+}
+
+function formatBalanceError(path: string, detail: string): string {
+  return `Syntax check failed for ${path}: delimiters are unbalanced.
+Fix and re-submit. (This is a pre-write guard — the file was NOT modified.)
+  ${detail}`;
+}
+
+/**
+ * Validate content for a given file path. Returns null (clean), or a
+ * formatted error message to surface as the block reason.
+ */
+async function validateContent(path: string, content: string): Promise<string | null> {
+  const ext = path.match(/\.[^.]+$/)?.[0]?.toLowerCase();
+  if (!ext) return null;
+
+  const entry = LANGUAGE_MAP[ext];
+  if (entry) {
+    const lang = await loadGrammar(entry);
+    if (lang) {
+      const parser = new Parser();
+      parser.setLanguage(lang);
+      const tree = parser.parse(content);
+      if (tree && tree.rootNode.hasError) {
+        const errors = collectErrors(tree, content);
+        if (errors.length > 0) {
+          return formatError(path, errors);
+        }
+      }
+      return null;
+    }
+    // Grammar not available from any source — skip validation
+    return null;
+  }
+
+  // Delimiter-balance scanner (only for Lisp-like languages without WASM grammars)
+  const rules = ext ? BALANCE_RULES[ext] : undefined;
+  if (rules) {
+    const err = checkDelimiterBalance(path, content, rules);
+    if (err) return formatBalanceError(path, err);
+  }
+
+  return null;
+}
+
+// ── Extension entry point ────────────────────────────────────────────────
+
+export default async function (pi: ExtensionAPI) {
+  // Initialize the web-tree-sitter WASM runtime once.
+  await Parser.init();
+
+  pi.on("tool_call", async (event, ctx) => {
+    // ── write ──────────────────────────────────────────────────────────
+    if (event.toolName === "write") {
+      const input = event.input as { path: string; content: string };
+      const err = await validateContent(input.path, input.content);
+      if (err) return { block: true, reason: err };
+      return;
+    }
+
+    // ── edit ───────────────────────────────────────────────────────────
+    if (event.toolName === "edit") {
+      const input = event.input as {
+        path: string;
+        edits: Array<{ oldText: string; newText: string }>;
+      };
+      if (!input.edits || input.edits.length === 0) return;
+
+      const absolutePath = resolve(ctx.cwd, input.path);
+
+      try {
+        const rawContent = await readFile(absolutePath, "utf-8");
+
+        // Apply edits sequentially (best-effort approximation of the final
+        // content for validation). If an edit's oldText is not found, skip
+        // it — the edit tool itself will report that error.
+        let result = rawContent;
+        for (const edit of input.edits) {
+          const idx = result.indexOf(edit.oldText);
+          if (idx === -1) continue;
+          result = result.slice(0, idx) + edit.newText + result.slice(idx + edit.oldText.length);
+        }
+
+        const err = await validateContent(input.path, result);
+        if (err) return { block: true, reason: err };
+      } catch {
+        // File doesn't exist or can't be read as UTF-8 — let the edit tool
+        // handle the error itself.
+      }
+    }
+  });
+}

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "pi-tree-sitter",
+  "version": "0.1.0",
+  "description": "Pre-write syntax validation for pi using tree-sitter WASM grammars",
+  "license": "EPL-2.0",
+  "author": "Marko Kocic <marko@euptera.com>",
+  "copyright": "Copyright (c) 2026 Marko Kocic",
+  "type": "module",
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "tree-sitter",
+    "syntax",
+    "validation",
+    "linter"
+  ],
+  "pi": {
+    "extensions": [
+      "./index.ts"
+    ]
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*"
+  },
+  "dependencies": {
+    "web-tree-sitter": "^0.26.10",
+    "tree-sitter-rust": "^0.24.0",
+    "tree-sitter-python": "^0.23.6",
+    "tree-sitter-javascript": "^0.23.1",
+    "tree-sitter-typescript": "^0.23.2",
+    "tree-sitter-go": "^0.23.4",
+    "tree-sitter-java": "^0.23.5",
+    "tree-sitter-ruby": "^0.23.1",
+    "tree-sitter-c": "^0.23.6",
+    "tree-sitter-cpp": "^0.23.4",
+    "tree-sitter-bash": "^0.25.1",
+    "tree-sitter-css": "^0.25.0",
+    "tree-sitter-elixir": "^0.3.5",
+    "tree-sitter-haskell": "^0.23.1",
+    "tree-sitter-html": "^0.23.2",
+    "tree-sitter-json": "^0.24.8",
+    "@tree-sitter-grammars/tree-sitter-kotlin": "^1.1.0",
+    "@tree-sitter-grammars/tree-sitter-zig": "^1.1.2"
+  }
+}