@wwjd/pi-graphify 0.2.0 → 0.4.0

package/CHANGELOG.md

@@ -5,6 +5,26 @@ 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.4.0](https://github.com/WianVDM/pi-graphify/compare/pi-graphify-v0.3.0...pi-graphify-v0.4.0) (2026-07-12)
+
+
+### Features
+
+* **commands:** add slash commands and unified /graphify menu ([7c7a566](https://github.com/WianVDM/pi-graphify/commit/7c7a566b4dcda3c7b2d166863a7704a98839669a))
+
+## [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)
 
 

package/README.md

@@ -1,93 +1,71 @@
 # 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.
-
-> ⚠️ **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
+## Install
 
 ```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
+pi install @wwjd/pi-graphify
 ```
 
-## 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.
+## What it does
 
-### Source (`src/`)
+`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.
 
-Pi-agnostic implementation logic. The `extensions/` layer imports from here and registers everything with Pi.
+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.
 
-## Development
+## Requirements
 
-### Requirements
+- [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`.
 
-- Node.js 22+
-- npm 10+
-- pi CLI
-
-### Scripts
+## Current commands
 
 | 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
+|---|---|
+| `/graphify` | Open the unified Graphify command menu. |
+| `/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-status` | Check whether a graph exists and whether the Graphify CLI is compatible. |
+| `/graphify-version` | Report the installed Graphify version and compatibility status. |
+
+## Current tools
+
+| 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. |
+
+## What's coming
+
+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.
+
+## How it works
+
+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.
+
+## Status
+
+This extension is in early development. The public API, tools, and commands will evolve as the extension matures toward a stable 1.0 release.
+
+## Documentation
+
+- [Design](docs/DESIGN.md)
+- [Architecture](docs/ARCHITECTURE.md)
+- [Ecosystem](docs/ECOSYSTEM.md)
+- [Versioning](docs/VERSIONING.md)
+- [Release standards](RELEASE.md)
+- [Agent context](AGENTS.md)
 
 ## License
 

package/docs/TESTING.md

@@ -0,0 +1,150 @@
+# 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
+
+You can build the graph with the Graphify CLI directly, or use the `/graphify-build` slash command once the extension is loaded.
+
+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 .
+```
+
+Inside Pi you can also run `/graphify` to open the command menu and select "Build graph", or type `/graphify-build` directly.
+
+## 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 slash command: type `/graphify` to open the menu, or `/graphify-status` to check graph status.
+5. 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,11 +4,13 @@
  * 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 { registerGraphifyCommands } from "../src/commands/index.js";
+import { registerGraphifyMenuCommand } from "../src/commands/menu.js";
 import { GraphifyCoordinator } from "../src/coordinator.js";
 import { buildGraphifyHint, graphifyStatus } from "../src/graphify.js";
 import { registerGraphifyTools } from "../src/tools/index.js";
@@ -17,33 +19,22 @@ export default function (pi: ExtensionAPI) {
   // 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. Register tools and commands synchronously ──────────────────
-  registerGraphifyTools(pi, getCoordinator);
+  // ── 1. Register slash commands synchronously ─────────────────────
+  registerGraphifyCommands(pi, getCoordinator);
+  registerGraphifyMenuCommand(pi, getCoordinator);
 
-  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. Run /graphify-build to create one.", "warning");
-      }
-    },
-  });
-
-  // ── 2. Initialize coordinator per session ─────────────────────────
+  // ── 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) => {
     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");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wwjd/pi-graphify",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "Graphify knowledge graph integration for Pi coding agent",
   "type": "module",
   "license": "MIT",
@@ -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/commands/commands.test.ts src/commands/menu.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/mock.ts

@@ -0,0 +1,47 @@
+import type { GraphifyBackend, GraphifyCapabilities, GraphifyResult } from "./types.js";
+
+export const allCapabilitiesEnabled = (): GraphifyCapabilities => ({
+  build: true,
+  query: true,
+  path: true,
+  explain: true,
+  affected: true,
+  add: true,
+  watch: true,
+  reflect: true,
+  mcp: true,
+  status: true,
+  version: true,
+  directedGraph: true,
+  incrementalUpdate: true,
+  semanticExtraction: true,
+});
+
+export interface MockBackendOptions {
+  version?: string;
+  capabilities?: GraphifyCapabilities;
+  run?: (operation: string, options: unknown) => Promise<GraphifyResult>;
+}
+
+export function createMockBackend(options: MockBackendOptions = {}): GraphifyBackend {
+  const {
+    version = "2.100.0",
+    capabilities = allCapabilitiesEnabled(),
+    run = async (operation) => ({
+      stdout: `ok: ${operation}`,
+      stderr: "",
+      exitCode: 0,
+      durationMs: 1,
+      backend: "cli",
+      feature: operation,
+    }),
+  } = options;
+
+  return {
+    type: "cli",
+    version,
+    capabilities,
+    run,
+    close: async () => {},
+  };
+}

package/src/commands/affected.ts

@@ -0,0 +1,63 @@
+/**
+ * /graphify-affected — show files and nodes affected by changes to given files.
+ */
+
+import { resolve } from "node:path";
+import type { GraphifyCapabilities } from "../backends/types.js";
+import { formatResultForCommand } from "./format.js";
+import { notifyCommandError, requireCoordinatorWithCapability } from "./helpers.js";
+import { splitArgs, usageError } from "./parse.js";
+import type { CommandDefinition, CommandExecutor } from "./types.js";
+
+const FEATURE: keyof GraphifyCapabilities = "affected";
+const AFFECTED_USAGE = "<file> [file...]";
+
+const executeAffected: CommandExecutor = async (ctx, getCoordinator, args) => {
+  if (!ctx.hasUI) return;
+
+  const coordinator = requireCoordinatorWithCapability(
+    ctx,
+    getCoordinator,
+    FEATURE,
+    "The installed Graphify version does not support affected analysis.",
+  );
+  if (!coordinator) return;
+
+  try {
+    const files = parseAffectedArgs(ctx.cwd, args);
+    const result = await coordinator.affected({ cwd: ctx.cwd, files });
+    ctx.ui.notify(formatResultForCommand(result), "info");
+  } catch (error) {
+    notifyCommandError(ctx, error);
+  }
+};
+
+export const affectedCommand: CommandDefinition = {
+  name: "graphify-affected",
+  label: "Show affected",
+  description: "Show files and nodes affected by changes to given files",
+  feature: FEATURE,
+  usage: AFFECTED_USAGE,
+  argMode: "input",
+  prompt: "Files to analyze",
+  placeholder: "src/index.ts src/utils.ts",
+  execute: executeAffected,
+};
+
+function parseAffectedArgs(cwd: string, args: string): string[] {
+  const tokens = splitArgs(args);
+  if (tokens.length === 0) {
+    throw usageError("graphify-affected", AFFECTED_USAGE);
+  }
+
+  return tokens.map((file) => resolveFile(cwd, file));
+}
+
+function resolveFile(cwd: string, file: string): string {
+  const absolute = resolve(cwd, file);
+  const normalizedCwd = resolve(cwd);
+  if (!absolute.startsWith(normalizedCwd)) {
+    throw new Error(`Invalid file path: ${file} is outside the project directory.`);
+  }
+  return absolute;
+}

package/src/commands/build.ts

@@ -0,0 +1,77 @@
+/**
+ * /graphify-build — build or update the Graphify knowledge graph.
+ */
+
+import type { GraphifyCapabilities } from "../backends/types.js";
+import { formatResultForCommand } from "./format.js";
+import { notifyCommandError, requireCoordinatorWithCapability } from "./helpers.js";
+import { parseBooleanFlag, splitArgs, usageError } from "./parse.js";
+import type { CommandDefinition, CommandExecutor } from "./types.js";
+
+const FEATURE: keyof GraphifyCapabilities = "build";
+const BUILD_USAGE = "[--code-only] [--update] [--directed]";
+
+const executeBuild: CommandExecutor = async (ctx, getCoordinator, args) => {
+  if (!ctx.hasUI) return;
+
+  const coordinator = requireCoordinatorWithCapability(
+    ctx,
+    getCoordinator,
+    FEATURE,
+    "The installed Graphify version does not support graph builds.",
+  );
+  if (!coordinator) return;
+
+  if (!ctx.isProjectTrusted()) {
+    ctx.ui.notify("Project trust is required to build the Graphify graph.", "warning");
+    return;
+  }
+
+  try {
+    const { codeOnly, update, directed } = parseBuildArgs(args);
+    const result = await coordinator.build({
+      cwd: ctx.cwd,
+      codeOnly,
+      update,
+      directed,
+    });
+    ctx.ui.notify(formatResultForCommand(result), "info");
+  } catch (error) {
+    notifyCommandError(ctx, error);
+  }
+};
+
+export const buildCommand: CommandDefinition = {
+  name: "graphify-build",
+  label: "Build graph",
+  description: "Build or incrementally update the Graphify knowledge graph",
+  feature: FEATURE,
+  usage: BUILD_USAGE,
+  argMode: "flags",
+  prompt: "Build graph (optional flags)",
+  placeholder: "--code-only --update --directed",
+  execute: executeBuild,
+};
+
+interface ParsedBuildArgs {
+  codeOnly: boolean | undefined;
+  update: boolean | undefined;
+  directed: boolean | undefined;
+}
+
+function parseBuildArgs(args: string): ParsedBuildArgs {
+  const tokens = splitArgs(args);
+  let result = parseBooleanFlag(tokens, "code-only", true);
+  const codeOnly = result.value;
+  result = parseBooleanFlag(result.rest, "update", true);
+  const update = result.value;
+  result = parseBooleanFlag(result.rest, "directed", true);
+  const directed = result.value;
+
+  const unknown = result.rest.find((t) => t.startsWith("--"));
+  if (unknown || result.rest.length > 0) {
+    throw usageError("graphify-build", BUILD_USAGE);
+  }
+
+  return { codeOnly, update, directed };
+}