{"_id":"@deevus/pi-wayfinder","_rev":"6-1ddfabe23d6273f4292e43ac04303743","name":"@deevus/pi-wayfinder","dist-tags":{"latest":"0.3.2"},"versions":{"0.1.0":{"name":"@deevus/pi-wayfinder","version":"0.1.0","keywords":["pi-package","wayfinder","dirac","coding-agent","code-navigation","code-editing","anchor-stable-editing","hash-anchored","tree-sitter","ast","ast-tools","symbol-search","symbol-rename","refactoring"],"license":"Apache-2.0","_id":"@deevus/pi-wayfinder@0.1.0","maintainers":[{"name":"deevus","email":"simon@simonhartcher.com"}],"homepage":"https://github.com/deevus/pi-wayfinder#readme","bugs":{"url":"https://github.com/deevus/pi-wayfinder/issues"},"pi":{"extensions":["./src/index.ts"]},"dist":{"shasum":"989465e6d8f4aea5d707b930405fc714c546dc74","tarball":"https://registry.npmjs.org/@deevus/pi-wayfinder/-/pi-wayfinder-0.1.0.tgz","fileCount":58,"integrity":"sha512-OT7m6aBzrDukdbbz5p8aWXJrAfBYwVcvC/zQQ9yb+Mg8JGbofl+HkFwtto07aH3MDKK6sYFWzJ5jIaFbNLtoXw==","signatures":[{"sig":"MEUCIFpHSDO95mYbKAMWAGlvPOEQX3cP6QYapFDkZV41qJwqAiEA6GnZ0aAlZY7S2MVtJuum1fP9qWt8ijdiRDOY45vBMYA=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":168251},"type":"module","gitHead":"98f0026ca2921d70c37acc4ac04fa2c904178f84","scripts":{"test":"vitest run","typecheck":"tsc --noEmit"},"_npmUser":{"name":"deevus","email":"simon@simonhartcher.com"},"repository":{"url":"git+https://github.com/deevus/pi-wayfinder.git","type":"git"},"_npmVersion":"11.10.1","description":"Structure-aware code navigation and anchor-stable editing tools for pi agents.","directories":{},"_nodeVersion":"25.7.0","dependencies":{"diff":"^7.0.0","web-tree-sitter":"^0.22.6","tree-sitter-wasms":"^0.1.13"},"_hasShrinkwrap":false,"devDependencies":{"vitest":"^2.0.0","typescript":"^5.0.0","@types/node":"20.x"},"peerDependencies":{"typebox":"*","@mariozechner/pi-ai":"*","@mariozechner/pi-tui":"*","@mariozechner/pi-coding-agent":"*"},"_npmOperationalInternal":{"tmp":"tmp/pi-wayfinder_0.1.0_1778403521769_0.1071925730001062","host":"s3://npm-registry-packages-npm-production"}},"0.1.1":{"name":"@deevus/pi-wayfinder","version":"0.1.1","keywords":["pi-package","wayfinder","dirac","coding-agent","code-navigation","code-editing","anchor-stable-editing","hash-anchored","tree-sitter","ast","ast-tools","symbol-search","symbol-rename","refactoring"],"license":"Apache-2.0","_id":"@deevus/pi-wayfinder@0.1.1","maintainers":[{"name":"deevus","email":"simon@simonhartcher.com"}],"homepage":"https://github.com/deevus/pi-wayfinder#readme","bugs":{"url":"https://github.com/deevus/pi-wayfinder/issues"},"pi":{"extensions":["./src/index.ts"]},"dist":{"shasum":"1cd8cedac3130019e11500d814cfa2fe0529d7e4","tarball":"https://registry.npmjs.org/@deevus/pi-wayfinder/-/pi-wayfinder-0.1.1.tgz","fileCount":58,"integrity":"sha512-03VPAuSdKXKHKmRGC9czMLsAM4G6QQjMSu3NjQqzistGGUqH0nPVaMy6UUfgDIwlT/0HpJpieoJtmJ+Z7OXrag==","signatures":[{"sig":"MEQCIH0k/En3l3w/dM1CS8Js/x/Evsk6VvFxMrQ+EPkWuzrFAiAHdekBI+TclNFLF/PT6S5PjoDavfYpUe1bPmtAA1jquA==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":169108},"type":"module","gitHead":"d1b2cceb8d672f85b8e3698c3cbfc5dd6f4e4d32","scripts":{"test":"vitest run","typecheck":"tsc --noEmit"},"_npmUser":{"name":"deevus","email":"simon@simonhartcher.com"},"repository":{"url":"git+https://github.com/deevus/pi-wayfinder.git","type":"git"},"_npmVersion":"11.10.1","description":"Structure-aware code navigation and anchor-stable editing tools for pi agents.","directories":{},"_nodeVersion":"25.7.0","dependencies":{"diff":"^7.0.0","web-tree-sitter":"^0.22.6","tree-sitter-wasms":"^0.1.13"},"_hasShrinkwrap":false,"devDependencies":{"vitest":"^2.0.0","typescript":"^5.0.0","@types/node":"20.x"},"peerDependencies":{"typebox":"*","@earendil-works/pi-ai":"*","@earendil-works/pi-tui":"*","@earendil-works/pi-coding-agent":"*"},"_npmOperationalInternal":{"tmp":"tmp/pi-wayfinder_0.1.1_1778833932015_0.626869616579175","host":"s3://npm-registry-packages-npm-production"}},"0.2.0":{"name":"@deevus/pi-wayfinder","version":"0.2.0","keywords":["pi-package","wayfinder","dirac","coding-agent","code-navigation","code-editing","anchor-stable-editing","hash-anchored","tree-sitter","ast","ast-tools","symbol-search","symbol-rename","refactoring"],"license":"Apache-2.0","_id":"@deevus/pi-wayfinder@0.2.0","maintainers":[{"name":"deevus","email":"simon@simonhartcher.com"}],"homepage":"https://github.com/deevus/pi-wayfinder#readme","bugs":{"url":"https://github.com/deevus/pi-wayfinder/issues"},"pi":{"extensions":["./src/index.ts"]},"dist":{"shasum":"0c86272081fcc1d6fddd0b596887769ea236d83f","tarball":"https://registry.npmjs.org/@deevus/pi-wayfinder/-/pi-wayfinder-0.2.0.tgz","fileCount":58,"integrity":"sha512-KfXdOrsVcqJFyGdo0gDkT6KZxpjneed9FViOVdRxO/RT4nBvL6IljogicFPB/MIgcEKx2rOOxIc/vb4Hd9ThCw==","signatures":[{"sig":"MEUCIQCN81AUHpgMCidVlShReExx3aPn3UErmmsbUUdwKcHFuQIgIrtgQiSSsB9HfY+xO4J6308HR4+ZtV9ksrwQ1wG0SGw=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":176556},"type":"module","gitHead":"ff5441ad02515ccc77c64b926843499d93babcc4","scripts":{"test":"vitest run","typecheck":"tsc --noEmit"},"_npmUser":{"name":"deevus","email":"simon@simonhartcher.com"},"repository":{"url":"git+https://github.com/deevus/pi-wayfinder.git","type":"git"},"_npmVersion":"11.10.1","description":"Structure-aware code navigation and anchor-stable editing tools for pi agents.","directories":{},"_nodeVersion":"25.7.0","dependencies":{"diff":"^7.0.0","web-tree-sitter":"^0.22.6","tree-sitter-wasms":"^0.1.13"},"_hasShrinkwrap":false,"devDependencies":{"vitest":"^2.0.0","typescript":"^5.0.0","@types/node":"20.x"},"peerDependencies":{"typebox":"*","@earendil-works/pi-ai":"*","@earendil-works/pi-tui":"*","@earendil-works/pi-coding-agent":"*"},"_npmOperationalInternal":{"tmp":"tmp/pi-wayfinder_0.2.0_1779002797252_0.5940537328846669","host":"s3://npm-registry-packages-npm-production"}},"0.2.1":{"name":"@deevus/pi-wayfinder","version":"0.2.1","keywords":["pi-package","wayfinder","dirac","coding-agent","code-navigation","code-editing","anchor-stable-editing","hash-anchored","tree-sitter","ast","ast-tools","symbol-search","symbol-rename","refactoring"],"license":"Apache-2.0","_id":"@deevus/pi-wayfinder@0.2.1","maintainers":[{"name":"deevus","email":"simon@simonhartcher.com"}],"homepage":"https://github.com/deevus/pi-wayfinder#readme","bugs":{"url":"https://github.com/deevus/pi-wayfinder/issues"},"pi":{"extensions":["./src/index.ts"]},"dist":{"shasum":"93a50af71391ad9eaae1f6a95af2eef14f4ad924","tarball":"https://registry.npmjs.org/@deevus/pi-wayfinder/-/pi-wayfinder-0.2.1.tgz","fileCount":58,"integrity":"sha512-/Km+aIM3/7tb8KA2/5TzHd23QhOyZ/5WvoQI5CvJhezRLVEXlq9pGhpoESjqX8zIOVaXQBk5lBmVyVWRlI4usg==","signatures":[{"sig":"MEQCIC/j5K0oAccM3NTr2dE9nxOAYz+770G7Q/tzaw9HwM1pAiB3WhbOrnGgw8swL8FaRzvsOfD8blgAVygxArPz3V+57A==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":176679},"type":"module","gitHead":"6c450cc8c42a4863ec9c8ff8a34a0ed4c817f7d2","scripts":{"test":"vitest run","typecheck":"tsc --noEmit"},"_npmUser":{"name":"deevus","email":"simon@simonhartcher.com"},"repository":{"url":"git+https://github.com/deevus/pi-wayfinder.git","type":"git"},"_npmVersion":"10.9.8","description":"Structure-aware code navigation and anchor-stable editing tools for pi agents.","directories":{},"_nodeVersion":"22.22.3","dependencies":{"diff":"^7.0.0","web-tree-sitter":"^0.22.6","tree-sitter-wasms":"^0.1.13"},"_hasShrinkwrap":false,"devDependencies":{"vitest":"^2.0.0","typescript":"^5.0.0","@types/node":"20.x"},"peerDependencies":{"typebox":"*","@earendil-works/pi-ai":"*","@earendil-works/pi-tui":"*","@earendil-works/pi-coding-agent":"*"},"_npmOperationalInternal":{"tmp":"tmp/pi-wayfinder_0.2.1_1779244784629_0.07841650286636859","host":"s3://npm-registry-packages-npm-production"}},"0.3.0":{"name":"@deevus/pi-wayfinder","version":"0.3.0","keywords":["pi-package","wayfinder","dirac","coding-agent","code-navigation","code-editing","anchor-stable-editing","hash-anchored","tree-sitter","ast","ast-tools","symbol-search","symbol-rename","refactoring"],"license":"Apache-2.0","_id":"@deevus/pi-wayfinder@0.3.0","maintainers":[{"name":"deevus","email":"simon@simonhartcher.com"}],"homepage":"https://github.com/deevus/pi-wayfinder#readme","bugs":{"url":"https://github.com/deevus/pi-wayfinder/issues"},"pi":{"extensions":["./src/index.ts"]},"dist":{"shasum":"79b745fafba477439b86cd9ebe00b66846316da2","tarball":"https://registry.npmjs.org/@deevus/pi-wayfinder/-/pi-wayfinder-0.3.0.tgz","fileCount":58,"integrity":"sha512-jrQyoZdrQP3nwB3r6ROJ1RWA7c4Magw8L4q3/UAS6JUYZkN82lXx7SGmJLOk5pFMWUvNnrO++5rHIjTFT7hmtA==","signatures":[{"sig":"MEUCIQD0GP3s7tQiaiN+omautzlHIC66dKNuyRQ4RP2q/GdjkAIgYqLg88lXv/hiGuhmujGB4RLtmox7Vt4ykt4k27eN8bo=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":179007},"type":"module","gitHead":"9051f50fdf5008206fa7e1ea54b91e7509f309bd","scripts":{"test":"vitest run","typecheck":"tsc --noEmit","test:agent":"uv run --with git+https://github.com/deevus/dokimasia pytest tests/agent -m agent_e2e"},"_npmUser":{"name":"deevus","email":"simon@simonhartcher.com"},"repository":{"url":"git+https://github.com/deevus/pi-wayfinder.git","type":"git"},"_npmVersion":"10.9.8","description":"Structure-aware code navigation and anchor-stable editing tools for pi agents.","directories":{},"_nodeVersion":"22.22.3","dependencies":{"diff":"^7.0.0","web-tree-sitter":"^0.22.6","tree-sitter-wasms":"^0.1.13"},"_hasShrinkwrap":false,"devDependencies":{"vitest":"^2.0.0","typescript":"^5.0.0","@types/node":"20.x"},"peerDependencies":{"typebox":"*","@earendil-works/pi-ai":"*","@earendil-works/pi-tui":"*","@earendil-works/pi-coding-agent":"*"},"_npmOperationalInternal":{"tmp":"tmp/pi-wayfinder_0.3.0_1779254294603_0.9857894946348782","host":"s3://npm-registry-packages-npm-production"}},"0.3.2":{"name":"@deevus/pi-wayfinder","version":"0.3.2","description":"Structure-aware code navigation and anchor-stable editing tools for pi agents.","type":"module","keywords":["pi-package","wayfinder","dirac","coding-agent","code-navigation","code-editing","anchor-stable-editing","hash-anchored","tree-sitter","ast","ast-tools","symbol-search","symbol-rename","refactoring"],"repository":{"type":"git","url":"git+https://github.com/deevus/pi-wayfinder.git"},"scripts":{"test":"vitest run","test:agent":"uv run --with git+https://github.com/deevus/dokimasia pytest tests/agent -m agent_e2e","typecheck":"tsc --noEmit"},"dependencies":{"diff":"^7.0.0","tree-sitter-wasms":"^0.1.13","web-tree-sitter":"^0.22.6"},"devDependencies":{"@types/node":"20.x","typescript":"^5.0.0","vitest":"^2.0.0"},"peerDependencies":{"@earendil-works/pi-coding-agent":"*","@earendil-works/pi-ai":"*","@earendil-works/pi-tui":"*","typebox":"*"},"pi":{"extensions":["./src/index.ts"]},"license":"Apache-2.0","_id":"@deevus/pi-wayfinder@0.3.2","gitHead":"2d098d6941f01cbb690bf0a396cd6de2c6b67ce7","bugs":{"url":"https://github.com/deevus/pi-wayfinder/issues"},"homepage":"https://github.com/deevus/pi-wayfinder#readme","_nodeVersion":"22.22.3","_npmVersion":"10.9.8","dist":{"integrity":"sha512-ewbAkAkrMgprAydKGkFZI99Zf6ToLkUNiLV86H92wP+8YOI2vdxAZ3vYSMTZ+jwHImduolH/YSbWeRk+2fYVGw==","shasum":"5b8c873a5b57c51c17a351dcb570fd382d2e5724","tarball":"https://registry.npmjs.org/@deevus/pi-wayfinder/-/pi-wayfinder-0.3.2.tgz","fileCount":58,"unpackedSize":178516,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIFTLmbDG4X3Lt3k5PFla6m/Gr/7w88CxrE2YjTUDiSVHAiAiJv5tHZJv5WUIg5G17LjbhsnLOCYxglFadf5zSyiQig=="}]},"_npmUser":{"name":"deevus","email":"simon@simonhartcher.com"},"directories":{},"maintainers":[{"name":"deevus","email":"simon@simonhartcher.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/pi-wayfinder_0.3.2_1781401972943_0.6353878134468933"},"_hasShrinkwrap":false}},"time":{"created":"2026-05-10T08:58:41.646Z","modified":"2026-06-14T01:52:53.170Z","0.1.0":"2026-05-10T08:58:41.919Z","0.1.1":"2026-05-15T08:32:12.158Z","0.2.0":"2026-05-17T07:26:37.420Z","0.2.1":"2026-05-20T02:39:44.821Z","0.3.0":"2026-05-20T05:18:14.783Z","0.3.2":"2026-06-14T01:52:53.082Z"},"bugs":{"url":"https://github.com/deevus/pi-wayfinder/issues"},"license":"Apache-2.0","homepage":"https://github.com/deevus/pi-wayfinder#readme","keywords":["pi-package","wayfinder","dirac","coding-agent","code-navigation","code-editing","anchor-stable-editing","hash-anchored","tree-sitter","ast","ast-tools","symbol-search","symbol-rename","refactoring"],"repository":{"type":"git","url":"git+https://github.com/deevus/pi-wayfinder.git"},"description":"Structure-aware code navigation and anchor-stable editing tools for pi agents.","maintainers":[{"name":"deevus","email":"simon@simonhartcher.com"}],"readme":"# pi-wayfinder\n\nStructure-aware code navigation and anchor-stable editing tools for pi agents.\n\nWayfinder helps agents keep code context focused with compact file skeletons, targeted function reads, stable anchored edits, whole-symbol replacement, and exact symbol search/rename.\n\n## Why context stays focused\n\nWayfinder gives agents precise source-code tools instead of forcing broad file reads and brittle line-number edits:\n\n- `get_file_skeleton` is the first-pass source exploration tool, returning a compact outline before broad reads.\n- `get_function` follows the skeleton and reads only the definitions needed for the task.\n- `read_file` supports stable anchors and narrow line ranges when skeleton/function output is insufficient.\n- `edit_file` batches precise edits across one or more files by anchor.\n- `replace_symbol` rewrites complete functions, methods, classes, interfaces, or exported const/arrow functions.\n- `find_symbol_references` and `rename_symbol` avoid manual grep-and-edit loops.\n\nAnchors add a small prefix to returned source lines, but they are intended to prevent repeated reads, failed edits, and correction turns.\n\n## Install\n\n```bash\npi install npm:@deevus/pi-wayfinder\n```\n\nFor local development:\n\n```bash\npi -e . --wayfinder-mode preferred\n```\n\n\n## Modes\n\n- `additive`: add Wayfinder tools without changing pi built-ins.\n- `preferred`: default; add Wayfinder tools and guide the model to prefer them for source-code reads and edits.\n- `replacement`: deactivate pi `edit` from the active toolset and use Wayfinder source-editing tools instead; keep built-in `read` for images, PDFs, and binary/non-source assets.\n\n## Built-in replacement\n\n`replacement` mode is a soft source-editing replacement: it removes pi `edit` from the active toolset and activates Wayfinder `read_file`, `edit_file`, and AST-aware tools. It intentionally keeps pi `read` active for images, PDFs, and binary/non-source assets. It does not override pi's built-in implementations. This is the safest idiomatic pi behavior.\n\nA future explicit `--wayfinder-override-builtins read_edit` mode can register tools named `read` and `edit`, but that is intentionally separate because overriding built-ins can surprise existing workflows.\n\nRun from a local checkout:\n\n```bash\npi -e . --wayfinder-mode preferred\npi -e . --wayfinder-mode replacement\n```\n\nInside pi:\n\n```txt\n/wayfinder additive\n/wayfinder preferred\n/wayfinder replacement\n```\n\nSlash-command mode changes are persisted in the current pi session and restored on reload/resume. An explicit `--wayfinder-mode ...` flag takes precedence over the persisted session mode.\n\n## Reading files\n\n`read_file` accepts global `start_line` / `end_line` for applying the same line range to every requested file. For mixed reads where only one file needs a range, put the range on that path instead:\n\n```json\n{ \"paths\": [\"PROJECTS/ROLLER/3d.h\", \"build.zig:150-230\"] }\n```\n\n\n## Agent acceptance tests\n\nWayfinder includes an opt-in Dokimasia acceptance test that runs pi and asserts the model uses `get_file_skeleton` before source reads, then `get_function` for targeted implementation context:\n\n```bash\nnpm run test:agent\n```\n\nThis test invokes a real agent/model, so it is intentionally separate from `npm test` and requires working pi credentials.\n\n## Smoke tests\n\n```bash\npi -e . --wayfinder-mode additive -p \"Use read_file on README.md and summarize the first 20 lines.\"\npi -e . --wayfinder-mode replacement -p \"Use read_file on README.md and report whether Wayfinder mentions anchor-stable editing.\"\n```\n\n## Tree-sitter AST tools\n\n\nFor source exploration, use `get_file_skeleton` first to understand the available symbols, then `get_function` for the relevant implementation. Use `read_file` for narrow line ranges, non-symbol context, small/config files, or when AST output is insufficient.\n\n`get_file_skeleton` and `get_function` use tree-sitter parsing for supported source files. Supported extensions include `bash`, `sh`, `zsh`, `ts`, `tsx`, `js`, `jsx`, `py`, `rs`, `go`, `c`, `h`, `cpp`, `cc`, `cxx`, `hpp`, `hh`, `hxx`, `cs`, `css`, `el`, `elisp`, `ex`, `exs`, `html`, `htm`, `rb`, `java`, `json`, `php`, `swift`, `kt`, `kts`, `lua`, `m`, `mm`, `ml`, `mli`, `res`, `resi`, `scala`, `sc`, `sol`, `rdl`, `tla`, `toml`, `vue`, and `zig`.\n\nFor unsupported languages or parser load failures, the tools fall back to the conservative regex MVP for common JavaScript, TypeScript, and Python top-level definitions.\n\nSome bundled tree-sitter WASMs are intentionally not enabled yet because they are incompatible with the current `web-tree-sitter` runtime or fail to parse reliably in Node: Dart, Elm, QL, and YAML.\n\n## Symbol replacement\n\n`replace_symbol` replaces complete AST symbols by name. Use it when replacing an entire function, method, class, interface, or exported const/arrow function.\n\n```json\n{\n  \"replacements\": [\n    {\n      \"path\": \"src/sample.ts\",\n      \"symbol\": \"Service.run\",\n      \"type\": \"method\",\n      \"text\": \"  run() {\\n    return 2;\\n  }\"\n    }\n  ]\n}\n```\n\nThe tool resolves symbols with tree-sitter, rejects overlapping replacements in the same file, applies accepted replacements from bottom to top, strips hash anchors from replacement text, and preserves the file's existing line-ending style where practical.\n\nThe `replacements` array is required. Unsupported languages, parser failures, and missing symbols are reported as errors; `replace_symbol` does not fall back to regex matching.\n\n## Finding symbol references\n\n`find_symbol_references` finds exact tree-sitter definitions and references for one or more symbols across files or directories.\n\n```json\n{\n  \"paths\": [\"src/\", \"test/\"],\n  \"symbols\": [\"calculateTotal\", \"UserAccount\"],\n  \"find_type\": \"both\"\n}\n```\n\n`find_type` can be `definition`, `reference`, or `both` (default). Results are grouped by file and include stable hash anchors for each matching line.\n\n## Renaming symbols\n\n`rename_symbol` renames all exact tree-sitter definitions and references of one symbol inside the requested files or directories.\n\n```json\n{\n  \"paths\": [\"src/\", \"test/\"],\n  \"existing_symbol\": \"calculateTotal\",\n  \"new_symbol\": \"calculateGrandTotal\"\n}\n```\n\nThe tool uses an in-memory session cache for scanned files, invalidated by file `mtime` and size. It does not create a persistent symbol index. Before writing, it prepares all affected files and verifies every indexed location still matches the existing symbol; if validation fails, no file is written.\n\n## Interactive rendering\n\nIn pi's interactive TUI, Wayfinder tools render with pi-native readable output:\n\n- read-like tools hide `WayX│` anchor prefixes visually while preserving anchors in model-facing tool content;\n- `edit_file`, `replace_symbol`, and `rename_symbol` render unified diffs using pi's diff renderer;\n- print/JSON/API outputs keep the same anchored text contract used by the agent.\n\nThis means humans see clean code and diffs, while the agent still receives stable anchors for follow-up edits.\n","readmeFilename":"README.md"}