@wwjd/pi-graphify 0.1.0

package/docs/VERSIONING.md

@@ -0,0 +1,241 @@
+# Versioning and Dependency Strategy: pi-graphify
+
+This document describes how `pi-graphify` manages its dependency on the external Graphify CLI and how it handles version mismatches.
+
+---
+
+## Supported Graphify range
+
+`pi-graphify` uses a **hybrid strategy** for determining the supported Graphify range:
+
+1. A **hardcoded minimum version** is enforced for safety. This protects the extension from known incompatible Graphify versions.
+2. **Runtime capability detection** is used to determine which features are actually available. This is more reliable than version number parsing alone.
+3. A **hardcoded maximum version** is only set when a known breaking Graphify release is discovered.
+
+This approach balances maintainability with adaptability. Auto-detecting the full supported range from Graphify’s CLI output is too fragile because the CLI’s help text, flag names, and output format can change between releases.
+
+```typescript
+const SUPPORTED_GRAPHIFY_RANGE = {
+  min: '2.100.0',     // Hardcoded minimum tested version
+  recommended: 'latest', // Best experience
+  max: undefined,      // No known breaking upper bound yet
+};
+```
+
+These values are examples. The exact `min` will be set during implementation based on real Graphify CLI behavior.
+
+---
+
+## Version detection
+
+The extension detects the installed Graphify version in this order:
+
+1. **Environment variable** `GRAPHIFY_PATH` — if set, use this executable.
+2. **Config** `graphifyPath` — if set, use this executable.
+3. **PATH lookup** — run `which graphify` (Unix) or `where graphify` (Windows).
+4. **Common installation paths** — check `~/.local/bin/graphify`, `~/.cargo/bin/graphify`, pipx/uv tool directories.
+
+Once an executable is found, the extension runs:
+
+```bash
+graphify --version
+```
+
+or falls back to:
+
+```bash
+graphify version
+```
+
+If neither works, the version is reported as `unknown` and the extension enters best-effort mode.
+
+---
+
+## Installation method detection
+
+The extension attempts to detect how Graphify was installed so it can suggest the correct update command:
+
+| Method | Detection | Update command |
+|---|---|---|
+| uv tool | `uv tool list` includes graphifyy | `uv tool install --upgrade graphifyy` |
+| pipx | `pipx list` includes graphifyy | `pipx upgrade graphifyy` |
+| pip user | Executable in pip user bin | `pip install --upgrade graphifyy` |
+| pip system | Executable in system site | `pip install --upgrade graphifyy` or system package manager |
+| cargo | Binary from `cargo install` | `cargo install fallow-cli` (if applicable) |
+| unknown | Cannot determine | `pip install --upgrade graphifyy` or `uv tool install --upgrade graphifyy` |
+
+The update command is shown to the user, never executed automatically.
+
+---
+
+## Version mismatch handling
+
+### Graphify missing
+
+- Disable all Graphify tools.
+- Show a notification with installation instructions.
+- Keep the session alive. The extension is otherwise inert.
+
+### Version below minimum
+
+- Disable features that require the minimum version.
+- Show a warning with the detected version, supported range, and update command.
+- Basic query/explain may still work if the CLI contract is compatible.
+
+### Version above supported range
+
+- If the extension has a known max version and the installed version exceeds it, disable features with known breaking changes.
+- Show a warning asking the user to update `pi-graphify` if a newer version supports it.
+- Log the issue for debugging.
+
+### Version unknown
+
+- Enter best-effort mode.
+- Assume basic CLI compatibility.
+- Do not claim to support advanced features.
+
+### Feature-specific detection
+
+Some features are gated by capability checks rather than strict version checks. For example:
+
+- If `graphify --help` does not list `affected`, the `graphify_affected` tool is disabled.
+- If the MCP server does not expose `shortest_path`, the coordinator falls back to CLI for that operation.
+
+This makes the extension resilient to partial CLI support.
+
+---
+
+## Runtime capability detection
+
+In addition to the hardcoded minimum version, the extension probes the installed Graphify CLI for capabilities. This is more robust than relying solely on version numbers.
+
+### How capability detection works
+
+1. **Version check** — If the version is below `min`, disable advanced features and warn.
+2. **Help parsing** — Run `graphify --help` and parse the available subcommands.
+3. **Feature probing** — For borderline features, run a lightweight command (e.g., `graphify affected --help`) to confirm the feature exists.
+4. **MCP discovery** — If MCP is requested, attempt to start the server and list available tools.
+
+### Why not fully auto-detect the range?
+
+Fully auto-detecting the supported version range from the CLI is fragile because:
+- Help text and flag names change.
+- A command may exist but behave differently than expected.
+- Subtle breaking changes (e.g., output format) are not visible in `--help`.
+
+The hardcoded minimum is a safety guard. The capability detection widens support within that guard.
+
+### Example
+
+```typescript
+const capabilities: GraphifyCapabilities = {
+  query: semver.gte(version, '2.0.0'),
+  path: semver.gte(version, '2.0.0'),
+  affected: hasCommand('affected'),  // runtime probe
+  reflect: hasCommand('reflect'),      // runtime probe
+  mcp: canStartMcpServer(),            // runtime probe
+};
+```
+
+If a feature probe fails, only that feature is disabled. The rest of the extension continues to work.
+
+---
+
+## Capability matrix
+
+The extension maintains a mapping of Graphify versions to features. This is used as an initial filter before runtime probing.
+
+| Feature | Min CLI version | Runtime probe | Notes |
+|---|---|---|---|
+| `build` | 2.0.0 | `graphify build --help` | Core command. |
+| `query` | 2.0.0 | `graphify query --help` | Core command. |
+| `path` | 2.0.0 | `graphify path --help` | Core command. |
+| `explain` | 2.0.0 | `graphify explain --help` | Core command. |
+| `affected` | 2.50.0 | `graphify affected --help` | Example threshold. |
+| `reflect` | 2.70.0 | `graphify reflect --help` | Example threshold. |
+| `mcp` | 2.90.0 | Start MCP server and list tools | MCP server support. |
+| `--directed` | 2.20.0 | `graphify build --help` mentions `--directed` | Build flag. |
+| `--update` | 2.10.0 | `graphify build --help` mentions `--update` | Incremental build. |
+| `--watch` | 2.30.0 | `graphify watch --help` | File watcher. |
+
+These versions are illustrative. The actual values will be validated against the real Graphify CLI during implementation.
+
+---
+
+## Update handling
+
+### What the extension does
+
+- Detect installed version.
+- Compare to supported range.
+- Notify user if an update is recommended.
+- Provide the exact update command.
+
+### What the extension does NOT do
+
+- Auto-update Graphify.
+- Install Graphify automatically (with one exception: it may suggest the install command).
+- Modify the user’s system packages without explicit action.
+
+### User-initiated update
+
+A user can run:
+
+```text
+/graphify-update
+```
+
+or the agent can call `graphify_update`. This tool runs the detected update command with the user’s confirmation. It is only available in trusted projects and may require elevated permissions depending on the installation method.
+
+### Extension self-update
+
+`pi-graphify` itself is updated through `pi update npm:pi-graphify`, not through Graphify. The extension’s npm version is independent of the Graphify CLI version.
+
+---
+
+## Backwards compatibility
+
+### For `pi-graphify` users
+
+- Minor and patch releases of `pi-graphify` maintain backward compatibility with existing config and tool schemas.
+- Major releases may change tool names, parameters, or config options.
+- The supported Graphify CLI range may be widened in minor/patch releases.
+
+### For Graphify CLI users
+
+- `pi-graphify` supports a range of Graphify CLI versions.
+- New Graphify CLI features may not be available until `pi-graphify` is updated to expose them.
+- Breaking Graphify CLI changes may require a major or minor `pi-graphify` release.
+
+---
+
+## Release cadence
+
+### Graphify CLI releases
+
+Graphify releases independently. The `pi-graphify` maintainers will:
+- Test new Graphify versions.
+- Update the capability matrix.
+- Release a new `pi-graphify` version if needed.
+
+### pi-graphify releases
+
+- Patch releases: bug fixes, doc updates, dependency updates.
+- Minor releases: new tools/commands, new Graphify CLI support, non-breaking features.
+- Major releases: breaking changes to public API, removal of tools, changes to default behavior.
+
+---
+
+## Telemetry and logging
+
+Version mismatches and capability failures are logged at the `warning` level. No data is sent to remote servers. Logs are local to the Pi session and can be used to diagnose issues.
+
+---
+
+## Open questions
+
+1. Should the extension pin a maximum Graphify version to avoid surprises from upstream CLI changes?
+2. Should the extension bundle a known-good Graphify CLI version in the future?
+3. How should the extension handle Graphify installed from a Git branch or source build?
+
+These will be resolved during implementation and testing.

package/extensions/index.ts

@@ -0,0 +1,54 @@
+/**
+ * pi-graphify — Extension entry point
+ *
+ * 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, ...)
+ *   - Optionally watches source files for incremental rebuilds
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { loadConfig } from "../src/config.js";
+import { buildGraphifyHint, graphifyStatus } from "../src/graphify.js";
+import { registerGraphifyTools } from "../src/tools/index.js";
+
+export default function (pi: ExtensionAPI) {
+  const config = loadConfig();
+
+  // ── 1. Notify and inject context when a graph is present ──────────
+  pi.on("session_start", async (_event, ctx) => {
+    const status = await graphifyStatus(ctx.cwd);
+    if (status.hasGraph && status.graphPath) {
+      ctx.ui.notify(`Graphify graph ready: ${status.graphPath}`, "info");
+    }
+  });
+
+  pi.on("before_agent_start", async (event, ctx) => {
+    const status = await graphifyStatus(ctx.cwd);
+    if (!status.hasGraph || !status.graphPath) {
+      return;
+    }
+
+    const hint = buildGraphifyHint(status.graphPath);
+    return {
+      systemPrompt: `${event.systemPrompt}\n\n${hint}`,
+    };
+  });
+
+  // ── 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");
+      }
+    },
+  });
+}

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "@wwjd/pi-graphify",
+  "version": "0.1.0",
+  "description": "Graphify knowledge graph integration for Pi coding agent",
+  "type": "module",
+  "license": "MIT",
+  "author": "WIAN <WIANVDM4@GMAIL.COM>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/WianVDM/pi-graphify.git"
+  },
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "pi",
+    "pi-coding-agent",
+    "graphify",
+    "graphs",
+    "knowledge-graph",
+    "visualization"
+  ],
+  "files": [
+    "src",
+    "extensions",
+    "docs",
+    "README.md",
+    "CHANGELOG.md",
+    "RELEASE.md",
+    "AGENTS.md",
+    "LICENSE",
+    "!.github"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "test": "echo \"No tests yet\" && exit 0",
+    "lint": "biome check .",
+    "lint:fix": "biome check --write .",
+    "format": "biome format --write .",
+    "typecheck": "tsc --noEmit"
+  },
+  "pi": {
+    "extensions": [
+      "./extensions"
+    ]
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-agent-core": "*",
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*",
+    "typebox": "*"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.4.14",
+    "@earendil-works/pi-ai": "^0.74.0",
+    "@earendil-works/pi-coding-agent": "^0.80.6",
+    "@types/node": "^20.0.0",
+    "typebox": "^1.1.24",
+    "typescript": "^5.0.0"
+  },
+  "dependencies": {
+    "chokidar": "^3.6.0"
+  }
+}

package/src/config.ts

@@ -0,0 +1,26 @@
+/**
+ * pi-graphify configuration
+ */
+
+export interface GraphifyConfig {
+  /** Whether to auto-watch source files and rebuild the graph. */
+  autoWatch: boolean;
+  /** Debounce window for file watcher events (ms). */
+  debounceMs: number;
+  /** Timeout for full graph builds (ms). */
+  buildTimeoutMs: number;
+  /** Timeout for graph queries (ms). */
+  queryTimeoutMs: number;
+  /** Timeout for short CLI calls like status checks (ms). */
+  shortTimeoutMs: number;
+}
+
+export function loadConfig(): GraphifyConfig {
+  return {
+    autoWatch: false,
+    debounceMs: 2000,
+    buildTimeoutMs: 300_000,
+    queryTimeoutMs: 30_000,
+    shortTimeoutMs: 10_000,
+  };
+}

package/src/graphify.ts

@@ -0,0 +1,98 @@
+/**
+ * Graphify CLI helpers
+ */
+
+import { execFile } from "node:child_process";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import type { GraphifyConfig } from "./config.js";
+
+export interface GraphifyResult {
+  stdout: string;
+  stderr: string;
+  exitCode: number;
+}
+
+export interface GraphStatus {
+  hasGraph: boolean;
+  graphPath?: string;
+  error?: string;
+}
+
+/** Best-effort resolve of the graphify CLI executable name. */
+export async function findGraphifyCli(): Promise<string> {
+  // Pi shells run with the user's PATH, so the bare command is usually enough.
+  // We try a platform-aware check first; if it fails, we fall back to "graphify".
+  const checkCmd = process.platform === "win32" ? "where" : "which";
+  const shell = process.platform === "win32" ? "cmd.exe" : undefined;
+
+  return new Promise((resolve) => {
+    execFile(checkCmd, ["graphify"], { shell }, (error, stdout) => {
+      if (error || !stdout.trim()) {
+        resolve("graphify");
+        return;
+      }
+      // Use the first match returned by where/which.
+      resolve(stdout.split("\n")[0].trim());
+    });
+  });
+}
+
+/** Run a graphify CLI command with a timeout. */
+export async function runGraphify(
+  args: string[],
+  cwd: string,
+  timeoutMs: number,
+): Promise<GraphifyResult> {
+  const cli = await findGraphifyCli();
+
+  return new Promise((resolve) => {
+    execFile(cli, args, { cwd, timeout: timeoutMs }, (error, stdout, stderr) => {
+      if (error) {
+        resolve({
+          stdout: stdout.trim(),
+          stderr: stderr.trim() || error.message,
+          exitCode: typeof error.code === "number" ? error.code : 1,
+        });
+        return;
+      }
+      resolve({
+        stdout: stdout.trim(),
+        stderr: stderr.trim(),
+        exitCode: 0,
+      });
+    });
+  });
+}
+
+/** Check whether a graph exists for the given project directory. */
+export async function graphifyStatus(cwd: string): Promise<GraphStatus> {
+  const graphPath = join(cwd, "graphify-out", "graph.json");
+
+  if (!existsSync(graphPath)) {
+    return { hasGraph: false };
+  }
+
+  return { hasGraph: true, graphPath };
+}
+
+/** Build a short system-prompt hint that the graph is available. */
+export function buildGraphifyHint(graphPath: string): string {
+  return [
+    "<graphify-context>",
+    `A Graphify knowledge graph is available at ${graphPath}.`,
+    "When answering questions about this codebase, prefer querying the graph via the graphify_status, graphify_query, graphify_path, and graphify_explain tools instead of grepping or reading raw files.",
+    "Only fall back to raw file reads when the graph lacks the needed detail or when modifying/debugging specific lines.",
+    "</graphify-context>",
+  ].join("\n");
+}
+
+/** Format a graphify CLI result for display. */
+export function formatResult(result: GraphifyResult): string {
+  if (result.exitCode === 0) {
+    return result.stdout;
+  }
+  return `graphify exited with code ${result.exitCode}\n${result.stderr || result.stdout}`.trim();
+}
+
+export type { GraphifyConfig };

package/src/tools/index.ts

@@ -0,0 +1,11 @@
+/**
+ * Tool registration barrel
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type { GraphifyConfig } from "../config.js";
+import { registerStatusTool } from "./status.js";
+
+export function registerGraphifyTools(pi: ExtensionAPI, config: GraphifyConfig): void {
+  registerStatusTool(pi, config);
+}

package/src/tools/status.ts

@@ -0,0 +1,43 @@
+/**
+ * Graphify status tool
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import type { GraphifyConfig } from "../config.js";
+import { graphifyStatus } from "../graphify.js";
+
+export function registerStatusTool(pi: ExtensionAPI, _config: GraphifyConfig): void {
+  pi.registerTool({
+    name: "graphify_status",
+    label: "Graphify Status",
+    description:
+      "Check whether a Graphify knowledge graph exists for the current project and whether the graphify CLI is available.",
+    parameters: Type.Object({}),
+    async execute(_toolCallId, _params, _signal, _onUpdate, ctx) {
+      const status = await graphifyStatus(ctx.cwd);
+
+      if (!status.hasGraph) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: "No Graphify graph found. Run /graphify-build to build one.",
+            },
+          ],
+          details: {},
+        };
+      }
+
+      return {
+        content: [
+          {
+            type: "text",
+            text: `Graphify graph is available at ${status.graphPath}.`,
+          },
+        ],
+        details: {},
+      };
+    },
+  });
+}