decorated-pi 0.6.0 → 0.7.0

package/tools/ask/index.ts

@@ -0,0 +1,93 @@
+/**
+ * ask — ask the user one or more questions and return their answers.
+ *
+ * Supports free text, single-choice, and multiple-choice questions.
+ * Uses a custom TUI component so multiple questions can be presented
+ * together and navigated with Tab / Shift+Tab.
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import { AskComponent, type AskAnswer, type AskQuestion } from "../../ui/ask.js";
+
+const askQuestionSchema = Type.Object({
+  id: Type.String({ description: "Unique identifier for this question in the result." }),
+  type: Type.Union(
+    [Type.Literal("text"), Type.Literal("single"), Type.Literal("multi")],
+    { description: "text = free input, single = one option, multi = many options" },
+  ),
+  question: Type.String({ description: "Question text shown to the user." }),
+  options: Type.Optional(Type.Array(Type.String(), { description: "Options for single or multi choice." })),
+  default: Type.Optional(Type.String({ description: "Default answer. For multi, comma-separated values." })),
+  allowCustom: Type.Optional(Type.Boolean({
+    description: "For single/multi: append an \"Other\" row that toggles into a free-text input. Lets the user enter a custom answer not in the preset list.",
+  })),
+});
+
+function formatAnswer(q: AskQuestion, value: string | string[]): string {
+  if (q.type === "text") return value as string;
+  if (q.type === "single") return value as string;
+  return (value as string[]).join(", ");
+}
+
+export function formatAnswers(questions: AskQuestion[], answers: { id: string; value: string | string[] }[]): string {
+  const lines: string[] = [];
+  for (const q of questions) {
+    const a = answers.find((x) => x.id === q.id);
+    if (!a) continue;
+    lines.push(`${q.question}: ${formatAnswer(q, a.value)}`);
+  }
+  return lines.join("\n");
+}
+
+export function registerAskTool(pi: ExtensionAPI): void {
+  pi.registerTool({
+    name: "ask",
+    label: "Ask user",
+    description: "Ask the user one or more questions and return their answers. Supports free text, single choice, and multiple choice. Use when you need clarification or a decision before continuing.",
+    promptSnippet: "Ask the user one or more clarifying questions",
+    promptGuidelines: [
+      "Before acting on a prompt, ensure you fully understand the user's intent — if ambiguous, ask clarifying questions using the ask tool.",
+    ],
+    parameters: Type.Object({
+      questions: Type.Array(askQuestionSchema, { minItems: 1, description: "Questions to ask. User navigates between them with Tab / Shift+Tab." }),
+    }),
+    execute: async (_id, params, _signal, _update, ctx) => {
+      if (!ctx.hasUI) {
+        return {
+          content: [{ type: "text", text: "ask tool requires an interactive UI session." }],
+          isError: true,
+          details: {},
+        };
+      }
+
+      // Validate options for single/multi.
+      for (const q of params.questions) {
+        if ((q.type === "single" || q.type === "multi") && (!q.options || q.options.length === 0)) {
+          return {
+            content: [{ type: "text", text: `Question "${q.id}" (${q.type}) requires at least one option.` }],
+            isError: true,
+            details: {},
+          };
+        }
+      }
+
+      const answers = await ctx.ui.custom<AskAnswer[] | undefined>(
+        (tui, theme, _kb, done) => new AskComponent(tui, theme, params.questions, done),
+      );
+
+      if (!answers) {
+        return {
+          content: [{ type: "text", text: "User cancelled the questions." }],
+          isError: false,
+          details: { cancelled: true },
+        };
+      }
+
+      return {
+        content: [{ type: "text", text: formatAnswers(params.questions, answers) }],
+        details: { answers },
+      };
+    },
+  });
+}

package/tools/mcp/builtin/codegraph.ts

@@ -1,45 +1,21 @@
 /**
- * codegraph builtin MCP server — config + system-prompt guidance.
+ * codegraph builtin MCP server — config + project artefact check.
  *
- * Injected by `index.ts` → `buildGuidelines()` when the codegraph
- * module is enabled (see `isModuleEnabled("codegraph")` in settings).
+ * Enabled state is controlled like any other MCP server: through the
+ * MCP config (global `~/.pi/agent/mcp.json` under `mcpServers`, or
+ * project `.pi/agent/mcp.json`) or via the `/mcp` command. There is no
+ * separate /dp-settings toggle; codegraph is just one MCP server.
  */
+import * as fs from "node:fs";
+import * as path from "node:path";
 import type { McpServerConfig } from "../config.js";
-import { isCodegraphModuleEnabled } from "../../../settings.js";
 
 export const CODEGRAPH_BUILTIN: Omit<McpServerConfig, "source"> = {
     name: "codegraph",
     command: "codegraph",
     args: ["serve", "--mcp"],
-    enabled: false, // overridden by isCodegraphModuleEnabled() at resolve time
+    enabled: false,
     description:
-        "Local code knowledge graph (colbymchenry/codegraph). Enable via /dp-settings.",
+        "Local code knowledge graph (colbymchenry/codegraph). Enable via /mcp.",
+    canUseInProject: (cwd: string) => fs.existsSync(path.join(cwd, ".codegraph")),
 };
-
-/** Predicate for `resolveMcpConfigs` to gate the codegraph server. */
-export function codegraphEnabled(): boolean {
-    return isCodegraphModuleEnabled();
-}
-
-export const CODEGRAPH_GUIDANCE = [
-    "### CodeGraph, code source map",
-    "- This project's `codegraph_*` MCP tools are enabled. The graph is a pre-built index; grep/glob/Read of source code is repeating work the index already did.",
-    "",
-    "#### When to reach for it",
-    '- Starting any task that touches code → `codegraph_explore("how does X work")` or `codegraph_files`',
-    "- Looking for where a symbol is defined → `codegraph_search <name>`",
-    "- Reading a function's body → `codegraph_node <name>` (or `codegraph_explore`)",
-    "- Tracing call flow → `codegraph_callers` / `codegraph_callees`",
-    "- Assessing refactor risk → `codegraph_impact <name>`",
-    "",
-    "#### Do NOT do this",
-    "- `ls`, `find`, `grep -rn`, `rg` to discover symbols → use `codegraph_search`",
-    "- `read` of an entire file to find a function → use `codegraph_explore` first",
-    '- Reading 3+ files to understand a module → use `codegraph_explore("how does X work")`',
-    "- `bash` with `cat`, `head`, `sed` to view source → use `codegraph_node` or `read` (single file only)",
-    "",
-    "#### If it errors",
-    '- "Project not initialized" → ask the user to run `codegraph init -i` in their terminal',
-    "- Empty results → fall back to grep/Read (the index is best-effort, not authoritative)",
-    "- Tool timeout → `codegraph_status` to check; if indexer is dead, fall back",
-].join("\n");

package/tools/mcp/builtin/index.ts

@@ -5,11 +5,11 @@
 import type { McpServerConfig } from "../config.js";
 import { CONTEXT7_BUILTIN } from "./context7.js";
 import { EXA_BUILTIN } from "./exa.js";
-import { CODEGRAPH_BUILTIN, CODEGRAPH_GUIDANCE } from "./codegraph.js";
+import { CODEGRAPH_BUILTIN } from "./codegraph.js";
 
 export { CONTEXT7_BUILTIN } from "./context7.js";
 export { EXA_BUILTIN } from "./exa.js";
-export { CODEGRAPH_BUILTIN, CODEGRAPH_GUIDANCE, codegraphEnabled } from "./codegraph.js";
+export { CODEGRAPH_BUILTIN } from "./codegraph.js";
 
 /** All builtin servers — flat list for `resolveMcpConfigs` to merge. */
 export const BUILTIN_MCP_SERVERS: Omit<McpServerConfig, "source">[] = [

package/tools/mcp/config.ts

@@ -5,16 +5,20 @@
  * hit sets defaults; later sources can override specific fields.
  *
  * Persistence locations:
- *   - global: `~/.pi/agent/decorated-pi.json` (under `mcpServers`)
+ *   - global: `~/.pi/agent/mcp.json` (under `mcpServers`)
  *   - project: `<cwd>/.pi/agent/mcp.json` (under `mcpServers`)
+ *
+ * Legacy: global MCP servers used to live in `~/.pi/agent/decorated-pi.json`
+ * under `mcpServers`. `loadGlobalMcpConfigs()` automatically migrates that
+ * data to `~/.pi/agent/mcp.json` on first read.
  */
 import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
 import { spawnSync } from "node:child_process";
-import { loadConfig } from "../../settings.js";
+import { isModuleEnabled } from "../../settings.js";
 import type { DependencyStatus } from "../../hooks/skeleton.js";
-import { BUILTIN_MCP_SERVERS, codegraphEnabled } from "./builtin/index.js";
+import { BUILTIN_MCP_SERVERS } from "./builtin/index.js";
 
 export { BUILTIN_MCP_SERVERS } from "./builtin/index.js";
 
@@ -27,6 +31,12 @@ export interface McpServerConfig {
   description?: string;
   enabled: boolean;
   source: "builtin" | "global" | "project";
+  /** Optional predicate: return false if this server cannot be used in the given project. */
+  canUseInProject?: (cwd: string) => boolean;
+}
+
+function globalMcpJsonPath(): string {
+  return path.join(os.homedir(), ".pi", "agent", "mcp.json");
 }
 
 function readMcpJson(filePath: string): Record<string, { url?: string; command?: string; args?: string[]; env?: Record<string, string>; enabled?: boolean; description?: string }> | null {
@@ -41,6 +51,64 @@ function readMcpJson(filePath: string): Record<string, { url?: string; command?:
   }
 }
 
+/**
+ * One-time migration: older versions stored global MCP servers in
+ * `~/.pi/agent/decorated-pi.json` under `mcpServers`. Move that data to
+ * the dedicated `~/.pi/agent/mcp.json` file so global and project configs
+ * are symmetric.
+ *
+ * Rules:
+ *   - Only runs when the legacy file has at least one `mcpServers` entry.
+ *   - For each legacy server name, if `mcp.json` already has an entry with
+ *     the same name, the legacy entry is skipped (new file wins).
+ *   - Idempotent: after running once, the legacy file no longer has
+ *     `mcpServers`, so a second call is a no-op.
+ */
+export function migrateLegacyGlobalMcpConfig(): void {
+  const legacyPath = path.join(os.homedir(), ".pi", "agent", "decorated-pi.json");
+  const newPath = globalMcpJsonPath();
+
+  let legacy: Record<string, any> | null = null;
+  try {
+    legacy = JSON.parse(fs.readFileSync(legacyPath, "utf-8"));
+  } catch {
+    return;
+  }
+  if (!legacy || !legacy.mcpServers || typeof legacy.mcpServers !== "object") return;
+  if (Object.keys(legacy.mcpServers).length === 0) return;
+
+  // Load existing new file (if any). If it is corrupt, leave everything
+  // alone — safer than clobbering.
+  let newConfig: Record<string, any> = { mcpServers: {} };
+  if (fs.existsSync(newPath)) {
+    try {
+      const parsed = JSON.parse(fs.readFileSync(newPath, "utf-8"));
+      if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+        newConfig = parsed;
+        if (!newConfig.mcpServers || typeof newConfig.mcpServers !== "object") {
+          newConfig.mcpServers = {};
+        }
+      }
+    } catch {
+      return;
+    }
+  }
+
+  // Merge: only add legacy entries that don't already exist in the new file.
+  for (const [name, entry] of Object.entries(legacy.mcpServers)) {
+    if (!(name in newConfig.mcpServers)) {
+      newConfig.mcpServers[name] = entry;
+    }
+  }
+
+  const dir = path.dirname(newPath);
+  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+  fs.writeFileSync(newPath, JSON.stringify(newConfig, null, 2) + "\n", "utf-8");
+
+  delete legacy.mcpServers;
+  fs.writeFileSync(legacyPath, JSON.stringify(legacy, null, 2) + "\n", "utf-8");
+}
+
 /** Load project-level MCP configs from cwd only. */
 export function loadProjectMcpConfigs(cwd: string): McpServerConfig[] {
   const configs: McpServerConfig[] = [];
@@ -69,18 +137,18 @@ export function loadProjectMcpConfigs(cwd: string): McpServerConfig[] {
   return configs;
 }
 
-/** Load global MCP configs from ~/.pi/agent/decorated-pi.json. */
+/** Load global MCP configs from ~/.pi/agent/mcp.json. */
 export function loadGlobalMcpConfigs(): McpServerConfig[] {
-  const config = loadConfig();
-  if (!config.mcpServers) return [];
+  const servers = readMcpJson(globalMcpJsonPath());
+  if (!servers) return [];
 
-  return Object.entries(config.mcpServers).map(([name, entry]) => ({
+  return Object.entries(servers).map(([name, entry]) => ({
     name,
     url: entry.url,
     command: entry.command,
     args: entry.args,
     env: entry.env,
-    description: (entry as any).description as string | undefined,
+    description: entry.description,
     enabled: entry.enabled !== false,
     source: "global" as const,
   }));
@@ -96,16 +164,17 @@ export function isSseUrl(url: string): boolean {
  * Later sources override earlier ones for the same server name.
  */
 export function resolveMcpConfigs(cwd: string): McpServerConfig[] {
+  // The mcp module switch is the master switch. When it is off, no MCP
+  // server config is considered active — this keeps the chain simple:
+  // mcp off → all servers off → no codegraph guidance.
+  if (!isModuleEnabled("mcp")) return [];
+
   const byName = new Map<string, McpServerConfig>();
 
-  // Builtin (lowest priority). The codegraph entry's `enabled` flag is
-  // computed at resolve time from the dp-settings module toggle.
+  // Builtin (lowest priority). Use the builtin's own `enabled` default.
+  // Servers can be enabled via the `/mcp` command or by editing mcp.json.
   for (const s of BUILTIN_MCP_SERVERS) {
-    if (s.name === "codegraph") {
-      byName.set(s.name, { ...s, enabled: codegraphEnabled(), source: "builtin" });
-    } else {
-      byName.set(s.name, { ...s, source: "builtin" });
-    }
+    byName.set(s.name, { ...s, source: "builtin" });
   }
 
   // Global — preserve url/command/description from builtin if not overridden
@@ -121,6 +190,7 @@ export function resolveMcpConfigs(cwd: string): McpServerConfig[] {
         env: s.env ?? existing.env,
         description: s.description ?? existing.description,
         source: "global",
+        canUseInProject: s.canUseInProject ?? existing.canUseInProject,
       });
     } else {
       byName.set(s.name, s);
@@ -140,6 +210,7 @@ export function resolveMcpConfigs(cwd: string): McpServerConfig[] {
         env: s.env ?? existing.env,
         description: s.description ?? existing.description,
         source: "project",
+        canUseInProject: s.canUseInProject ?? existing.canUseInProject,
       });
     } else {
       byName.set(s.name, s);
@@ -201,13 +272,14 @@ export function toggleMcpServerEnabled(
       if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
       fs.writeFileSync(filePath, JSON.stringify(raw, null, 2) + "\n", "utf-8");
     } else {
-      const config = loadConfig();
-      config.mcpServers = config.mcpServers || {};
-      config.mcpServers[serverName] = { ...(config.mcpServers[serverName] || {}), enabled };
-      const configPath = path.join(os.homedir(), ".pi/agent/decorated-pi.json");
-      const dir = path.dirname(configPath);
+      const filePath = globalMcpJsonPath();
+      const raw = readMcpJsonSafe(filePath) || { mcpServers: {} };
+      const servers = raw.mcpServers ?? {};
+      servers[serverName] = { ...(servers[serverName] || {}), enabled };
+      raw.mcpServers = servers;
+      const dir = path.dirname(filePath);
       if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
-      fs.writeFileSync(configPath, JSON.stringify(config, null, 2) + "\n", "utf-8");
+      fs.writeFileSync(filePath, JSON.stringify(raw, null, 2) + "\n", "utf-8");
     }
     return true;
   } catch {