@wwjd/pi-graphify 0.1.0 → 0.3.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/backends/types.ts

@@ -0,0 +1,158 @@
+/**
+ * Backend abstraction types for pi-graphify.
+ *
+ * All Graphify operations go through the `GraphifyBackend` interface so the
+ * rest of the extension is agnostic to whether the CLI or MCP is used.
+ */
+
+export interface GraphifyCapabilities {
+  /** Core graph build. */
+  build: boolean;
+  /** Query the graph. */
+  query: boolean;
+  /** Shortest path between nodes. */
+  path: boolean;
+  /** Explain a node or relationship. */
+  explain: boolean;
+  /** Affected nodes/files. */
+  affected: boolean;
+  /** Add content to the graph. */
+  add: boolean;
+  /** Watch source files for changes. */
+  watch: boolean;
+  /** Reflect on graph structure. */
+  reflect: boolean;
+  /** MCP server support. */
+  mcp: boolean;
+  /** Graph status check. */
+  status: boolean;
+  /** Version reporting. */
+  version: boolean;
+  /** Directed graph support. */
+  directedGraph: boolean;
+  /** Incremental code-only updates. */
+  incrementalUpdate: boolean;
+  /** Semantic extraction beyond code. */
+  semanticExtraction: boolean;
+}
+
+/** Normalized result from any Graphify backend. */
+export interface GraphifyResult {
+  stdout: string;
+  stderr: string;
+  exitCode: number;
+  durationMs: number;
+  backend: "cli" | "mcp";
+  feature: string;
+}
+
+/** Backend-agnostic interface for all Graphify operations. */
+export interface GraphifyBackend {
+  readonly type: "cli" | "mcp";
+  readonly version: string | null;
+  readonly capabilities: GraphifyCapabilities;
+
+  /**
+   * Run a Graphify operation.
+   *
+   * @param operation - The operation name, e.g. `"build"`, `"query"`, `"status"`.
+   * @param options - Operation-specific options.
+   */
+  run(operation: string, options: unknown): Promise<GraphifyResult>;
+
+  /** Optional cleanup hook called on session shutdown. */
+  close?(): Promise<void>;
+}
+
+/** Options for the `status` operation. */
+export interface StatusOptions {
+  cwd: string;
+}
+
+/** Options for the `version` operation. */
+export interface VersionOptions {
+  cwd?: string;
+}
+
+/** Options for the `build` operation. */
+export interface BuildOptions {
+  cwd: string;
+  codeOnly?: boolean;
+  update?: boolean;
+  directed?: boolean;
+}
+
+/** Options for the `query` operation. */
+export interface QueryOptions {
+  cwd: string;
+  question: string;
+}
+
+/** Options for the `path` operation. */
+export interface PathOptions {
+  cwd: string;
+  source: string;
+  target: string;
+}
+
+/** Options for the `explain` operation. */
+export interface ExplainOptions {
+  cwd: string;
+  node: string;
+}
+
+/** Options for the `affected` operation. */
+export interface AffectedOptions {
+  cwd: string;
+  files: string[];
+}
+
+/** Options for the `add` operation. */
+export interface AddOptions {
+  cwd: string;
+  paths: string[];
+}
+
+/** Options for the `watch` operation. */
+export interface WatchOptions {
+  cwd: string;
+  codeOnly?: boolean;
+}
+
+/** Options for the `reflect` operation. */
+export interface ReflectOptions {
+  cwd: string;
+  question?: string;
+}
+
+/** All operation option types unioned together. */
+export type GraphifyOperationOptions =
+  | StatusOptions
+  | VersionOptions
+  | BuildOptions
+  | QueryOptions
+  | PathOptions
+  | ExplainOptions
+  | AffectedOptions
+  | AddOptions
+  | WatchOptions
+  | ReflectOptions;
+
+export function allCapabilitiesDisabled(): GraphifyCapabilities {
+  return {
+    build: false,
+    query: false,
+    path: false,
+    explain: false,
+    affected: false,
+    add: false,
+    watch: false,
+    reflect: false,
+    mcp: false,
+    status: false,
+    version: false,
+    directedGraph: false,
+    incrementalUpdate: false,
+    semanticExtraction: false,
+  };
+}

package/src/coordinator.ts

@@ -0,0 +1,192 @@
+/**
+ * GraphifyCoordinator — the single entry point for all Graphify operations.
+ *
+ * The coordinator loads configuration, selects a backend, detects the installed
+ * Graphify version, builds a capability matrix, and routes tool/command
+ * requests to the backend. It also normalizes backend results and errors.
+ */
+
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { createCliBackend } from "./backends/cli.js";
+import {
+  type AddOptions,
+  type AffectedOptions,
+  allCapabilitiesDisabled,
+  type BuildOptions,
+  type ExplainOptions,
+  type GraphifyBackend,
+  type GraphifyCapabilities,
+  type GraphifyResult,
+  type PathOptions,
+  type QueryOptions,
+  type ReflectOptions,
+  type StatusOptions,
+  type VersionOptions,
+  type WatchOptions,
+} from "./backends/types.js";
+import { type GraphifyConfig, loadConfig } from "./config.js";
+import { codeForOperation, GraphifyError, messageForCliFailure } from "./errors.js";
+
+export interface GraphifyStatusResult {
+  hasGraph: boolean;
+  graphPath?: string;
+  backendVersion: string | null;
+}
+
+export interface CoordinatorOptions {
+  cwd: string;
+  config?: GraphifyConfig;
+  /** Optional backend, primarily for tests. */
+  backend?: GraphifyBackend;
+}
+
+export class GraphifyCoordinator {
+  readonly config: GraphifyConfig;
+  readonly cwd: string;
+  private backend: GraphifyBackend | null = null;
+  private readonly _warnings: string[] = [];
+  private closed = false;
+
+  constructor(options: CoordinatorOptions) {
+    this.cwd = options.cwd;
+    this.config = options.config ?? loadConfig();
+    this.backend = options.backend ?? null;
+  }
+
+  async initialize(): Promise<void> {
+    if (this.closed) {
+      throw new GraphifyError("UNKNOWN", "Coordinator has already been closed");
+    }
+
+    try {
+      if (!this.backend) {
+        // Phase 2 only supports CLI backend. MCP is a Phase 6 addition.
+        this.backend = await createCliBackend({
+          cwd: this.cwd,
+          timeoutMs: this.config.queryTimeoutMs,
+        });
+      }
+    } catch (error) {
+      this.backend = null;
+      this._warnings.push(
+        error instanceof Error ? error.message : "Graphify backend failed to initialize",
+      );
+    }
+  }
+
+  get version(): string | null {
+    return this.backend?.version ?? null;
+  }
+
+  get capabilities(): GraphifyCapabilities {
+    return this.backend?.capabilities ?? allCapabilitiesDisabled();
+  }
+
+  get warnings(): readonly string[] {
+    return this._warnings;
+  }
+
+  supports(feature: keyof GraphifyCapabilities): boolean {
+    return this.capabilities[feature] ?? false;
+  }
+
+  async status(_options: StatusOptions): Promise<GraphifyStatusResult> {
+    const graphPath = join(this.cwd, "graphify-out", "graph.json");
+    return {
+      hasGraph: existsSync(graphPath),
+      graphPath,
+      backendVersion: this.version,
+    };
+  }
+
+  async getVersion(_options?: VersionOptions): Promise<GraphifyResult> {
+    if (!this.backend) {
+      throw new GraphifyError("MISSING", "Graphify is not installed or not available on PATH.");
+    }
+    return {
+      stdout: this.version ?? "unknown",
+      stderr: "",
+      exitCode: 0,
+      durationMs: 0,
+      backend: "cli",
+      feature: "version",
+    };
+  }
+
+  async build(options: BuildOptions): Promise<GraphifyResult> {
+    return this.runWithFeature("build", options);
+  }
+
+  async query(options: QueryOptions): Promise<GraphifyResult> {
+    return this.runWithFeature("query", options);
+  }
+
+  async path(options: PathOptions): Promise<GraphifyResult> {
+    return this.runWithFeature("path", options);
+  }
+
+  async explain(options: ExplainOptions): Promise<GraphifyResult> {
+    return this.runWithFeature("explain", options);
+  }
+
+  async affected(options: AffectedOptions): Promise<GraphifyResult> {
+    return this.runWithFeature("affected", options);
+  }
+
+  async add(options: AddOptions): Promise<GraphifyResult> {
+    return this.runWithFeature("add", options);
+  }
+
+  async watch(options: WatchOptions): Promise<GraphifyResult> {
+    return this.runWithFeature("watch", options);
+  }
+
+  async reflect(options: ReflectOptions): Promise<GraphifyResult> {
+    return this.runWithFeature("reflect", options);
+  }
+
+  async close(): Promise<void> {
+    this.closed = true;
+    if (this.backend?.close) {
+      await this.backend.close();
+    }
+    this.backend = null;
+  }
+
+  private async runWithFeature(
+    operation: keyof GraphifyCapabilities,
+    options: unknown,
+  ): Promise<GraphifyResult> {
+    if (!this.backend) {
+      throw new GraphifyError("MISSING", `Graphify is not available. Cannot run ${operation}.`);
+    }
+
+    if (!this.supports(operation)) {
+      throw new GraphifyError(
+        "VERSION",
+        `The installed Graphify version does not support "${operation}".`,
+      );
+    }
+
+    const result = await this.backend.run(operation, options);
+    if (result.exitCode !== 0) {
+      throw new GraphifyError(
+        codeForOperation(operation),
+        messageForCliFailure(operation, result.exitCode, result.stderr),
+        { exitCode: result.exitCode, stderr: result.stderr },
+      );
+    }
+    return result;
+  }
+}
+
+/** Convenience factory. */
+export async function createGraphifyCoordinator(
+  cwd: string,
+  config?: GraphifyConfig,
+): Promise<GraphifyCoordinator> {
+  const coordinator = new GraphifyCoordinator({ cwd, config });
+  await coordinator.initialize();
+  return coordinator;
+}

package/src/errors.ts

@@ -0,0 +1,67 @@
+/**
+ * Normalized error handling for pi-graphify.
+ */
+
+export type GraphifyErrorCode =
+  | "MISSING"
+  | "VERSION"
+  | "BUILD"
+  | "QUERY"
+  | "PATH"
+  | "EXPLAIN"
+  | "AFFECTED"
+  | "ADD"
+  | "WATCH"
+  | "REFLECT"
+  | "TIMEOUT"
+  | "MCP"
+  | "UNKNOWN";
+
+export class GraphifyError extends Error {
+  readonly code: GraphifyErrorCode;
+  readonly details: Record<string, unknown>;
+  readonly userMessage: string;
+
+  constructor(code: GraphifyErrorCode, userMessage: string, details: Record<string, unknown> = {}) {
+    super(userMessage);
+    this.code = code;
+    this.userMessage = userMessage;
+    this.details = details;
+    this.name = "GraphifyError";
+  }
+}
+
+/** Map a Graphify operation name to an error code. */
+export function codeForOperation(operation: string): GraphifyErrorCode {
+  switch (operation) {
+    case "build":
+      return "BUILD";
+    case "query":
+      return "QUERY";
+    case "path":
+      return "PATH";
+    case "explain":
+      return "EXPLAIN";
+    case "affected":
+      return "AFFECTED";
+    case "add":
+      return "ADD";
+    case "watch":
+      return "WATCH";
+    case "reflect":
+      return "REFLECT";
+    case "mcp":
+      return "MCP";
+    default:
+      return "UNKNOWN";
+  }
+}
+
+/** Build a user-friendly message from a backend result. */
+export function messageForCliFailure(operation: string, exitCode: number, stderr: string): string {
+  const trimmed = stderr.trim();
+  if (trimmed) {
+    return `graphify ${operation} failed (exit ${exitCode}): ${trimmed}`;
+  }
+  return `graphify ${operation} failed with exit code ${exitCode}`;
+}

package/src/extensions/extension-load.test.ts

@@ -0,0 +1,15 @@
+import assert from "node:assert";
+import { describe, it } from "node:test";
+
+/**
+ * Smoke test that verifies the extension entry point module loads and exports a
+ * valid factory function. This catches syntax errors, import issues, or jiti
+ * problems without requiring the full Pi runtime.
+ */
+describe("extension entry point", () => {
+  it("exports a default factory function", async () => {
+    const module = await import("../../extensions/index.js");
+    assert.equal(typeof module.default, "function");
+    assert.equal(module.default.length, 1);
+  });
+});

package/src/graphify.ts

@@ -1,72 +1,23 @@
 /**
- * Graphify CLI helpers
+ * High-level Graphify helpers used by the extension and tools.
+ *
+ * CLI execution has moved to `src/backends/cli.ts`. This module retains:
+ *   - graph existence checks
+ *   - system-prompt hint construction
+ *   - result formatting utilities
  */
 
-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;
-}
+import type { GraphifyResult } from "./backends/types.js";
 
 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> {
+export function graphifyStatus(cwd: string): GraphStatus {
   const graphPath = join(cwd, "graphify-out", "graph.json");
 
   if (!existsSync(graphPath)) {
@@ -82,6 +33,8 @@ export function buildGraphifyHint(graphPath: string): string {
     "<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.",
+    "Use graphify_explain to explain a specific function, file, tool, or concept that is a node in the graph.",
+    "Use graphify_path to trace how two functions, files, tools, or concepts are connected in the graph.",
     "Only fall back to raw file reads when the graph lacks the needed detail or when modifying/debugging specific lines.",
     "</graphify-context>",
   ].join("\n");
@@ -94,5 +47,3 @@ export function formatResult(result: GraphifyResult): string {
   }
   return `graphify exited with code ${result.exitCode}\n${result.stderr || result.stdout}`.trim();
 }
-
-export type { GraphifyConfig };

package/src/tools/affected.ts

@@ -0,0 +1,37 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import { GraphifyError } from "../errors.js";
+import { formatGraphifyError, formatGraphifyResult } from "./format.js";
+import type { CoordinatorProvider } from "./index.js";
+
+export function registerAffectedTool(pi: ExtensionAPI, getCoordinator: CoordinatorProvider): void {
+  pi.registerTool({
+    name: "graphify_affected",
+    label: "Graphify Affected",
+    description: "Show the blast radius of changes to the given files or nodes.",
+    promptSnippet: "Show what files, nodes, or concepts depend on the given files or nodes",
+    promptGuidelines: [
+      "Use graphify_affected when the user asks what would break if they change a file or node.",
+      "Use graphify_affected to find downstream dependents of a file or concept before refactoring.",
+    ],
+    parameters: Type.Object({
+      cwd: Type.String({ description: "Working directory of the project to analyze." }),
+      files: Type.Array(Type.String({ minLength: 1 }), {
+        minItems: 1,
+        description: "The files or nodes whose downstream dependents should be reported.",
+      }),
+    }),
+    async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+      const coordinator = getCoordinator();
+      if (!coordinator) {
+        return formatGraphifyError(new GraphifyError("MISSING", "Graphify is not initialized."));
+      }
+      try {
+        const result = await coordinator.affected({ ...params, cwd: ctx.cwd });
+        return formatGraphifyResult(result);
+      } catch (error) {
+        return formatGraphifyError(error);
+      }
+    },
+  });
+}

package/src/tools/build.ts

@@ -0,0 +1,43 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import { GraphifyError } from "../errors.js";
+import { formatGraphifyError, formatGraphifyResult } from "./format.js";
+import type { CoordinatorProvider } from "./index.js";
+
+export function registerBuildTool(pi: ExtensionAPI, getCoordinator: CoordinatorProvider): void {
+  pi.registerTool({
+    name: "graphify_build",
+    label: "Graphify Build",
+    description:
+      "Build or incrementally update the Graphify knowledge graph for the current project.",
+    promptSnippet: "Build or update the project's Graphify knowledge graph",
+    promptGuidelines: [
+      "Use graphify_build when the user wants to create or update the knowledge graph.",
+      "Use graphify_build when graphify_status reports that no graph exists.",
+    ],
+    parameters: Type.Object({
+      cwd: Type.String({ description: "Working directory of the project to build the graph for." }),
+      codeOnly: Type.Optional(
+        Type.Boolean({ description: "Only index code files; skip semantic extraction." }),
+      ),
+      update: Type.Optional(
+        Type.Boolean({ description: "Perform an incremental update instead of a full rebuild." }),
+      ),
+      directed: Type.Optional(
+        Type.Boolean({ description: "Build a directed graph instead of an undirected one." }),
+      ),
+    }),
+    async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+      const coordinator = getCoordinator();
+      if (!coordinator) {
+        return formatGraphifyError(new GraphifyError("MISSING", "Graphify is not initialized."));
+      }
+      try {
+        const result = await coordinator.build({ ...params, cwd: ctx.cwd });
+        return formatGraphifyResult(result);
+      } catch (error) {
+        return formatGraphifyError(error);
+      }
+    },
+  });
+}

package/src/tools/explain.ts

@@ -0,0 +1,38 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import { GraphifyError } from "../errors.js";
+import { formatGraphifyError, formatGraphifyResult } from "./format.js";
+import type { CoordinatorProvider } from "./index.js";
+
+export function registerExplainTool(pi: ExtensionAPI, getCoordinator: CoordinatorProvider): void {
+  pi.registerTool({
+    name: "graphify_explain",
+    label: "Graphify Explain",
+    description:
+      "Explain how a specific node (function, file, tool, or concept) is connected in the Graphify knowledge graph.",
+    promptSnippet: "Explain a function, file, tool, or concept from the project's knowledge graph",
+    promptGuidelines: [
+      "Use graphify_explain when the user asks what a specific function, file, tool, or concept does.",
+      "Use graphify_explain instead of reading source code when the subject is a node in the knowledge graph.",
+    ],
+    parameters: Type.Object({
+      cwd: Type.String({ description: "Working directory of the project to explain." }),
+      node: Type.String({
+        minLength: 1,
+        description: "The node or concept to explain in the graph.",
+      }),
+    }),
+    async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+      const coordinator = getCoordinator();
+      if (!coordinator) {
+        return formatGraphifyError(new GraphifyError("MISSING", "Graphify is not initialized."));
+      }
+      try {
+        const result = await coordinator.explain({ ...params, cwd: ctx.cwd });
+        return formatGraphifyResult(result);
+      } catch (error) {
+        return formatGraphifyError(error);
+      }
+    },
+  });
+}