@wwjd/pi-graphify 0.3.0 → 0.4.0

package/src/commands/menu.test.ts

@@ -0,0 +1,266 @@
+/**
+ * Tests for the unified /graphify menu.
+ */
+
+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 { buildMenuItems, registerGraphifyMenuCommand } from "./menu.js";
+import { queryCommand } from "./query.js";
+import { graphifyCommands } from "./registry.js";
+import { createTestCoordinator, getCoordinator } from "./test-helpers.js";
+import type { CommandContext } from "./types.js";
+import { versionCommand } from "./version.js";
+
+interface Notification {
+  message: string;
+  type?: "info" | "warning" | "error";
+}
+
+interface MockUi {
+  notifications: Notification[];
+  selectCalls: Array<{ title: string; options: string[] }>;
+  inputCalls: Array<{ title: string; placeholder?: string }>;
+  customCalls: unknown[];
+  customResult: string | null;
+  selectResult: string | undefined;
+  inputResult: string | undefined;
+}
+
+interface MockContextResult {
+  ctx: CommandContext;
+  ui: MockUi;
+}
+
+function createMockContext(overrides: Partial<CommandContext> = {}): MockContextResult {
+  const ui: MockUi = {
+    notifications: [],
+    selectCalls: [],
+    inputCalls: [],
+    customCalls: [],
+    customResult: null,
+    selectResult: undefined,
+    inputResult: undefined,
+  };
+
+  const ctx: CommandContext = {
+    cwd: process.cwd(),
+    hasUI: true,
+    mode: "tui",
+    isProjectTrusted: () => true,
+    ui: {
+      notify: (message, type) => ui.notifications.push({ message, type }),
+      input: async (title, placeholder) => {
+        ui.inputCalls.push({ title, placeholder });
+        return ui.inputResult;
+      },
+      select: async (title, options) => {
+        ui.selectCalls.push({ title, options });
+        return ui.selectResult;
+      },
+      custom: async (factory) => {
+        ui.customCalls.push(factory);
+        return ui.customResult as never;
+      },
+    },
+    ...overrides,
+  };
+
+  return { ctx, ui };
+}
+
+interface CommandHandler {
+  description?: string;
+  handler: (args: string, ctx: unknown) => Promise<void>;
+}
+
+interface MockPi {
+  commands: Record<string, CommandHandler>;
+  registerCommand: (name: string, options: CommandHandler) => void;
+}
+
+function createMockPi(): MockPi {
+  const commands: MockPi["commands"] = {};
+  return {
+    commands,
+    registerCommand: (name, options) => {
+      commands[name] = options;
+    },
+  };
+}
+
+function invokeHandler(pi: MockPi, ctx: CommandContext): Promise<void> {
+  return pi.commands.graphify.handler(
+    "",
+    ctx as unknown as Parameters<CommandHandler["handler"]>[1],
+  );
+}
+
+describe("registerGraphifyMenuCommand", () => {
+  it("registers /graphify", () => {
+    const pi = createMockPi();
+    registerGraphifyMenuCommand(pi as unknown as ExtensionAPI, () => null);
+
+    assert.ok("graphify" in pi.commands);
+    assert.equal(pi.commands.graphify.description, "Open the Graphify command menu");
+  });
+});
+
+describe("buildMenuItems", () => {
+  it("maps commands to SelectItem values", () => {
+    const items = buildMenuItems(graphifyCommands);
+
+    assert.equal(items.length, graphifyCommands.length);
+    for (const command of graphifyCommands) {
+      assert.ok(items.some((item) => item.value === command.name && item.label === command.label));
+    }
+  });
+});
+
+describe("showGraphifyMenu TUI mode", () => {
+  it("calls ctx.ui.custom when commands are available", async () => {
+    const { ctx, ui } = createMockContext();
+    ui.customResult = "graphify-status";
+    const coordinator = createTestCoordinator();
+    const pi = createMockPi();
+    registerGraphifyMenuCommand(pi as unknown as ExtensionAPI, getCoordinator(coordinator));
+    await invokeHandler(pi, ctx);
+
+    assert.equal(ui.customCalls.length, 1);
+    assert.equal(ui.notifications.length, 1);
+    assert.ok(ui.notifications[0].message.includes("Graphify graph ready"));
+  });
+
+  it("renders the menu with the correct items", () => {
+    const { ctx, ui } = createMockContext();
+    const coordinator = createTestCoordinator();
+    const pi = createMockPi();
+    registerGraphifyMenuCommand(pi as unknown as ExtensionAPI, getCoordinator(coordinator));
+    invokeHandler(pi, ctx);
+
+    const factory = ui.customCalls[0] as (
+      tui: unknown,
+      theme: unknown,
+      kb: unknown,
+      done: (value: string | null) => void,
+    ) => { render: (width: number) => string[] };
+    const mockTheme = {
+      fg: (_color: string, text: string) => text,
+      bold: (text: string) => text,
+    };
+    const component = factory({ requestRender: () => {} }, mockTheme, {}, () => {});
+    const lines = component.render(80);
+
+    for (const command of graphifyCommands) {
+      assert.ok(
+        lines.some((line) => line.includes(command.label)),
+        `expected menu to contain ${command.label}`,
+      );
+    }
+  });
+
+  it("warns when no commands are available", async () => {
+    const { ctx, ui } = createMockContext();
+    const backend = createMockBackend({
+      capabilities: {
+        ...allCapabilitiesEnabled(),
+        build: false,
+        query: false,
+        path: false,
+        explain: false,
+        affected: false,
+        status: false,
+        version: false,
+      },
+    });
+    const coordinator = createTestCoordinator(backend);
+    const pi = createMockPi();
+    registerGraphifyMenuCommand(pi as unknown as ExtensionAPI, getCoordinator(coordinator));
+    await invokeHandler(pi, ctx);
+
+    assert.equal(ui.customCalls.length, 0);
+    assert.equal(ui.notifications[0].type, "warning");
+    assert.ok(ui.notifications[0].message.includes("No Graphify commands are available"));
+  });
+
+  it("cancels without executing when custom returns null", async () => {
+    const { ctx, ui } = createMockContext();
+    ui.customResult = null;
+    const coordinator = createTestCoordinator();
+    const pi = createMockPi();
+    registerGraphifyMenuCommand(pi as unknown as ExtensionAPI, getCoordinator(coordinator));
+    await invokeHandler(pi, ctx);
+
+    assert.equal(ui.customCalls.length, 1);
+    assert.equal(ui.notifications.length, 0);
+  });
+
+  it("prompts for input and executes arg commands", async () => {
+    const { ctx, ui } = createMockContext();
+    ui.customResult = "graphify-query";
+    ui.inputResult = "how does auth work?";
+    const coordinator = createTestCoordinator();
+    const pi = createMockPi();
+    registerGraphifyMenuCommand(pi as unknown as ExtensionAPI, getCoordinator(coordinator));
+    await invokeHandler(pi, ctx);
+
+    assert.equal(ui.inputCalls.length, 1);
+    assert.equal(ui.inputCalls[0].title, queryCommand.prompt);
+    assert.equal(ui.notifications[0].message, "ok: query");
+  });
+
+  it("cancels when input is cancelled", async () => {
+    const { ctx, ui } = createMockContext();
+    ui.customResult = "graphify-query";
+    ui.inputResult = undefined;
+    const coordinator = createTestCoordinator();
+    const pi = createMockPi();
+    registerGraphifyMenuCommand(pi as unknown as ExtensionAPI, getCoordinator(coordinator));
+    await invokeHandler(pi, ctx);
+
+    assert.equal(ui.inputCalls.length, 1);
+    assert.equal(ui.notifications.length, 0);
+  });
+});
+
+describe("showGraphifyMenu RPC mode", () => {
+  it("uses ctx.ui.select when in rpc mode", async () => {
+    const { ctx, ui } = createMockContext({ mode: "rpc" });
+    ui.selectResult = `${versionCommand.label}: ${versionCommand.description}`;
+    const coordinator = createTestCoordinator();
+    const pi = createMockPi();
+    registerGraphifyMenuCommand(pi as unknown as ExtensionAPI, getCoordinator(coordinator));
+    await invokeHandler(pi, ctx);
+
+    assert.equal(ui.selectCalls.length, 1);
+    assert.equal(ui.selectCalls[0].title, "Graphify");
+    assert.equal(ui.notifications[0].message, "2.100.0");
+  });
+
+  it("does not execute when select is cancelled", async () => {
+    const { ctx, ui } = createMockContext({ mode: "rpc" });
+    ui.selectResult = undefined;
+    const coordinator = createTestCoordinator();
+    const pi = createMockPi();
+    registerGraphifyMenuCommand(pi as unknown as ExtensionAPI, getCoordinator(coordinator));
+    await invokeHandler(pi, ctx);
+
+    assert.equal(ui.selectCalls.length, 1);
+    assert.equal(ui.notifications.length, 0);
+  });
+});
+
+describe("showGraphifyMenu non-UI mode", () => {
+  it("returns silently when hasUI is false", async () => {
+    const { ctx, ui } = createMockContext({ hasUI: false });
+    const coordinator = createTestCoordinator();
+    const pi = createMockPi();
+    registerGraphifyMenuCommand(pi as unknown as ExtensionAPI, getCoordinator(coordinator));
+    await invokeHandler(pi, ctx);
+
+    assert.equal(ui.customCalls.length, 0);
+    assert.equal(ui.selectCalls.length, 0);
+    assert.equal(ui.notifications.length, 0);
+  });
+});

package/src/commands/menu.ts

@@ -0,0 +1,150 @@
+/**
+ * /graphify — unified command menu.
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { DynamicBorder } from "@earendil-works/pi-coding-agent";
+import { Container, type SelectItem, SelectList, Text } from "@earendil-works/pi-tui";
+import type { CoordinatorProvider } from "../coordinator.js";
+import { getAvailableCommands, graphifyCommands } from "./registry.js";
+import type { CommandContext, CommandDefinition } from "./types.js";
+import { toCommandContext } from "./types.js";
+
+const MAX_MENU_VISIBLE_ITEMS = 10;
+
+export function registerGraphifyMenuCommand(
+  pi: ExtensionAPI,
+  getCoordinator: CoordinatorProvider,
+): void {
+  pi.registerCommand("graphify", {
+    description: "Open the Graphify command menu",
+    handler: async (_args, ctx) => {
+      const commandCtx = toCommandContext(ctx);
+      await showGraphifyMenu(commandCtx, getCoordinator);
+    },
+  });
+}
+
+async function showGraphifyMenu(
+  ctx: CommandContext,
+  getCoordinator: CoordinatorProvider,
+): Promise<void> {
+  if (!ctx.hasUI) return;
+
+  const coordinator = getCoordinator();
+  if (!coordinator) {
+    ctx.ui.notify("Graphify is not initialized.", "warning");
+    return;
+  }
+
+  const availableCommands = getAvailableCommands(coordinator, graphifyCommands);
+  if (availableCommands.length === 0) {
+    ctx.ui.notify("No Graphify commands are available for this installation.", "warning");
+    return;
+  }
+
+  const selectedName = await selectCommandName(ctx, availableCommands);
+  await runSelectedCommand(ctx, getCoordinator, availableCommands, selectedName);
+}
+
+async function selectCommandName(
+  ctx: CommandContext,
+  availableCommands: CommandDefinition[],
+): Promise<string | null | undefined> {
+  if (ctx.mode === "tui") return showTuiMenu(ctx, availableCommands);
+  if (ctx.mode === "rpc") return showRpcMenu(ctx, availableCommands);
+  return undefined;
+}
+
+async function runSelectedCommand(
+  ctx: CommandContext,
+  getCoordinator: CoordinatorProvider,
+  availableCommands: CommandDefinition[],
+  selectedName: string | null | undefined,
+): Promise<void> {
+  if (!selectedName) return;
+  await executeMenuChoice(ctx, getCoordinator, availableCommands, selectedName);
+}
+
+async function showTuiMenu(
+  ctx: CommandContext,
+  availableCommands: CommandDefinition[],
+): Promise<string | null> {
+  const items = buildMenuItems(availableCommands);
+
+  return ctx.ui.custom<string | null>(
+    (tui, theme, _kb, done) => {
+      const container = new Container();
+      container.addChild(new DynamicBorder((str) => theme.fg("accent", str)));
+      container.addChild(new Text(theme.fg("accent", theme.bold(" Graphify "))));
+
+      const selectList = new SelectList(items, Math.min(items.length, MAX_MENU_VISIBLE_ITEMS), {
+        selectedPrefix: (text) => theme.fg("accent", text),
+        selectedText: (text) => theme.fg("accent", text),
+        description: (text) => theme.fg("muted", text),
+        scrollInfo: (text) => theme.fg("dim", text),
+        noMatch: (text) => theme.fg("warning", text),
+      });
+
+      selectList.onSelect = (item) => done(item.value);
+      selectList.onCancel = () => done(null);
+      container.addChild(selectList);
+      container.addChild(new Text(theme.fg("dim", "↑↓ navigate • enter select • esc cancel")));
+      container.addChild(new DynamicBorder((str) => theme.fg("accent", str)));
+
+      return {
+        render: (width) => container.render(width),
+        invalidate: () => container.invalidate(),
+        handleInput: (data) => {
+          selectList.handleInput(data);
+          tui.requestRender();
+        },
+      };
+    },
+    { overlay: true },
+  );
+}
+
+async function showRpcMenu(
+  ctx: CommandContext,
+  availableCommands: CommandDefinition[],
+): Promise<string | undefined> {
+  const choices = availableCommands.map((command) => ({
+    label: `${command.label}: ${command.description}`,
+    value: command.name,
+  }));
+  const labels = choices.map((c) => c.label);
+  const selectedLabel = await ctx.ui.select("Graphify", labels);
+  return choices.find((c) => c.label === selectedLabel)?.value;
+}
+
+export function buildMenuItems(availableCommands: CommandDefinition[]): SelectItem[] {
+  return availableCommands.map((command) => ({
+    value: command.name,
+    label: command.label,
+    description: command.description,
+  }));
+}
+
+async function executeMenuChoice(
+  ctx: CommandContext,
+  getCoordinator: CoordinatorProvider,
+  availableCommands: CommandDefinition[],
+  selectedName: string,
+): Promise<void> {
+  const selectedCommand = availableCommands.find((c) => c.name === selectedName);
+  if (!selectedCommand) return;
+
+  if (selectedCommand.argMode === "none") {
+    await selectedCommand.execute(ctx, getCoordinator, "");
+    return;
+  }
+
+  const input = await ctx.ui.input(
+    selectedCommand.prompt ?? selectedCommand.label,
+    selectedCommand.placeholder,
+  );
+  if (input === undefined) return;
+
+  await selectedCommand.execute(ctx, getCoordinator, input);
+}

package/src/commands/parse.ts

@@ -0,0 +1,103 @@
+/**
+ * Shared argument parsing utilities for Graphify slash commands.
+ */
+
+const WHITESPACE = /\s+/;
+
+/** Split an argument string on whitespace while respecting single and double quotes. */
+export function splitArgs(args: string): string[] {
+  const tokens: string[] = [];
+  let current = "";
+  let quote: "'" | '"' | null = null;
+
+  function flushToken() {
+    if (current === "") return;
+    tokens.push(current);
+    current = "";
+  }
+
+  for (const char of args) {
+    if (quote && char === quote) {
+      quote = null;
+      continue;
+    }
+    if (quote) {
+      current += char;
+      continue;
+    }
+    if (char === "'" || char === '"') {
+      quote = char;
+      continue;
+    }
+    if (WHITESPACE.test(char)) {
+      flushToken();
+      continue;
+    }
+    current += char;
+  }
+
+  flushToken();
+  if (quote !== null) {
+    tokens.push(current);
+  }
+
+  return tokens;
+}
+
+export interface ParseBooleanFlagResult {
+  value: boolean | undefined;
+  rest: string[];
+}
+
+/**
+ * Detect `--flag` or `--flag=true|false` in a token list.
+ * Returns the flag value and the remaining tokens with the flag removed.
+ */
+export function parseBooleanFlag(
+  tokens: string[],
+  flag: string,
+  supportsValue: boolean = false,
+): ParseBooleanFlagResult {
+  const prefix = `--${flag}`;
+  const valuePrefix = `${prefix}=`;
+  let value: boolean | undefined;
+  const rest: string[] = [];
+
+  for (const token of tokens) {
+    if (token === prefix) {
+      value = true;
+      continue;
+    }
+
+    if (supportsValue && token.startsWith(valuePrefix)) {
+      value = parseFlagValue(token.slice(valuePrefix.length), flag);
+      continue;
+    }
+
+    rest.push(token);
+  }
+
+  return { value, rest };
+}
+
+function parseFlagValue(raw: string, flag: string): boolean {
+  if (raw === "true") return true;
+  if (raw === "false") return false;
+  throw new FlagValueError(flag, raw);
+}
+
+class FlagValueError extends Error {
+  readonly flag: string;
+  readonly value: string;
+
+  constructor(flag: string, value: string) {
+    super(`Invalid value for --${flag}: ${value}`);
+    this.flag = flag;
+    this.value = value;
+  }
+}
+
+/** Build a usage message for a command. */
+export function usageError(command: string, usage: string): Error {
+  return new Error(`Usage: /${command} ${usage}`);
+}

package/src/commands/path.ts

@@ -0,0 +1,52 @@
+/**
+ * /graphify-path — find the shortest path between two nodes in the graph.
+ */
+
+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 = "path";
+const PATH_USAGE = "<source> <target>";
+
+const executePath: CommandExecutor = async (ctx, getCoordinator, args) => {
+  if (!ctx.hasUI) return;
+
+  const coordinator = requireCoordinatorWithCapability(
+    ctx,
+    getCoordinator,
+    FEATURE,
+    "The installed Graphify version does not support path queries.",
+  );
+  if (!coordinator) return;
+
+  try {
+    const [source, target] = parsePathArgs(args);
+    const result = await coordinator.path({ cwd: ctx.cwd, source, target });
+    ctx.ui.notify(formatResultForCommand(result), "info");
+  } catch (error) {
+    notifyCommandError(ctx, error);
+  }
+};
+
+export const pathCommand: CommandDefinition = {
+  name: "graphify-path",
+  label: "Find path",
+  description: "Find the shortest path between two nodes in the graph",
+  feature: FEATURE,
+  usage: PATH_USAGE,
+  argMode: "input",
+  prompt: "Path source and target",
+  placeholder: "src/index.ts src/utils.ts",
+  execute: executePath,
+};
+
+function parsePathArgs(args: string): [string, string] {
+  const tokens = splitArgs(args);
+  if (tokens.length !== 2) {
+    throw usageError("graphify-path", PATH_USAGE);
+  }
+  return [tokens[0], tokens[1]];
+}

package/src/commands/query.ts

@@ -0,0 +1,48 @@
+/**
+ * /graphify-query — ask a natural-language question against the graph.
+ */
+
+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 = "query";
+
+const executeQuery: CommandExecutor = async (ctx, getCoordinator, args) => {
+  if (!ctx.hasUI) return;
+
+  const coordinator = requireCoordinatorWithCapability(
+    ctx,
+    getCoordinator,
+    FEATURE,
+    "The installed Graphify version does not support graph queries.",
+  );
+  if (!coordinator) return;
+
+  const question = args.trim();
+  if (question === "") {
+    ctx.ui.notify("Usage: /graphify-query <question>", "warning");
+    return;
+  }
+
+  try {
+    const result = await coordinator.query({ cwd: ctx.cwd, question });
+    ctx.ui.notify(formatResultForCommand(result), "info");
+  } catch (error) {
+    const { message, severity } = formatErrorForCommand(error);
+    ctx.ui.notify(message, severity);
+  }
+};
+
+export const queryCommand: CommandDefinition = {
+  name: "graphify-query",
+  label: "Query graph",
+  description: "Ask a natural-language question against the graph",
+  feature: FEATURE,
+  usage: "<question>",
+  argMode: "input",
+  prompt: "Question",
+  placeholder: "What does this project do?",
+  execute: executeQuery,
+};

package/src/commands/registry.ts

@@ -0,0 +1,31 @@
+/**
+ * Single source of truth for all Graphify slash commands.
+ */
+
+import type { GraphifyCoordinator } from "../coordinator.js";
+import { affectedCommand } from "./affected.js";
+import { buildCommand } from "./build.js";
+import { explainCommand } from "./explain.js";
+import { pathCommand } from "./path.js";
+import { queryCommand } from "./query.js";
+import { statusCommand } from "./status.js";
+import type { CommandDefinition } from "./types.js";
+import { versionCommand } from "./version.js";
+
+export const graphifyCommands: CommandDefinition[] = [
+  buildCommand,
+  queryCommand,
+  pathCommand,
+  explainCommand,
+  affectedCommand,
+  statusCommand,
+  versionCommand,
+];
+
+export function getAvailableCommands(
+  coordinator: GraphifyCoordinator | null,
+  commands: CommandDefinition[] = graphifyCommands,
+): CommandDefinition[] {
+  if (!coordinator) return [];
+  return commands.filter((command) => coordinator.supports(command.feature));
+}

package/src/commands/status.ts

@@ -0,0 +1,39 @@
+/**
+ * /graphify-status — show graph status for the current project.
+ */
+
+import type { GraphifyCapabilities } from "../backends/types.js";
+import { formatErrorForCommand } from "./format.js";
+import { requireCoordinator } from "./helpers.js";
+import type { CommandDefinition, CommandExecutor } from "./types.js";
+
+const FEATURE: keyof GraphifyCapabilities = "status";
+
+const executeStatus: CommandExecutor = async (ctx, getCoordinator) => {
+  if (!ctx.hasUI) return;
+
+  const coordinator = requireCoordinator(ctx, getCoordinator);
+  if (!coordinator) return;
+
+  try {
+    const status = await coordinator.status({ cwd: ctx.cwd });
+    if (status.hasGraph && status.graphPath) {
+      ctx.ui.notify(`Graphify graph ready: ${status.graphPath}`, "info");
+      return;
+    }
+    ctx.ui.notify("No Graphify graph found. Build one with `graphify .`.", "warning");
+  } catch (error) {
+    const { message, severity } = formatErrorForCommand(error);
+    ctx.ui.notify(message, severity);
+  }
+};
+
+export const statusCommand: CommandDefinition = {
+  name: "graphify-status",
+  label: "Graph status",
+  description: "Show whether a Graphify knowledge graph exists for this project",
+  feature: FEATURE,
+  usage: "",
+  argMode: "none",
+  execute: executeStatus,
+};