Skip to content

feat: implement v0.1.0 native explore tool and runner - #8

Merged
AllenMuu merged 7 commits into
mainfrom
feat/v0.1.0-native-explore
Aug 26, 2026
Merged

feat: implement v0.1.0 native explore tool and runner#8
AllenMuu merged 7 commits into
mainfrom
feat/v0.1.0-native-explore

Conversation

@AllenMuu

Copy link
Copy Markdown
Owner

Summary

Implements pi-codegraph v0.1.0 Native Explore according to docs/specs/2026-08-26-v0.1-native-explore.md and docs/architecture.md.

Closes #1

User-Facing Changes

  • Pi-Native Tool: Registers codegraph_explore({ query }) for natural-language structural code understanding and symbol relationship exploration.
  • Active Workspace Scoping: Derives execution working directory strictly from active Pi session (cwd); no model-supplied arbitrary path access.
  • Safe Process Invocation: Uses child_process.spawn argument arrays; never performs shell string interpolation.
  • Preflight Diagnostics: Validates .codegraph/ presence and codegraph binary availability (with Windows codegraph.cmd fallback) before running exploration.
  • Process Guardrails: Enforces a 30-second timeout (CODEGRAPH_TIMEOUT), propagates AbortSignal cancellation, bounds stdout to 50 KB / 2,000 lines (with visible truncation marker), and bounds failure stderr to 4 KB (CODEGRAPH_COMMAND_FAILED).
  • Prompt Guidance: Injects native Pi guidelines instructing the agent when to use CodeGraph vs built-in grep/read tools.
  • Standalone Example: Provides copyable single-file extension in examples/pi-codegraph.ts.
  • Zero Telemetry / Zero Network: Makes no extension-originated network requests and records no telemetry.

Tests Run

  • npm run lint: clean TypeScript type-check with zero errors.
  • npm test: 24 tests across 9 suites passing (argument preservation, shell metacharacter safety, unicode, timeout, abort, output bounds, preflight detection, duplicate registration, standalone example, and fixed fixture).
  • npm run build: clean ESM and declaration build output in dist/.

CI & Platform Support

  • GitHub Actions workflow testing Node 22 on macOS, Linux, and Windows.

@AllenMuu
AllenMuu merged commit a889b9a into main Aug 26, 2026
3 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Spec: v0.1.0 Native Explore

1 participant