@wwjd/pi-graphify 0.1.0

package/AGENTS.md

@@ -0,0 +1,23 @@
+---
+name: pi-graphify
+description: Agent context for working on pi-graphify
+---
+
+# pi-graphify
+
+A Pi extension that integrates [Graphify](https://github.com/Graphify-Labs/graphify) into Pi sessions.
+
+## Key references
+
+- Project standards: [docs/STANDARDS.md](docs/STANDARDS.md)
+- Design: [docs/DESIGN.md](docs/DESIGN.md)
+- Architecture: [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)
+- Ecosystem: [docs/ECOSYSTEM.md](docs/ECOSYSTEM.md)
+- Versioning: [docs/VERSIONING.md](docs/VERSIONING.md)
+- Release: [RELEASE.md](RELEASE.md)
+
+## Quick verification
+
+```bash
+npm run typecheck && npm run lint
+```

package/CHANGELOG.md

@@ -0,0 +1,16 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## 0.1.0 (2026-07-11)
+
+### Added
+
+- Initial project setup from the official pi package template.
+- Scaffolded extension, skill, prompt template, and theme for graphify.
+- add graphify_status tool and /graphify-status command

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,94 @@
+# pi-graphify
+
+A production-quality [pi](https://pi.dev) extension for [Graphify](https://github.com/Graphify-Labs/graphify).
+
+This extension brings Graphify knowledge graph capabilities into your Pi sessions, making it easy to query, explore, and update codebase graphs without leaving the agent.
+
+> ⚠️ **Work in progress** — this package is in early development. The public API, tools, and commands will evolve as the extension matures toward a stable 1.0 release.
+
+## Quick Start
+
+```bash
+# Install from a local path (during development)
+pi install .
+
+# Or run ephemerally without installing
+pi -e .
+
+# Type check
+npm run typecheck
+
+# Lint
+npm run lint
+```
+
+## What's Included
+
+```
+pi-graphify/
+├── extensions/
+│   └── index.ts          # Extension entry point (tools, commands, events)
+├── src/                   # Core implementation
+├── package.json           # Pi manifest + npm config
+├── tsconfig.json          # TypeScript config (type checking only)
+├── biome.json             # Linter/formatter config
+├── .gitignore
+├── LICENSE
+├── CHANGELOG.md
+├── RELEASE.md             # Versioning and release standards
+├── AGENTS.md              # Agent context / development conventions
+└── README.md
+```
+
+## Package Structure
+
+### Extensions (`extensions/`)
+
+TypeScript modules that extend pi's behavior with custom tools, slash commands, and event handlers.
+
+### Source (`src/`)
+
+Pi-agnostic implementation logic. The `extensions/` layer imports from here and registers everything with Pi.
+
+## Development
+
+### Requirements
+
+- Node.js 22+
+- npm 10+
+- pi CLI
+
+### Scripts
+
+| Command | Description |
+|---------|-------------|
+| `npm run typecheck` | TypeScript type checking (`tsc --noEmit`) |
+| `npm run lint` | Check lint + formatting (`biome check`) |
+| `npm run lint:fix` | Auto-fix lint + formatting issues |
+| `npm run format` | Format code only |
+
+### Testing the package
+
+```bash
+# Run ephemerally with no other extensions loaded
+pi -ne -e . --no-session
+
+# Test a specific tool in print mode
+pi -ne -e . --no-session -p "List the available tools."
+```
+
+## Publishing
+
+This package is intended for publication to npm so it can be listed on [pi.dev/packages](https://pi.dev/packages). CI/CD workflows for release automation are included under `.github/workflows/`.
+
+See `RELEASE.md` for versioning and release standards.
+
+Before publishing, update:
+
+- `package.json` author and repository fields
+- `README.md` with final usage instructions
+- `CHANGELOG.md` with release notes
+
+## License
+
+MIT

package/RELEASE.md

@@ -0,0 +1,149 @@
+# Release Standards
+
+This document defines how `pi-graphify` is versioned and released.
+
+---
+
+## Versioning
+
+`pi-graphify` follows [Semantic Versioning 2.0.0](https://semver.org/):
+
+| Position | Name | Bumped when |
+|---|---|---|
+| `MAJOR` | Breaking release | A public tool, command, config option, or behavior changes in a way that could break existing users. |
+| `MINOR` | Feature release | New tools, commands, or backward-compatible features are added. |
+| `PATCH` | Fix release | Bugs are fixed, docs are corrected, or internal behavior improves without affecting the public API. |
+
+Pre-1.0 policy: while the package is at `0.x`, the API is considered unstable. Minor releases may introduce substantial changes. Patch releases are safe to apply.
+
+---
+
+## What triggers each version bump
+
+### MAJOR (`x.0.0`)
+
+- Removing a registered tool or command.
+- Renaming a tool, command, or parameter.
+- Changing the default behavior of a tool or command in a way that breaks existing workflows.
+- Changing the required config schema or environment variables.
+
+### MINOR (`0.x.0`)
+
+- Adding a new tool (e.g., `graphify_query`).
+- Adding a new slash command (e.g., `/graphify-watch`).
+- Adding new optional parameters to existing tools/commands.
+- Adding new config options with safe defaults.
+- Adding support for new Graphify CLI features.
+
+### PATCH (`0.0.x`)
+
+- Fixing a bug in a tool or command.
+- Improving error messages or output formatting.
+- Updating documentation.
+- Updating dependencies that do not change public behavior.
+- Internal refactoring with no user-visible change.
+
+---
+
+## Commit conventions
+
+All commits must use [Conventional Commits](https://www.conventionalcommits.org/).
+
+Allowed prefixes:
+
+| Prefix | Use for |
+|---|---|
+| `feat:` | New user-facing feature or tool |
+| `fix:` | Bug fix |
+| `docs:` | Documentation-only changes |
+| `refactor:` | Code change that neither fixes a bug nor adds a feature |
+| `test:` | Adding or correcting tests |
+| `chore:` | Maintenance, dependency updates, cleanup |
+| `ci:` | Changes to CI/CD configuration |
+
+For breaking changes, add `BREAKING CHANGE:` in the commit body or use `!` after the prefix:
+
+```
+feat!: remove graphify_status tool in favor of graphify_info
+```
+
+---
+
+## Release workflow
+
+Releases are automated with [release-please](https://github.com/googleapis/release-please) via `.github/workflows/release.yml`.
+
+### How it works
+
+1. **You commit to `main`** using conventional commits.
+2. **release-please scans the commit history** and opens a Release PR titled something like `chore(main): release 0.2.0`.
+3. **The Release PR contains:**
+   - An updated `CHANGELOG.md`.
+   - A version bump in `package.json` and `package-lock.json`.
+4. **You review and merge the Release PR.**
+5. **release-please creates:**
+   - A Git tag (e.g., `v0.2.0`).
+   - A GitHub Release with auto-generated notes.
+6. **The `publish` job runs** and publishes the package to npm with provenance.
+
+### Manual steps required
+
+- Ensure `NPM_TOKEN` is configured as a repository secret in GitHub.
+- Ensure GitHub Actions has permission to create pull requests.
+- Review the Release PR before merging.
+
+### No manual version bumps
+
+Do not manually edit `version` in `package.json`. release-please handles this. The only exception is the very first `0.1.0`, which is already set.
+
+---
+
+## Branching strategy
+
+Because this is a solo project, keep the branching model minimal:
+
+- **`main`** is the only long-lived branch.
+- Commit directly to `main` for small changes.
+- Optional: use short-lived feature branches (e.g., `feat/query-tool`) if you want cleaner history, but they are not required.
+- No release branches, no sub-branches, no cherry-pick branches.
+- Hotfixes are committed to `main` and release-please cuts a new patch release.
+
+---
+
+## Git tags
+
+Git tags are created automatically by release-please in the format `v0.2.0`. Do not create tags manually.
+
+---
+
+## npm provenance
+
+The publish workflow uses `npm publish --provenance`, which attaches a signed attestation to the package on npm. This requires:
+
+- The `publish` job runs in GitHub Actions.
+- The workflow has `id-token: write` permission.
+- The package is published with `--access public`.
+
+---
+
+## Pre-release checklist
+
+Before merging a Release PR, verify:
+
+- [ ] `CHANGELOG.md` accurately describes the release.
+- [ ] The version bump is correct (patch/minor/major).
+- [ ] `npm run typecheck` passes on `main`.
+- [ ] `npm run lint` passes on `main`.
+- [ ] `NPM_TOKEN` is available.
+
+---
+
+## Emergency fixes
+
+If a release is broken and needs an immediate fix:
+
+1. Commit the fix to `main` with `fix: <description>`.
+2. release-please will open a new Release PR with a patch bump.
+3. Merge it to publish the fix.
+
+Do not unpublish npm versions. Prefer publishing a patch release over unpublishing.

package/docs/ARCHITECTURE.md

@@ -0,0 +1,388 @@
+# Architecture Document: pi-graphify
+
+This document describes the internal architecture of `pi-graphify`. It is intended for developers who want to understand or contribute to the extension.
+
+---
+
+## Component overview
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                        Pi Agent                             │
+└─────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────┐
+│                   Extension Entry Point                     │
+│                  (extensions/index.ts)                        │
+│  ┌──────────────┐  ┌──────────────┐  ┌──────────────────┐  │
+│  │ Tool         │  │ Command      │  │ Event handlers   │  │
+│  │ registration │  │ registration │  │ (session, model) │  │
+│  └──────────────┘  └──────────────┘  └──────────────────┘  │
+└─────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────┐
+│                      Coordinator                            │
+│                  (src/coordinator.ts)                         │
+│  ┌──────────────┐  ┌──────────────┐  ┌──────────────────┐  │
+│  │ Backend      │  │ Version      │  │ State manager    │  │
+│  │ selector     │  │ manager      │  │                  │  │
+│  └──────────────┘  └──────────────┘  └──────────────────┘  │
+└─────────────────────────────────────────────────────────────┘
+                              │
+              ┌───────────────┴───────────────┐
+              ▼                               ▼
+┌────────────────────────────┐    ┌────────────────────────────┐
+│       CliBackend           │    │        McpBackend          │
+│    (src/backends/cli.ts)   │    │   (src/backends/mcp.ts)    │
+│  Shells out to `graphify`  │    │ Spawns `graphify --mcp`    │
+│  via execFile              │    │ and speaks JSON-RPC        │
+└────────────────────────────┘    └────────────────────────────┘
+```
+
+---
+
+## Backend abstraction
+
+All Graphify operations are abstracted behind a `GraphifyBackend` interface. This allows the rest of the extension to be backend-agnostic.
+
+```typescript
+export interface GraphifyBackend {
+  readonly type: 'cli' | 'mcp';
+  readonly version: string | null;
+  readonly capabilities: GraphifyCapabilities;
+
+  status(cwd: string): Promise<GraphStatusResult>;
+  build(options: BuildOptions): Promise<GraphifyResult>;
+  query(options: QueryOptions): Promise<GraphifyResult>;
+  path(options: PathOptions): Promise<GraphifyResult>;
+  explain(options: ExplainOptions): Promise<GraphifyResult>;
+  affected(options: AffectedOptions): Promise<GraphifyResult>;
+  add(options: AddOptions): Promise<GraphifyResult>;
+  watch(options: WatchOptions): Promise<GraphifyResult>;
+  reflect(options: ReflectOptions): Promise<GraphifyResult>;
+
+  close?(): Promise<void>;
+}
+```
+
+### Capabilities
+
+```typescript
+export interface GraphifyCapabilities {
+  query: boolean;
+  path: boolean;
+  explain: boolean;
+  affected: boolean;
+  add: boolean;
+  watch: boolean;
+  reflect: boolean;
+  mcp: boolean;
+  directedGraph: boolean;
+  incrementalUpdate: boolean;
+  semanticExtraction: boolean;
+}
+```
+
+Capabilities are determined by:
+1. Detected Graphify version.
+2. Whether the backend is CLI or MCP.
+3. A feature map that maps version ranges to supported features.
+
+### Backend selector
+
+The coordinator chooses the backend in this order:
+
+1. **MCP if explicitly enabled** (`backend: 'mcp'` in config) and available.
+2. **MCP if auto-detected** (`backend: 'auto'`) and the MCP server starts successfully.
+3. **CLI** as the universal fallback.
+
+The CLI backend is always safe to attempt because Graphify is required to be installed. The MCP backend is preferred when it works because it provides typed, structured responses and avoids spawning a process per call.
+
+---
+
+## Backend implementations
+
+### CliBackend
+
+Responsibilities:
+- Resolve the Graphify executable path.
+- Execute `graphify <command>` with argument arrays via `execFile`.
+- Parse stdout/stderr into a normalized `GraphifyResult`.
+- Enforce timeouts.
+- Handle version detection via `graphify --version`.
+
+Security:
+- Never construct shell strings.
+- Validate all paths before passing them.
+- Respect `timeout` to prevent hung processes.
+
+### McpBackend
+
+Responsibilities:
+- Spawn `graphify --mcp` as a long-lived stdio process per session.
+- Maintain a JSON-RPC client over stdin/stdout.
+- Map Pi tool calls to MCP tool invocations.
+- Cache the graph context so the MCP server does not reload the graph on every call.
+- Close the process on `session_shutdown`.
+
+Fallback:
+- If the MCP process fails to start or crashes, the coordinator falls back to `CliBackend` and logs the reason.
+
+---
+
+## Coordinator
+
+The coordinator is the single entry point for all Graphify operations. It:
+
+1. Loads configuration.
+2. Detects or selects the backend.
+3. Checks the installed Graphify version against the supported range.
+4. Builds a capability map.
+5. Routes tool/command requests to the backend.
+6. Normalizes backend results into a common format.
+7. Handles errors and converts them into user-friendly messages.
+
+```typescript
+export class GraphifyCoordinator {
+  constructor(config: GraphifyConfig, backend: GraphifyBackend);
+  
+  initialize(): Promise<void>;
+  getStatus(): Promise<SystemStatus>;
+  runOperation(name: string, options: unknown): Promise<GraphifyResult>;
+  supports(feature: keyof GraphifyCapabilities): boolean;
+  close(): Promise<void>;
+}
+```
+
+---
+
+## Version manager
+
+The version manager is responsible for detecting the installed Graphify version and determining what features are available.
+
+```typescript
+export interface GraphifyVersionInfo {
+  version: string | null;
+  installationMethod: 'uv' | 'pipx' | 'pip' | 'system' | 'unknown';
+  isSupported: boolean;
+  isRecommended: boolean;
+  minSupported: string;
+  recommended: string;
+  warnings: string[];
+}
+```
+
+It is used by:
+- The coordinator to disable unsupported features.
+- The `graphify_version` tool to report compatibility.
+- The `session_start` handler to notify the user of issues.
+
+---
+
+## State manager
+
+The state manager holds per-session runtime state. It does not persist across sessions; it is rebuilt on `session_start`.
+
+```typescript
+export interface GraphifyState {
+  cwd: string;
+  graphPath: string | null;
+  graphExists: boolean;
+  graphMtime: number | null;
+  backendType: 'cli' | 'mcp';
+  graphifyVersion: string | null;
+  capabilities: GraphifyCapabilities;
+  watcherActive: boolean;
+  lastError: string | null;
+}
+```
+
+This state is used by:
+- Event handlers to decide whether to inject hints.
+- Tools to check prerequisites quickly.
+- Commands to report status.
+
+---
+
+## Watcher manager
+
+The watcher manager watches source files and triggers incremental rebuilds.
+
+Responsibilities:
+- Use `chokidar` to watch the project root.
+- Ignore `node_modules/`, `.git/`, `graphify-out/`, and other non-source directories.
+- Debounce change events.
+- Run `graphify --update` with `codeOnly: true` by default.
+- Never run full semantic rebuilds automatically.
+- Stop cleanly on `session_shutdown`.
+
+```typescript
+export interface WatcherOptions {
+  root: string;
+  debounceMs: number;
+  ignored: string[];
+  codeOnly: boolean;
+}
+```
+
+---
+
+## Tool/command mapping
+
+Each tool has a corresponding command, but the implementation is shared.
+
+```typescript
+// src/tools/query.ts
+export function registerQueryTool(pi: ExtensionAPI, coordinator: GraphifyCoordinator) {
+  pi.registerTool({
+    name: 'graphify_query',
+    // ...
+    execute: async (_id, params, _signal, _onUpdate, ctx) => {
+      return coordinator.runOperation('query', { ...params, cwd: ctx.cwd });
+    },
+  });
+}
+
+// src/commands/query.ts
+export function registerQueryCommand(pi: ExtensionAPI, coordinator: GraphifyCoordinator) {
+  pi.registerCommand('graphify-query', {
+    handler: async (args, ctx) => {
+      const result = await coordinator.runOperation('query', { question: args, cwd: ctx.cwd });
+      ctx.ui.notify(result.stdout.slice(0, 200), 'info');
+    },
+  });
+}
+```
+
+This ensures tools and commands behave identically and reduces duplication.
+
+---
+
+## Error normalization
+
+All backends return a `GraphifyResult`:
+
+```typescript
+export interface GraphifyResult {
+  stdout: string;
+  stderr: string;
+  exitCode: number;
+  durationMs: number;
+  backend: 'cli' | 'mcp';
+  feature: string;
+}
+```
+
+The coordinator converts backend errors into extension-level errors:
+
+```typescript
+export class GraphifyError extends Error {
+  readonly code: 'MISSING' | 'VERSION' | 'BUILD' | 'QUERY' | 'TIMEOUT' | 'MCP' | 'UNKNOWN';
+  readonly details: Record<string, unknown>;
+  readonly userMessage: string;
+}
+```
+
+This allows tools and UI to present consistent messages without knowing backend specifics.
+
+---
+
+## Configuration loading
+
+Configuration is loaded in this order (later overrides earlier):
+
+1. Default config (`src/config.ts`).
+2. Global config (`~/.pi/agent/pi-graphify/config.json`).
+3. Project-local config (`.pi/pi-graphify.json`) if project is trusted.
+
+```typescript
+export interface GraphifyConfig {
+  backend: 'auto' | 'cli' | 'mcp';
+  autoHint: boolean;
+  autoWatch: boolean;
+  watchDebounceMs: number;
+  buildTimeoutMs: number;
+  queryTimeoutMs: number;
+  shortTimeoutMs: number;
+  staleThresholdHours: number;
+  codeOnlyUpdates: boolean;
+  interceptReads: boolean;
+  graphifyPath?: string;
+  mcpTimeoutMs: number;
+}
+```
+
+---
+
+## Integration hooks
+
+`pi-graphify` is designed so that third-party integrations are optional, easy to add, and easy to build. The core extension works without any integrations. When another extension is available, `pi-graphify` can detect it and wire itself in through well-defined hooks.
+
+### Hook interface
+
+```typescript
+export interface GraphifyIntegration {
+  readonly name: string;
+  readonly priority: number;
+  isAvailable(pi: ExtensionAPI): boolean | Promise<boolean>;
+  onGraphBuilt?(result: GraphifyResult): void | Promise<void>;
+  onQueryResult?(result: GraphifyResult, question: string): void | Promise<void>;
+  onLesson?(lesson: GraphifyLesson): void | Promise<void>;
+}
+
+export interface GraphifyLesson {
+  kind: 'insight' | 'correction' | 'dead_end' | 'preference';
+  summary: string;
+  sourceNodes: string[];
+  query?: string;
+}
+```
+
+### How integrations are registered
+
+Third-party Pi extensions register themselves by importing a small registration helper from `pi-graphify`:
+
+```typescript
+import { registerGraphifyIntegration } from 'pi-graphify/integrations';
+
+registerGraphifyIntegration({
+  name: 'pi-hermes-memory',
+  priority: 100,
+  isAvailable: (pi) => pi.getAllTools().some((t) => t.name === 'memory'),
+  onLesson: async (lesson) => {
+    // Save a durable memory entry
+  },
+});
+```
+
+If no integrations are registered, the extension functions normally. This keeps the core lean and avoids hard dependencies.
+
+### Built-in integration stubs
+
+The extension ships with no built-in third-party integrations. It may include example adapters in a separate `examples/integrations/` directory to show how to build them.
+
+### Future integration candidates
+
+- `pi-hermes-memory`: save graph-derived lessons as memory entries.
+- `pi-fallow`: cross-reference dead-code findings with graph communities.
+- Custom provider extensions: route semantic extraction through the user’s configured provider.
+
+These are explicitly out of scope for the initial implementation but are supported by the hook design.
+
+---
+
+## Module boundaries
+
+- `extensions/` — Only Pi registration code. No business logic.
+- `src/coordinator.ts` — The only place backend selection happens.
+- `src/backends/` — Backend-specific code. No Pi imports.
+- `src/tools/` — Tool definitions. Each tool calls the coordinator.
+- `src/commands/` — Command definitions. Each command calls the coordinator.
+- `src/config.ts` — Pure config loading. No Pi imports.
+- `src/state.ts` — Session state.
+- `src/watcher.ts` — File watcher.
+- `src/version.ts` — Version detection and compatibility.
+
+This separation makes the core logic testable without loading Pi.