@wwjd/pi-graphify 0.2.0 → 0.4.0

package/src/commands/test-helpers.ts

@@ -0,0 +1,16 @@
+/**
+ * Shared test helpers for command tests.
+ */
+
+import { createMockBackend } from "../backends/mock.js";
+import { GraphifyCoordinator } from "../coordinator.js";
+
+export function createTestCoordinator(backend = createMockBackend()): GraphifyCoordinator {
+  return new GraphifyCoordinator({ cwd: process.cwd(), backend });
+}
+
+export function getCoordinator(
+  coordinator: GraphifyCoordinator | null,
+): () => GraphifyCoordinator | null {
+  return () => coordinator;
+}

package/src/commands/types.ts

@@ -0,0 +1,76 @@
+/**
+ * Shared types for Graphify slash commands.
+ *
+ * Command executors receive a narrow subset of ExtensionCommandContext so they
+ * are easy to test with mock contexts.
+ */
+
+import type { ExtensionCommandContext, ExtensionUIContext } from "@earendil-works/pi-coding-agent";
+import type { GraphifyCapabilities } from "../backends/types.js";
+import type { CoordinatorProvider } from "../coordinator.js";
+
+export type ExtensionMode = "tui" | "rpc" | "json" | "print";
+
+/** UI surface needed by command executors and the unified menu. */
+export interface CommandUIContext
+  extends Pick<ExtensionUIContext, "notify" | "input" | "select" | "custom"> {}
+
+/** Context passed to every command executor. */
+export interface CommandContext {
+  cwd: string;
+  ui: CommandUIContext;
+  hasUI: boolean;
+  mode: ExtensionMode;
+  isProjectTrusted(): boolean;
+}
+
+/** Function signature for a command executor. */
+export type CommandExecutor = (
+  ctx: CommandContext,
+  getCoordinator: CoordinatorProvider,
+  args: string,
+) => Promise<void>;
+
+/** How a command collects arguments from the unified menu. */
+export type CommandArgMode = "none" | "input" | "flags";
+
+/** Static metadata and runtime executor for one slash command. */
+export interface CommandDefinition {
+  /** Slash command name, e.g. "graphify-build". */
+  name: string;
+
+  /** Menu label, e.g. "Build graph". */
+  label: string;
+
+  /** Description shown in the menu and in Pi's command list. */
+  description: string;
+
+  /** Required Graphify capability. */
+  feature: keyof GraphifyCapabilities;
+
+  /** Usage string shown when arguments are invalid. */
+  usage: string;
+
+  /** How the menu collects arguments. */
+  argMode: CommandArgMode;
+
+  /** Title for ctx.ui.input when argMode is "input" or "flags". */
+  prompt?: string;
+
+  /** Placeholder for ctx.ui.input. */
+  placeholder?: string;
+
+  /** Execute the command with the given raw argument string. */
+  execute: CommandExecutor;
+}
+
+/** Narrow an ExtensionCommandContext to the CommandContext shape. */
+export function toCommandContext(ctx: ExtensionCommandContext): CommandContext {
+  return {
+    cwd: ctx.cwd,
+    ui: ctx.ui,
+    hasUI: ctx.hasUI,
+    mode: ctx.mode as ExtensionMode,
+    isProjectTrusted: ctx.isProjectTrusted,
+  };
+}

package/src/commands/version.ts

@@ -0,0 +1,40 @@
+/**
+ * /graphify-version — show the installed Graphify CLI version.
+ */
+
+import type { GraphifyCapabilities } from "../backends/types.js";
+import { formatErrorForCommand, formatResultForCommand } from "./format.js";
+import { requireCoordinatorWithCapability } from "./helpers.js";
+import type { CommandDefinition, CommandExecutor } from "./types.js";
+
+const FEATURE: keyof GraphifyCapabilities = "version";
+
+const executeVersion: CommandExecutor = async (ctx, getCoordinator) => {
+  if (!ctx.hasUI) return;
+
+  const coordinator = requireCoordinatorWithCapability(
+    ctx,
+    getCoordinator,
+    FEATURE,
+    "The installed Graphify version does not support version reporting.",
+  );
+  if (!coordinator) return;
+
+  try {
+    const result = await coordinator.getVersion();
+    ctx.ui.notify(formatResultForCommand(result), "info");
+  } catch (error) {
+    const { message, severity } = formatErrorForCommand(error);
+    ctx.ui.notify(message, severity);
+  }
+};
+
+export const versionCommand: CommandDefinition = {
+  name: "graphify-version",
+  label: "Graphify version",
+  description: "Show the installed Graphify CLI version",
+  feature: FEATURE,
+  usage: "",
+  argMode: "none",
+  execute: executeVersion,
+};

package/src/coordinator.ts

@@ -37,6 +37,8 @@ export interface GraphifyStatusResult {
 export interface CoordinatorOptions {
   cwd: string;
   config?: GraphifyConfig;
+  /** Optional backend, primarily for tests. */
+  backend?: GraphifyBackend;
 }
 
 export class GraphifyCoordinator {
@@ -49,6 +51,7 @@ export class GraphifyCoordinator {
   constructor(options: CoordinatorOptions) {
     this.cwd = options.cwd;
     this.config = options.config ?? loadConfig();
+    this.backend = options.backend ?? null;
   }
 
   async initialize(): Promise<void> {
@@ -57,11 +60,13 @@ export class GraphifyCoordinator {
     }
 
     try {
-      // Phase 2 only supports CLI backend. MCP is a Phase 6 addition.
-      this.backend = await createCliBackend({
-        cwd: this.cwd,
-        timeoutMs: this.config.queryTimeoutMs,
-      });
+      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(
@@ -176,6 +181,8 @@ export class GraphifyCoordinator {
   }
 }
 
+export type CoordinatorProvider = () => GraphifyCoordinator | null;
+
 /** Convenience factory. */
 export async function createGraphifyCoordinator(
   cwd: string,

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

@@ -33,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");

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);
+      }
+    },
+  });
+}

package/src/tools/format.ts

@@ -0,0 +1,25 @@
+/**
+ * Shared result formatting helpers for graphify tools.
+ */
+
+import type { GraphifyResult } from "../backends/types.js";
+import { GraphifyError } from "../errors.js";
+import { errorResult, successResult, type ToolResult } from "./types.js";
+
+/** Format a successful Graphify result into tool content. */
+export function formatGraphifyResult(result: GraphifyResult): ToolResult {
+  return successResult(result);
+}
+
+/** Format a Graphify or unexpected error into friendly tool content. */
+export function formatGraphifyError(error: unknown): ToolResult {
+  if (error instanceof GraphifyError) {
+    return errorResult(error.userMessage, { code: error.code, details: error.details });
+  }
+
+  if (error instanceof Error) {
+    return errorResult(error.message);
+  }
+
+  return errorResult(String(error));
+}

package/src/tools/index.ts

@@ -1,12 +1,89 @@
-/**
- * Tool registration barrel
- */
-
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type { GraphifyCapabilities } from "../backends/types.js";
+import type { CoordinatorProvider, GraphifyCoordinator } from "../coordinator.js";
+import { registerAffectedTool } from "./affected.js";
+import { registerBuildTool } from "./build.js";
+import { registerExplainTool } from "./explain.js";
+import { registerPathTool } from "./path.js";
+import { registerQueryTool } from "./query.js";
 import { registerStatusTool } from "./status.js";
+import { registerVersionTool } from "./version.js";
+
+export type { CoordinatorProvider } from "../coordinator.js";
+
+export interface RegisterToolsOptions {
+  /** Tracks tool names that have already been registered to prevent duplicates. */
+  registeredToolNames: Set<string>;
+}
+
+export function registerGraphifyTools(
+  pi: ExtensionAPI,
+  getCoordinator: CoordinatorProvider,
+  options: RegisterToolsOptions,
+): void {
+  const { registeredToolNames } = options;
+  const coordinator = getCoordinator();
+  if (!coordinator) {
+    return;
+  }
 
-export type CoordinatorProvider = () => import("../coordinator.js").GraphifyCoordinator | null;
+  registerToolIfSupported(coordinator, registeredToolNames, "graphify_status", () =>
+    registerStatusTool(pi, getCoordinator),
+  );
+  registerToolIfSupported(coordinator, registeredToolNames, "graphify_build", () =>
+    registerBuildTool(pi, getCoordinator),
+  );
+  registerToolIfSupported(coordinator, registeredToolNames, "graphify_query", () =>
+    registerQueryTool(pi, getCoordinator),
+  );
+  registerToolIfSupported(coordinator, registeredToolNames, "graphify_path", () =>
+    registerPathTool(pi, getCoordinator),
+  );
+  registerToolIfSupported(coordinator, registeredToolNames, "graphify_explain", () =>
+    registerExplainTool(pi, getCoordinator),
+  );
+  registerToolIfSupported(coordinator, registeredToolNames, "graphify_affected", () =>
+    registerAffectedTool(pi, getCoordinator),
+  );
+  registerToolIfSupported(coordinator, registeredToolNames, "graphify_version", () =>
+    registerVersionTool(pi, getCoordinator),
+  );
+}
+
+function registerToolIfSupported(
+  coordinator: GraphifyCoordinator,
+  registeredToolNames: Set<string>,
+  name: string,
+  register: () => void,
+): void {
+  if (registeredToolNames.has(name)) {
+    return;
+  }
+
+  const feature = nameToFeature(name);
+  if (feature && !coordinator.supports(feature)) {
+    return;
+  }
+
+  registeredToolNames.add(name);
+  register();
+}
 
-export function registerGraphifyTools(pi: ExtensionAPI, getCoordinator: CoordinatorProvider): void {
-  registerStatusTool(pi, getCoordinator);
+function nameToFeature(name: string): keyof GraphifyCapabilities | null {
+  switch (name) {
+    case "graphify_build":
+      return "build";
+    case "graphify_query":
+      return "query";
+    case "graphify_path":
+      return "path";
+    case "graphify_explain":
+      return "explain";
+    case "graphify_affected":
+      return "affected";
+    case "graphify_version":
+      return "version";
+    default:
+      return null;
+  }
 }

package/src/tools/path.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 registerPathTool(pi: ExtensionAPI, getCoordinator: CoordinatorProvider): void {
+  pi.registerTool({
+    name: "graphify_path",
+    label: "Graphify Path",
+    description:
+      "Trace the shortest path between two nodes (functions, files, tools, or concepts) in the Graphify knowledge graph.",
+    promptSnippet:
+      "Trace how two functions, files, tools, or concepts are connected in the knowledge graph",
+    promptGuidelines: [
+      "Use graphify_path when the user asks how two concepts, functions, files, tools, or symbols are related.",
+      "Use graphify_path instead of manually tracing code when both source and target are known nodes in the graph.",
+    ],
+    parameters: Type.Object({
+      cwd: Type.String({ description: "Working directory of the project to search." }),
+      source: Type.String({
+        minLength: 1,
+        description: "The source node or concept to start from.",
+      }),
+      target: Type.String({
+        minLength: 1,
+        description: "The target node or concept to find a path to.",
+      }),
+    }),
+    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.path({ ...params, cwd: ctx.cwd });
+        return formatGraphifyResult(result);
+      } catch (error) {
+        return formatGraphifyError(error);
+      }
+    },
+  });
+}

package/src/tools/query.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 registerQueryTool(pi: ExtensionAPI, getCoordinator: CoordinatorProvider): void {
+  pi.registerTool({
+    name: "graphify_query",
+    label: "Graphify Query",
+    description: "Ask a natural-language question against the Graphify knowledge graph.",
+    promptSnippet: "Ask a natural-language question about the project's knowledge graph",
+    promptGuidelines: [
+      "Use graphify_query when the user asks a broad question about the codebase.",
+      "Use graphify_query instead of grepping or reading files when a graph is available.",
+    ],
+    parameters: Type.Object({
+      cwd: Type.String({ description: "Working directory of the project to query." }),
+      question: Type.String({
+        minLength: 1,
+        description: "The natural-language question to run against 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.query({ ...params, cwd: ctx.cwd });
+        return formatGraphifyResult(result);
+      } catch (error) {
+        return formatGraphifyError(error);
+      }
+    },
+  });
+}

package/src/tools/status.ts

@@ -11,6 +11,11 @@ export function registerStatusTool(pi: ExtensionAPI, getCoordinator: Coordinator
     name: "graphify_status",
     label: "Graphify Status",
     description: "Check whether a Graphify knowledge graph exists for the current project.",
+    promptSnippet: "Check whether a Graphify knowledge graph exists for the current project",
+    promptGuidelines: [
+      "Use graphify_status when the user asks if a Graphify graph is available.",
+      "Use graphify_status before calling other graphify tools to confirm the graph exists.",
+    ],
     parameters: Type.Object({}),
     async execute(_toolCallId, _params, _signal, _onUpdate, ctx) {
       const coordinator = getCoordinator();
@@ -38,7 +43,7 @@ export function registerStatusTool(pi: ExtensionAPI, getCoordinator: Coordinator
           content: [
             {
               type: "text",
-              text: `No Graphify graph found. Run /graphify-build to build one.${cliNote}`,
+              text: `No Graphify graph found. Build one with \`graphify .\`.${cliNote}`,
             },
           ],
           details,