@wwjd/pi-graphify 0.1.0 → 0.3.0

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,11 +1,89 @@
-/**
- * Tool registration barrel
- */
-
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import type { GraphifyConfig } from "../config.js";
+import type { GraphifyCapabilities } from "../backends/types.js";
+import type { 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 = () => GraphifyCoordinator | null;
+
+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;
+  }
+
+  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, config: GraphifyConfig): void {
-  registerStatusTool(pi, config);
+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

@@ -4,39 +4,67 @@
 
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
-import type { GraphifyConfig } from "../config.js";
-import { graphifyStatus } from "../graphify.js";
+import type { CoordinatorProvider } from "./index.js";
 
-export function registerStatusTool(pi: ExtensionAPI, _config: GraphifyConfig): void {
+export function registerStatusTool(pi: ExtensionAPI, getCoordinator: CoordinatorProvider): 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.",
+    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 status = await graphifyStatus(ctx.cwd);
+      const coordinator = getCoordinator();
+      if (!coordinator) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: "Graphify is not initialized yet.",
+            },
+          ],
+          details: {},
+        };
+      }
+
+      const status = await coordinator.status({ cwd: ctx.cwd });
+      const details: Record<string, unknown> = {
+        hasGraph: status.hasGraph,
+        backendVersion: status.backendVersion,
+      };
 
       if (!status.hasGraph) {
+        const cliNote = status.backendVersion ? "" : " The Graphify CLI was not detected on PATH.";
         return {
           content: [
             {
               type: "text",
-              text: "No Graphify graph found. Run /graphify-build to build one.",
+              text: `No Graphify graph found. Build one with \`graphify .\`.${cliNote}`,
             },
           ],
-          details: {},
+          details,
         };
       }
 
+      const graphText = status.backendVersion
+        ? `Graphify graph is available at ${status.graphPath}.`
+        : `Graphify graph is available at ${status.graphPath}, but the Graphify CLI was not detected on PATH.`;
+
       return {
         content: [
           {
             type: "text",
-            text: `Graphify graph is available at ${status.graphPath}.`,
+            text: graphText,
           },
         ],
-        details: {},
+        details: {
+          ...details,
+          graphPath: status.graphPath,
+        },
       };
     },
   });

package/src/tools/tools.test.ts

@@ -0,0 +1,282 @@
+import assert from "node:assert";
+import { describe, it } from "node:test";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { allCapabilitiesEnabled, createMockBackend } from "../backends/mock.js";
+import { GraphifyCoordinator } from "../coordinator.js";
+import { GraphifyError } from "../errors.js";
+import { type RegisterToolsOptions, registerGraphifyTools } from "./index.js";
+
+interface ToolRecord {
+  name: string;
+  label: string;
+  description: string;
+  parameters: unknown;
+  execute: (
+    toolCallId: string,
+    params: unknown,
+    signal: unknown,
+    onUpdate: (content: unknown) => void,
+    ctx: { cwd: string },
+  ) => Promise<{ content: { type: string; text: string }[]; details: Record<string, unknown> }>;
+}
+
+interface MockPi {
+  tools: Record<string, ToolRecord>;
+  registerTool: (tool: ToolRecord) => void;
+}
+
+function createMockPi(): MockPi {
+  const tools: Record<string, ToolRecord> = {};
+  return {
+    tools,
+    registerTool: (tool: ToolRecord) => {
+      tools[tool.name] = tool;
+    },
+  };
+}
+
+function createTestCoordinator(backend = createMockBackend()): GraphifyCoordinator {
+  return new GraphifyCoordinator({ cwd: process.cwd(), backend });
+}
+
+function createRegisterOptions(): RegisterToolsOptions {
+  return { registeredToolNames: new Set<string>() };
+}
+
+const noopOnUpdate = (): void => {};
+
+const expectedTools = [
+  "graphify_status",
+  "graphify_build",
+  "graphify_query",
+  "graphify_path",
+  "graphify_explain",
+  "graphify_affected",
+  "graphify_version",
+];
+
+describe("registerGraphifyTools", () => {
+  it("registers all expected tools when all capabilities are enabled", () => {
+    const pi = createMockPi();
+    const coordinator = createTestCoordinator();
+    const options = createRegisterOptions();
+    registerGraphifyTools(pi as unknown as ExtensionAPI, () => coordinator, options);
+
+    for (const name of expectedTools) {
+      assert.ok(name in pi.tools, `expected tool ${name} to be registered`);
+    }
+  });
+
+  it("does not register tools when coordinator is null", () => {
+    const pi = createMockPi();
+    const options = createRegisterOptions();
+    registerGraphifyTools(pi as unknown as ExtensionAPI, () => null, options);
+
+    assert.equal(Object.keys(pi.tools).length, 0);
+  });
+
+  it("skips tools whose capabilities are disabled", () => {
+    const pi = createMockPi();
+    const capabilities = { ...allCapabilitiesEnabled(), build: false, query: false };
+    const backend = createMockBackend({ capabilities });
+    const coordinator = createTestCoordinator(backend);
+    const options = createRegisterOptions();
+    registerGraphifyTools(pi as unknown as ExtensionAPI, () => coordinator, options);
+
+    assert.ok(
+      !("graphify_build" in pi.tools),
+      "graphify_build should not be registered when build is unsupported",
+    );
+    assert.ok(
+      !("graphify_query" in pi.tools),
+      "graphify_query should not be registered when query is unsupported",
+    );
+    assert.ok(
+      "graphify_path" in pi.tools,
+      "graphify_path should be registered when path is supported",
+    );
+  });
+
+  it("prevents duplicate registration when called again with the same set", () => {
+    const pi = createMockPi();
+    const coordinator = createTestCoordinator();
+    const options = createRegisterOptions();
+
+    registerGraphifyTools(pi as unknown as ExtensionAPI, () => coordinator, options);
+    const firstCount = Object.keys(pi.tools).length;
+
+    registerGraphifyTools(pi as unknown as ExtensionAPI, () => coordinator, options);
+    const secondCount = Object.keys(pi.tools).length;
+
+    assert.equal(firstCount, expectedTools.length);
+    assert.equal(secondCount, expectedTools.length);
+  });
+});
+
+async function runTool(
+  pi: MockPi,
+  name: string,
+  params: Record<string, unknown>,
+  cwd: string,
+): Promise<{ content: { type: string; text: string }[]; details: Record<string, unknown> }> {
+  return pi.tools[name].execute("call-1", params, null, noopOnUpdate, { cwd });
+}
+
+describe("graphify_build", () => {
+  it("returns formatted result on success", async () => {
+    const pi = createMockPi();
+    const coordinator = createTestCoordinator();
+    registerGraphifyTools(
+      pi as unknown as ExtensionAPI,
+      () => coordinator,
+      createRegisterOptions(),
+    );
+    const result = await runTool(pi, "graphify_build", {}, process.cwd());
+
+    assert.equal(result.content[0].text, "ok: build");
+    assert.equal(result.details.exitCode, 0);
+    assert.equal(result.details.feature, "build");
+  });
+});
+
+describe("graphify_query", () => {
+  it("passes question and cwd to the coordinator", async () => {
+    const pi = createMockPi();
+    let captured: unknown = null;
+    const backend = createMockBackend({
+      run: async (_operation, options) => {
+        captured = options;
+        return {
+          stdout: "answer",
+          stderr: "",
+          exitCode: 0,
+          durationMs: 1,
+          backend: "cli",
+          feature: "query",
+        };
+      },
+    });
+    const coordinator = createTestCoordinator(backend);
+    registerGraphifyTools(
+      pi as unknown as ExtensionAPI,
+      () => coordinator,
+      createRegisterOptions(),
+    );
+    const result = await runTool(
+      pi,
+      "graphify_query",
+      { question: "how does auth work?" },
+      process.cwd(),
+    );
+
+    assert.equal(result.content[0].text, "answer");
+    assert.deepEqual(captured, { cwd: process.cwd(), question: "how does auth work?" });
+  });
+
+  it("is not registered when the coordinator is missing", () => {
+    const pi = createMockPi();
+    registerGraphifyTools(pi as unknown as ExtensionAPI, () => null, createRegisterOptions());
+    assert.equal("graphify_query" in pi.tools, false);
+  });
+
+  it("returns an error when the coordinator becomes null after registration", async () => {
+    const pi = createMockPi();
+    let coordinator: GraphifyCoordinator | null = createTestCoordinator();
+    registerGraphifyTools(
+      pi as unknown as ExtensionAPI,
+      () => coordinator,
+      createRegisterOptions(),
+    );
+
+    coordinator = null;
+    const result = await runTool(pi, "graphify_query", { question: "x" }, process.cwd());
+
+    assert.ok(result.content[0].text.includes("Graphify is not initialized"));
+  });
+});
+
+describe("graphify_path", () => {
+  it("returns formatted result on success", async () => {
+    const pi = createMockPi();
+    const coordinator = createTestCoordinator();
+    registerGraphifyTools(
+      pi as unknown as ExtensionAPI,
+      () => coordinator,
+      createRegisterOptions(),
+    );
+    const result = await runTool(pi, "graphify_path", { source: "a", target: "b" }, process.cwd());
+
+    assert.equal(result.content[0].text, "ok: path");
+  });
+});
+
+describe("graphify_explain", () => {
+  it("returns formatted result on success", async () => {
+    const pi = createMockPi();
+    const coordinator = createTestCoordinator();
+    registerGraphifyTools(
+      pi as unknown as ExtensionAPI,
+      () => coordinator,
+      createRegisterOptions(),
+    );
+    const result = await runTool(pi, "graphify_explain", { node: "auth" }, process.cwd());
+
+    assert.equal(result.content[0].text, "ok: explain");
+  });
+});
+
+describe("graphify_affected", () => {
+  it("returns formatted result on success", async () => {
+    const pi = createMockPi();
+    const coordinator = createTestCoordinator();
+    registerGraphifyTools(
+      pi as unknown as ExtensionAPI,
+      () => coordinator,
+      createRegisterOptions(),
+    );
+    const result = await runTool(
+      pi,
+      "graphify_affected",
+      { files: ["src/auth.ts"] },
+      process.cwd(),
+    );
+
+    assert.equal(result.content[0].text, "ok: affected");
+  });
+});
+
+describe("graphify_version", () => {
+  it("returns formatted version on success", async () => {
+    const pi = createMockPi();
+    const backend = createMockBackend({ version: "2.100.0" });
+    const coordinator = createTestCoordinator(backend);
+    registerGraphifyTools(
+      pi as unknown as ExtensionAPI,
+      () => coordinator,
+      createRegisterOptions(),
+    );
+    const result = await runTool(pi, "graphify_version", {}, process.cwd());
+
+    assert.equal(result.content[0].text, "2.100.0");
+  });
+});
+
+describe("tool error handling", () => {
+  it("returns friendly error when the backend throws GraphifyError", async () => {
+    const pi = createMockPi();
+    const backend = createMockBackend({
+      run: async () => {
+        throw new GraphifyError("QUERY", "graphify query failed");
+      },
+    });
+    const coordinator = createTestCoordinator(backend);
+    registerGraphifyTools(
+      pi as unknown as ExtensionAPI,
+      () => coordinator,
+      createRegisterOptions(),
+    );
+    const result = await runTool(pi, "graphify_query", { question: "x" }, process.cwd());
+
+    assert.ok(result.content[0].text.includes("graphify query failed"));
+  });
+});

package/src/tools/types.ts

@@ -0,0 +1,31 @@
+import type { GraphifyResult } from "../backends/types.js";
+
+export interface ToolContext {
+  cwd: string;
+}
+
+export interface TextContentItem {
+  type: "text";
+  text: string;
+}
+
+export interface ToolResult {
+  content: TextContentItem[];
+  details: Record<string, unknown>;
+}
+
+export function successResult(result: GraphifyResult): ToolResult {
+  return {
+    content: [{ type: "text", text: result.stdout || "Operation completed successfully." }],
+    details: {
+      exitCode: result.exitCode,
+      durationMs: result.durationMs,
+      backend: result.backend,
+      feature: result.feature,
+    },
+  };
+}
+
+export function errorResult(text: string, details: Record<string, unknown> = {}): ToolResult {
+  return { content: [{ type: "text", text: `Error: ${text}` }], details };
+}

package/src/tools/version.ts

@@ -0,0 +1,35 @@
+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 registerVersionTool(pi: ExtensionAPI, getCoordinator: CoordinatorProvider): void {
+  pi.registerTool({
+    name: "graphify_version",
+    label: "Graphify Version",
+    description: "Report the installed Graphify version and compatibility status.",
+    promptSnippet: "Report the installed Graphify CLI version and compatibility status",
+    promptGuidelines: [
+      "Use graphify_version when the user asks what version of Graphify is installed.",
+      "Use graphify_version to check whether the installed Graphify version is supported.",
+    ],
+    parameters: Type.Object({
+      cwd: Type.Optional(
+        Type.String({ description: "Optional working directory to check Graphify in." }),
+      ),
+    }),
+    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.getVersion({ cwd: ctx.cwd });
+        return formatGraphifyResult(result);
+      } catch (error) {
+        return formatGraphifyError(error);
+      }
+    },
+  });
+}