@wwjd/pi-graphify 0.1.0 → 0.3.0

package/CHANGELOG.md

@@ -5,6 +5,33 @@ 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).
 
+## [0.3.0](https://github.com/WianVDM/pi-graphify/compare/pi-graphify-v0.2.0...pi-graphify-v0.3.0) (2026-07-12)
+
+
+### Features
+
+* **tools:** add build, query, path, explain, affected, and version tools ([5b8cb07](https://github.com/WianVDM/pi-graphify/commit/5b8cb0730f7c766dd00f40149e7abb6b1fce64fa))
+* **tools:** add shared tool types and formatting helpers ([0efd421](https://github.com/WianVDM/pi-graphify/commit/0efd4214e6b4397c126abecb864ad947be896fa6))
+
+
+### Bug Fixes
+
+* replace /graphify-build references with graphify CLI command ([63f4fb2](https://github.com/WianVDM/pi-graphify/commit/63f4fb25889719448f13c4dffb485164f7774c55))
+
+## [0.2.0](https://github.com/WianVDM/pi-graphify/compare/pi-graphify-v0.1.0...pi-graphify-v0.2.0) (2026-07-12)
+
+
+### Features
+
+* add graphify_status tool and /graphify-status command ([99f809c](https://github.com/WianVDM/pi-graphify/commit/99f809caace328e5af97a5dcdac50af025437776))
+* implement phase 2 backend abstraction ([40afa65](https://github.com/WianVDM/pi-graphify/commit/40afa65bbadf9bcb72676a613d94f6bdb677cc5d))
+
+
+### Bug Fixes
+
+* correct status tool description and missing-Graphify warning ([c4225c1](https://github.com/WianVDM/pi-graphify/commit/c4225c1591124a65ca0df33565168970a6720a9d))
+* normalize package author email casing ([fcfa352](https://github.com/WianVDM/pi-graphify/commit/fcfa3520463ed860be1264daa6443c608a197444))
+
 ## [Unreleased]
 
 ## 0.1.0 (2026-07-11)

package/README.md

@@ -1,93 +1,86 @@
 # pi-graphify
 
-A production-quality [pi](https://pi.dev) extension for [Graphify](https://github.com/Graphify-Labs/graphify).
+A [Pi](https://pi.dev) extension that brings [Graphify](https://github.com/Graphify-Labs/graphify) knowledge graph capabilities into your agent sessions.
 
-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.
+## Install
 
-> ⚠️ **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.
+```bash
+pi install @wwjd/pi-graphify
+```
 
-## Quick Start
+Or run locally during development:
 
 ```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
+## What it does
 
-```
-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
-```
+`pi-graphify` detects the Graphify CLI and a project's `graphify-out/graph.json` graph, then exposes Graphify operations as Pi tools and slash commands. It routes requests through a backend abstraction so the agent can use Graphify without worrying about whether it's talking to the CLI or (in the future) an MCP server.
+
+When a graph is present, the extension also injects a lightweight hint into the system prompt so the agent knows it can ask structural codebase questions via the graph.
 
-## Package Structure
+## Requirements
 
-### Extensions (`extensions/`)
+- [Graphify](https://github.com/Graphify-Labs/graphify) must be installed and on your `PATH`.
+- The project must have a generated graph at `graphify-out/graph.json`.
 
-TypeScript modules that extend pi's behavior with custom tools, slash commands, and event handlers.
+## Current commands
 
-### Source (`src/`)
+| Command | Description |
+|---|---|
+| `/graphify-status` | Check whether a graph exists and whether the Graphify CLI is compatible. |
 
-Pi-agnostic implementation logic. The `extensions/` layer imports from here and registers everything with Pi.
+## Current tools
 
-## Development
+| Tool | Description |
+|---|---|
+| `graphify_status` | Check graph presence, path, and Graphify CLI compatibility. |
+| `graphify_build` | Build or incrementally update the Graphify knowledge graph. |
+| `graphify_query` | Ask a natural-language question against the graph. |
+| `graphify_path` | Find the shortest path between two graph nodes. |
+| `graphify_explain` | Explain a node and its connections in the graph. |
+| `graphify_affected` | Show the blast radius of changes to one or more files. |
+| `graphify_version` | Report the installed Graphify version and compatibility status. |
 
-### Requirements
+## What's coming
 
-- Node.js 22+
-- npm 10+
-- pi CLI
+Slash commands for the tools above are planned in the next phase:
 
-### Scripts
+- `/graphify-build`
+- `/graphify-query`
+- `/graphify-path`
+- `/graphify-explain`
+- `/graphify-affected`
+- `/graphify-version`
 
-| 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 |
+Later phases will add background file watching, MCP backend support, ecosystem integrations, and release readiness work. See [plan/PLAN.md](plan/PLAN.md) for the full roadmap.
 
-### Testing the package
+## How it works
 
-```bash
-# Run ephemerally with no other extensions loaded
-pi -ne -e . --no-session
+1. On session start, the extension detects the installed Graphify version and looks for `graphify-out/graph.json`.
+2. If a graph is found, a hint is added to the agent context.
+3. Tools and commands route through a coordinator that selects the best available backend.
 
-# Test a specific tool in print mode
-pi -ne -e . --no-session -p "List the available tools."
-```
+## Status
 
-## Publishing
+This extension is in early development. The public API, tools, and commands will evolve as the extension matures toward a stable 1.0 release.
 
-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/`.
+## Documentation
 
-See `RELEASE.md` for versioning and release standards.
+- [Design](docs/DESIGN.md)
+- [Architecture](docs/ARCHITECTURE.md)
+- [Ecosystem](docs/ECOSYSTEM.md)
+- [Versioning](docs/VERSIONING.md)
+- [Release standards](RELEASE.md)
+- [Agent context](AGENTS.md)
 
-Before publishing, update:
+## Development
 
-- `package.json` author and repository fields
-- `README.md` with final usage instructions
-- `CHANGELOG.md` with release notes
+```bash
+npm run typecheck
+npm run lint
+```
 
 ## License
 

package/docs/TESTING.md

@@ -0,0 +1,149 @@
+# Local Development and Testing Guide
+
+This guide covers how to install and test the local `pi-graphify` extension, plus how to install and uninstall the Graphify CLI for end-to-end verification.
+
+## Prerequisites
+
+- [Pi](https://pi.dev) installed and on your PATH.
+- Node.js 20+ and npm.
+- Python 3.10+ (only needed when testing with the Graphify CLI).
+- [uv](https://docs.astral.sh/uv/) or [pipx](https://pipx.pypa.io/) (recommended for Graphify).
+
+## Install the local pi-graphify extension
+
+From the project root directory, run:
+
+```bash
+pi install .
+```
+
+This installs the local package into Pi so the extension is loaded on the next Pi session.
+
+To verify the install, start Pi in any project and check that `/graphify-status` autocompletes.
+
+## Automated checks
+
+Before running manual tests, run the static and automated checks:
+
+```bash
+npm run typecheck
+npm run lint
+npm test
+npm audit --audit-level=moderate
+```
+
+All should pass.
+
+## Install the Graphify CLI
+
+The official PyPI package is **`graphifyy`** (double-y). The CLI command is still `graphify`.
+
+### Recommended: uv
+
+```bash
+uv tool install graphifyy
+graphify --version
+```
+
+### Alternative: pipx
+
+```bash
+pipx install graphifyy
+graphify --version
+```
+
+### Alternative: pip
+
+```bash
+pip install graphifyy
+graphify --version
+```
+
+After installing, `graphify` should be available on your PATH. If it is not, add the tool's bin directory to your PATH (for example, `~/.local/bin` for `uv tool` or `pipx`).
+
+## Build a graph for testing
+
+Phase 3 only adds the tools. The `/graphify-build` command is added in Phase 4, so for now build the graph directly with the Graphify CLI.
+
+The recommended approach for testing `pi-graphify` is a code-only graph. It skips semantic extraction, so it does not require an API key or extra Python dependencies:
+
+```bash
+graphify . --code-only
+```
+
+This creates a `graphify-out/` directory with `graph.json`, `graph.html`, and `GRAPH_REPORT.md`. It has been verified to work with the default `uv tool install graphifyy` setup.
+
+If you want semantic extraction (docs, images, etc.), you need the `kimi` backend dependencies. Install them with:
+
+```bash
+uv tool install "graphifyy[kimi]" --force
+```
+
+Then run the full build:
+
+```bash
+graphify .
+```
+
+Once Phase 4 is complete, `/graphify-build` will be available as an alternative.
+
+## Verify the extension with Graphify installed
+
+1. Start Pi in a project with a built graph.
+2. You should see a notification: `Graphify graph ready: ...`.
+3. The supported tools should be available to the LLM. You can verify by asking: "What graphify tools are available?" or by checking the system prompt tool list.
+4. Test a tool by asking: "Use the graphify graph to explain how auth works in this codebase."
+
+## Verify the extension without Graphify
+
+1. Uninstall Graphify (see below).
+2. Start Pi in a project.
+3. You should see a warning: `Graphify CLI was not detected on PATH...`.
+4. No `graphify_*` tools should be available to the LLM.
+5. `/graphify-status` should still work and report that no graph was found.
+
+## Uninstall the Graphify CLI
+
+### uv
+
+```bash
+uv tool uninstall graphifyy
+```
+
+### pipx
+
+```bash
+pipx uninstall graphifyy
+```
+
+### pip
+
+```bash
+pip uninstall graphifyy
+```
+
+After uninstalling, run `graphify --version` to confirm it is no longer on PATH.
+
+## Uninstall the local pi-graphify extension
+
+```bash
+pi uninstall npm:@wwjd/pi-graphify
+```
+
+Or remove the package manually from Pi's package directory if you installed it locally.
+
+## Troubleshooting
+
+| Problem | Solution |
+|---|---|
+| `graphify` command not found after install | Ensure the tool bin directory is on your PATH. For `uv tool`, try `uv tool update-shell`. |
+| Pi does not load the extension | Run `pi --version` and confirm the package is listed in `pi packages`. Try `/reload`. |
+| Extension shows old version after changes | Run `pi install .` again, then start a fresh Pi session. |
+| `graphify_status` returns "No Graphify graph found" | Build the graph first with `graphify . --code-only`. |
+| Semantic extraction fails with `openai` package error | Run `graphify . --code-only` for a code-only graph, or install the `kimi` backend with `uv tool install "graphifyy[kimi]" --force`. |
+
+## References
+
+- [Graphify repository](https://github.com/Graphify-Labs/graphify)
+- [graphifyy on PyPI](https://pypi.org/project/graphifyy/)
+- [Pi extensions documentation](https://pi.dev/docs/extensions)

package/extensions/index.ts

@@ -4,28 +4,70 @@
  * Brings Graphify knowledge graph capabilities into Pi sessions:
  *   - Detects existing graphify-out/graph.json in the project
  *   - Registers LLM-callable tools (graphify_status, graphify_query, ...)
- *   - Registers slash commands (/graphify-build, /graphify-status, ...)
+ *   - Registers slash commands (/graphify-status, ...)
  *   - Optionally watches source files for incremental rebuilds
  */
 
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import { loadConfig } from "../src/config.js";
+import { GraphifyCoordinator } from "../src/coordinator.js";
 import { buildGraphifyHint, graphifyStatus } from "../src/graphify.js";
 import { registerGraphifyTools } from "../src/tools/index.js";
 
 export default function (pi: ExtensionAPI) {
-  const config = loadConfig();
+  // Coordinator is created per session and shared by tools and commands.
+  let coordinator: GraphifyCoordinator | null = null;
+  const getCoordinator = () => coordinator;
+  const registeredToolNames = new Set<string>();
 
-  // ── 1. Notify and inject context when a graph is present ──────────
+  // ── 1. Register slash commands synchronously ─────────────────────
+  pi.registerCommand("graphify-status", {
+    description: "Show Graphify graph status for the current project",
+    handler: async (_args, ctx) => {
+      const current = getCoordinator();
+      if (!current) {
+        ctx.ui.notify("Graphify is not initialized.", "warning");
+        return;
+      }
+
+      const status = await current.status({ cwd: ctx.cwd });
+      if (status.hasGraph && status.graphPath) {
+        ctx.ui.notify(`Graphify graph ready: ${status.graphPath}`, "info");
+      } else {
+        ctx.ui.notify("No Graphify graph found. Build one with `graphify .`.", "warning");
+      }
+    },
+  });
+
+  // ── 2. Initialize coordinator and register tools per session ───────
+  // Tools are registered inside session_start so we can gate them by the
+  // coordinator's detected capabilities. Registering at load time would mean
+  // the LLM sees tools that may not be supported by the installed Graphify version.
   pi.on("session_start", async (_event, ctx) => {
-    const status = await graphifyStatus(ctx.cwd);
+    coordinator = new GraphifyCoordinator({ cwd: ctx.cwd });
+    await coordinator.initialize();
+
+    registerGraphifyTools(pi, getCoordinator, { registeredToolNames });
+
+    const status = await coordinator.status({ cwd: ctx.cwd });
     if (status.hasGraph && status.graphPath) {
       ctx.ui.notify(`Graphify graph ready: ${status.graphPath}`, "info");
     }
+
+    if (coordinator.version === null) {
+      ctx.ui.notify(
+        "Graphify CLI was not detected on PATH. Install Graphify to use build, query, and other graph tools.",
+        "warning",
+      );
+    }
+
+    for (const warning of coordinator.warnings) {
+      ctx.ui.notify(warning, "warning");
+    }
   });
 
+  // ── 3. Inject context hint when a graph is present ────────────────
   pi.on("before_agent_start", async (event, ctx) => {
-    const status = await graphifyStatus(ctx.cwd);
+    const status = graphifyStatus(ctx.cwd);
     if (!status.hasGraph || !status.graphPath) {
       return;
     }
@@ -36,19 +78,11 @@ export default function (pi: ExtensionAPI) {
     };
   });
 
-  // ── 2. Register custom tools the LLM can call ─────────────────────
-  registerGraphifyTools(pi, config);
-
-  // ── 3. Register slash commands ────────────────────────────────────
-  pi.registerCommand("graphify-status", {
-    description: "Show Graphify graph status for the current project",
-    handler: async (_args, ctx) => {
-      const status = await graphifyStatus(ctx.cwd);
-      if (status.hasGraph && status.graphPath) {
-        ctx.ui.notify(`Graphify graph ready: ${status.graphPath}`, "info");
-      } else {
-        ctx.ui.notify("No Graphify graph found. Run /graphify-build to create one.", "warning");
-      }
-    },
+  // ── 4. Clean up coordinator on shutdown ─────────────────────────
+  pi.on("session_shutdown", async () => {
+    if (coordinator) {
+      await coordinator.close();
+      coordinator = null;
+    }
   });
 }

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@wwjd/pi-graphify",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "Graphify knowledge graph integration for Pi coding agent",
   "type": "module",
   "license": "MIT",
-  "author": "WIAN <WIANVDM4@GMAIL.COM>",
+  "author": "Wian <wianvdm4@gmail.com>",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/WianVDM/pi-graphify.git"
@@ -34,7 +34,7 @@
     "access": "public"
   },
   "scripts": {
-    "test": "echo \"No tests yet\" && exit 0",
+    "test": "node --test --import tsx src/tools/tools.test.ts src/extensions/extension-load.test.ts",
     "lint": "biome check .",
     "lint:fix": "biome check --write .",
     "format": "biome format --write .",
@@ -57,6 +57,7 @@
     "@earendil-works/pi-ai": "^0.74.0",
     "@earendil-works/pi-coding-agent": "^0.80.6",
     "@types/node": "^20.0.0",
+    "tsx": "^4.23.0",
     "typebox": "^1.1.24",
     "typescript": "^5.0.0"
   },

package/src/backends/cli.ts

@@ -0,0 +1,201 @@
+/**
+ * CLI backend for Graphify.
+ *
+ * Resolves the `graphify` executable, runs commands via `execFile`, and
+ * normalizes the results into the backend-agnostic `GraphifyResult` shape.
+ */
+
+import { execFile } from "node:child_process";
+import { existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+import { buildCapabilities, detectVersion } from "../version.js";
+import type { GraphifyBackend, GraphifyCapabilities, GraphifyResult } from "./types.js";
+import { allCapabilitiesDisabled } from "./types.js";
+
+const DEFAULT_TIMEOUT = 30_000;
+
+export interface CliBackendOptions {
+  cwd: string;
+  timeoutMs?: number;
+  /** Explicit executable path from config or env. */
+  explicitPath?: string;
+}
+
+export class CliBackend implements GraphifyBackend {
+  readonly type = "cli" as const;
+  private readonly cwd: string;
+  private readonly timeoutMs: number;
+  private readonly explicitPath: string | undefined;
+  private _cli: string | null = null;
+  private _version: string | null = null;
+  private _capabilities: GraphifyCapabilities | null = null;
+
+  constructor(options: CliBackendOptions) {
+    this.cwd = options.cwd;
+    this.timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT;
+    this.explicitPath = options.explicitPath;
+  }
+
+  get version(): string | null {
+    return this._version;
+  }
+
+  get capabilities(): GraphifyCapabilities {
+    return this._capabilities ?? allCapabilitiesDisabled();
+  }
+
+  async initialize(): Promise<void> {
+    this._cli = await this.resolveCli();
+    const versionInfo = await detectVersion(this._cli, this.cwd);
+    this._version = versionInfo.version;
+
+    this._capabilities = await buildCapabilities(this._cli, this.cwd, versionInfo, async (args) =>
+      this.runHelp(args),
+    );
+  }
+
+  async run(operation: string, options: unknown): Promise<GraphifyResult> {
+    const cli = await this.resolveCli();
+    const args = buildArgs(operation, options);
+    const start = performance.now();
+
+    return new Promise((resolve) => {
+      execFile(cli, args, { cwd: this.cwd, timeout: this.timeoutMs }, (error, stdout, stderr) => {
+        const durationMs = Math.round(performance.now() - start);
+        if (error) {
+          resolve({
+            stdout: stdout.trim(),
+            stderr: stderr.trim() || error.message,
+            exitCode: typeof error.code === "number" ? error.code : 1,
+            durationMs,
+            backend: "cli",
+            feature: operation,
+          });
+          return;
+        }
+        resolve({
+          stdout: stdout.trim(),
+          stderr: stderr.trim(),
+          exitCode: 0,
+          durationMs,
+          backend: "cli",
+          feature: operation,
+        });
+      });
+    });
+  }
+
+  async close(): Promise<void> {
+    // CLI backend has no persistent process to clean up.
+    this._cli = null;
+  }
+
+  private async resolveCli(): Promise<string> {
+    if (this._cli) return this._cli;
+    if (this.explicitPath) return this.explicitPath;
+
+    // Try the PATH first.
+    const fromPath = await findOnPath("graphify");
+    if (fromPath) return fromPath;
+
+    // Common install locations.
+    const candidates = [
+      join(homedir(), ".local", "bin", "graphify"),
+      join(homedir(), ".cargo", "bin", "graphify"),
+      join(homedir(), ".pipx", "venvs", "graphify", "bin", "graphify"),
+    ];
+
+    for (const candidate of candidates) {
+      if (existsSync(candidate)) return candidate;
+    }
+
+    // Fall back to the bare command and let execFile report the error.
+    return "graphify";
+  }
+
+  private async runHelp(args: string[]): Promise<{ stdout: string; exitCode: number }> {
+    const cli = await this.resolveCli();
+    return new Promise((resolve) => {
+      execFile(cli, args, { cwd: this.cwd, timeout: 10_000 }, (error, stdout, _stderr) => {
+        if (error) {
+          resolve({
+            stdout: stdout.trim(),
+            exitCode: typeof error.code === "number" ? error.code : 1,
+          });
+          return;
+        }
+        resolve({ stdout: stdout.trim(), exitCode: 0 });
+      });
+    });
+  }
+}
+
+/** Best-effort find an executable on the user PATH. */
+function findOnPath(command: string): Promise<string | null> {
+  const checkCmd = process.platform === "win32" ? "where" : "which";
+  const shell = process.platform === "win32" ? "cmd.exe" : undefined;
+
+  return new Promise((resolve) => {
+    execFile(checkCmd, [command], { shell }, (error, stdout) => {
+      if (error || !stdout.trim()) {
+        resolve(null);
+        return;
+      }
+      resolve(stdout.split("\n")[0].trim());
+    });
+  });
+}
+
+/** Build a CLI argument array from an operation and options. */
+function buildArgs(operation: string, options: unknown): string[] {
+  if (!options || typeof options !== "object") {
+    return [operation];
+  }
+
+  const opts = options as Record<string, unknown>;
+  const args = [operation];
+
+  if (opts.cwd && typeof opts.cwd === "string") {
+    // graphify commands operate on cwd via the spawned process working directory;
+    // no explicit flag is needed for most operations.
+  }
+
+  if (opts.codeOnly === true) args.push("--code-only");
+  if (opts.update === true) args.push("--update");
+  if (opts.directed === true) args.push("--directed");
+
+  if (opts.question && typeof opts.question === "string") {
+    args.push(opts.question);
+  }
+  if (opts.source && typeof opts.source === "string") {
+    args.push("--source", opts.source);
+  }
+  if (opts.target && typeof opts.target === "string") {
+    args.push("--target", opts.target);
+  }
+  if (opts.node && typeof opts.node === "string") {
+    args.push("--node", opts.node);
+  }
+  if (Array.isArray(opts.files)) {
+    for (const file of opts.files) {
+      if (typeof file === "string") args.push(file);
+    }
+  }
+  if (Array.isArray(opts.paths)) {
+    for (const p of opts.paths) {
+      if (typeof p === "string") {
+        args.push(resolve(p));
+      }
+    }
+  }
+
+  return args;
+}
+
+/** Create a CLI backend and initialize it. */
+export async function createCliBackend(options: CliBackendOptions): Promise<CliBackend> {
+  const backend = new CliBackend(options);
+  await backend.initialize();
+  return backend;
+}