Spec: v0.1.0 Native Explore

[AllenMuu]

v0.1.0 Native Explore Specification

Problem Statement

Pi users need reliable structural code exploration in the active workspace without introducing an MCP client, a server lifecycle, arbitrary filesystem access, or a dependency on CodeGraph upstream accepting Pi-specific work. They need clear diagnostics when CodeGraph is unavailable or the workspace has not been indexed, and they need results that do not overwhelm the agent context.

Solution

Deliver pi-codegraph as an npm-distributed, Pi-native extension with a copyable single-file example. It provides one LLM-callable tool, codegraph_explore, which submits an Explore request to the local CodeGraph CLI in the active workspace only.

The extension uses an argument-array subprocess invocation, checks for the CodeGraph index and executable, records CLI version diagnostics without version gating, respects cancellation, enforces a 30-second timeout, and returns bounded useful output. It is supported on Node.js 22+ for macOS and Linux, with Windows experimental and using codegraph.cmd fallback. The extension itself sends no network traffic and records no telemetry.

User Stories

1. As a Pi user, I want to install pi-codegraph from npm, so that I can use a versioned and updatable native extension.
2. As a Pi user, I want a copyable single-file extension example, so that I can inspect and trial the integration locally.
3. As a Pi user, I want to ask a structural question in natural language, so that I can understand symbols, relationships, implementations, and call paths without composing CLI syntax.
4. As a Pi user, I want exploration to operate only in my active workspace, so that a model cannot inspect another project by supplying a path.
5. As a Pi user, I want Pi-native tool rendering and guidance, so that CodeGraph exploration fits naturally into my Pi session.
6. As a Pi user, I want the tool used for architecture and relationship questions rather than trivial reads or exact text searches, so that small tasks do not incur unnecessary process cost.
7. As a Pi user, I want a clear error when CodeGraph is absent from my environment, so that I know to install or expose the CLI on PATH.
8. As a Pi user, I want a clear error when my active workspace has no CodeGraph index, so that I can choose to run CodeGraph initialization myself.
9. As a Pi user, I want the extension never to initialize, synchronize, or otherwise mutate my CodeGraph index automatically, so that indexing remains my explicit action.
10. As a Pi user, I want my natural-language Explore request passed safely as data, so that quotes, metacharacters, Unicode, and whitespace never become shell syntax.
11. As a Pi user, I want cancellation to stop the running CLI process, so that I can regain control of a Pi session promptly.
12. As a Pi user, I want an unresponsive CLI to fail after 30 seconds with an actionable error, so that my session cannot wait indefinitely.
13. As a Pi user, I want results limited to 50 KB or 2,000 lines and visibly marked when truncated, so that CodeGraph output remains useful without exhausting model context.
14. As a Pi user, I want a CLI failure to provide a stable error code, remediation, and a bounded stderr tail, so that I can diagnose problems without receiving raw stacks or unbounded output.
15. As a Pi user, I want CodeGraph version recorded as diagnostic metadata without premature version rejection, so that compatibility problems can be investigated from real evidence.
16. As a Windows user, I want the extension to fall back to codegraph.cmd, so that known launcher differences do not make the integration unusable.
17. As a user with both global and project-level installations, I want duplicate registration to leave the first active tool available, so that my Pi session does not fail because of a duplicate name.
18. As a privacy-conscious user, I want pi-codegraph itself to make no network requests and collect no telemetry, so that its data boundary is straightforward to audit.
19. As a contributor, I want deterministic tests around the public tool contract, so that process behavior is verified without depending on a developer's arbitrary repository.
20. As a contributor, I want a small fixed CodeGraph fixture in CI, so that drift in the public CLI contract is detected before release.
21. As a maintainer, I want pi-codegraph to remain independently released and tested even if CodeGraph develops an upstream Pi integration, so that this project's viability does not depend on another repository's roadmap.

Implementation Decisions

• The only v0.1 LLM-callable capability is codegraph_explore with one natural-language Explore request field. It does not accept a workspace path or executable path.
• The active workspace is derived from the Pi extension context and is the sole subprocess working directory.
• The extension uses Pi native tool registration rather than an MCP adapter or client.
• The public CodeGraph CLI is the only CodeGraph integration boundary. The extension does not import CodeGraph internals or access the CodeGraph index directly.
• The CLI runner is a reusable internal boundary responsible for launch, output collection, cancellation, timeout, termination, output limits, executable discovery, and process-error normalization.
• Invocation uses a command and argument array, never a shell-interpolated command string.
• The runner checks for an existing CodeGraph index but does not assess index freshness. v0.1 treats the existing index as authoritative and does not run initialization or synchronization.
• The runner records CodeGraph CLI version diagnostics without enforcing a semver range in v0.1.
• On Windows, executable discovery tries codegraph before codegraph.cmd. Windows support is experimental in v0.1.
• Tool output is limited to 50 KB or 2,000 lines, whichever occurs first, and identifies truncation. A non-zero exit raises a normalized Pi tool error with a stable code, remediation, and at most the final 4 KB of stderr.
• The runner honors Pi cancellation and terminates an unfinished process after 30 seconds with CODEGRAPH_TIMEOUT.
• If multiple installations register the same tool, the first registration remains active and later duplicates are skipped. Documentation warns users not to mix versions.
• The npm package requires Node.js 22 or later and is the supported release artifact; a single-file example is also supplied for local trial and audit.
• pi-codegraph performs no extension-originated network request and collects no telemetry.
• CodeGraph upstream work is a compatibility reference only. pi-codegraph remains independently maintained and does not wait for, migrate to, or require upstream Pi support.

Testing Decisions

• The primary and highest test seam is the observable codegraph_explore tool execution contract. Tests assert its returned result or normalized tool error, not internal helper calls or implementation structure.
• A controlled fake CodeGraph executable drives deterministic tests for argument preservation, active-workspace selection, missing executable, absent index, non-zero exit, stderr bounding, cancellation, timeout, output truncation, duplicate registration, and Windows executable fallback.
• A small, fixed, real CodeGraph fixture suite runs in CI through that same public tool seam to detect CLI-contract incompatibility.
• CI tests Node.js 22 and later supported LTS lines on macOS and Linux. Windows runs the experimental launcher compatibility coverage.
• There is no existing implementation or test suite in the repository; this specification establishes the testing baseline rather than extending prior art.

Out of Scope

• An MCP client, adapter, or CodeGraph MCP server lifecycle.
• Automatic CodeGraph installation, initialization, synchronization, rebuilding, watching, caching, daemon management, or AGENTS.md modification.
• Direct CodeGraph index/database access or CodeGraph internal module imports.
• Model-controlled workspace or executable-path selection.
• Multiple CodeGraph tools, semantic result rewriting, automatic grep fallback, query caching, background synchronization, or file watching.
• Index freshness checks before every Explore request.
• Mandatory CodeGraph version ranges in v0.1.
• Extension telemetry or extension-originated network communication.

Further Notes

• The project uses the terms Active workspace, CodeGraph index, Explore request, and Pi extension as defined by the repository glossary.
• The native CLI boundary and distribution/runtime contract are governed by the accepted architecture decisions.
• The project is MIT licensed.

[AllenMuu]

v0.1.0 Implementation Complete

All 6 sub-issues have been implemented, verified via TDD, and closed:

• Project Skeleton & Test Harness Baseline #2 Project Skeleton & Test Harness Baseline
• Workspace & CodeGraph Environment Preflight Detection #3 Workspace & CodeGraph Environment Preflight Detection
• Safe Subprocess Execution Runner #4 Safe Subprocess Execution Runner
• codegraph_explore Native Pi Tool & Registration Layer #5 codegraph_explore Native Pi Tool & Registration Layer
• Copyable Single-File Example & Documentation #6 Copyable Single-File Example & Documentation
• Fixed CodeGraph Fixture CI Suite & Cross-Platform Verification #7 Fixed CodeGraph Fixture CI Suite & Cross-Platform Verification

The full test suite (24 unit and fixture integration tests) passes cleanly across all modules.

[AllenMuu]

Resolved and closed by PR #8.