@liuxincuit/pi-codegraph 0.1.0 → 0.1.2

package/README.md

@@ -15,6 +15,8 @@
 npm i -g @colbymchenry/codegraph
 ```
 
+未检测到 CLI 时，插件**不会注入任何工具、命令或技能**（`codegraph_explore`、`/codegraph-*`、CodeGraph 技能均不加载），仅在会话开始时弹出一条安装提示；安装后 `/reload` 或重启 pi 即恢复全部功能。
+
 ## 安装
 
 ### npm（推荐）
@@ -47,7 +49,13 @@ pi -e ./extensions/codegraph.ts
 
 ## 功能一览
 
-- **`codegraph_explore` 工具** — 面向智能体的核心代码智能工具。输入符号名或自然语言问题即可查询；可选传 `path` 查询其他已建索引的项目，传 `maxFiles` 限制返回的源码行数。
+- **`codegraph_*` 工具集** — 面向智能体的代码智能工具，均支持 `path` 参数查询其他已建索引的项目：
+  - `codegraph_explore` — 一揽子探索：相关符号逐字源码 + 调用路径 + 影响范围（`maxFiles` 限制返回行数）
+  - `codegraph_query` — 按名称搜索符号（位置 + 签名，可选 `kind`/`limit` 过滤）
+  - `codegraph_node` — 单个符号的源码 + 调用轨迹，可链式追踪调用图
+  - `codegraph_callers` / `codegraph_callees` — 谁调用了它 / 它调用了谁（`limit`）
+  - `codegraph_impact` — 修改符号的影响半径（`depth`）
+  - `codegraph_files` — 从索引查看文件结构（tree/flat/grouped，`pattern`、`maxDepth`）
 - **`/codegraph-init [path]`** — 为项目建立索引（`codegraph init`）。
 - **`/codegraph-sync [path]`** — 手动同步自上次索引以来的改动（`codegraph sync`）。
 - **`/codegraph-status [path]`** — 查看索引状态与统计信息（`codegraph status`）。

package/extensions/codegraph.ts

@@ -8,16 +8,21 @@
 // Upstream: https://github.com/colbymchenry/codegraph
 
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
-import { Type } from "typebox";
+import { TSchema, Type } from "typebox";
 import * as fs from "node:fs/promises";
 import * as path from "node:path";
+import { fileURLToPath } from "node:url";
 
 const INSTALL_HINT =
-	"codegraph CLI not found on PATH. Install: npm i -g @colbymchenry/codegraph";
+	"未检测到 codegraph CLI（PATH 中无 codegraph 命令），本插件未注入任何工具、命令或技能。" +
+	"安装：npm i -g @colbymchenry/codegraph，然后 /reload 或重启 pi 生效。";
+
+// Whole-process dedup for the missing-CLI hint: extensions re-run per session and
+// per subagent (separate jiti module copies), so gate on globalThis.
+const MISSING_CLI_HINTED = Symbol.for("pi-codegraph.missing-cli-hinted");
 
 // Result of `codegraph version` this session — null until first check.
 let cliAvailable: boolean | null = null;
-let notifiedMissing = false;
 
 async function execCg(
 	pi: ExtensionAPI,
@@ -74,29 +79,46 @@ function updateStatusBar(ctx: ExtensionContext, state: StatusState) {
 }
 
 // Modeled on upstream's MCP SERVER_INSTRUCTIONS (src/mcp/server-instructions.ts):
-// lead the agent to codegraph_explore BEFORE grep/read, plus anti-patterns and staleness handling.
+// lead the agent to the codegraph_* tools BEFORE grep/read, plus anti-patterns and staleness handling.
 const INDEX_HINT = `# CodeGraph — this project is indexed
 
-A \`.codegraph/\` index exists here: SQLite knowledge graph of every symbol, edge, and file (30+ languages). ONE \`codegraph_explore\` call returns the relevant symbols' verbatim line-numbered source (treat it as already Read — safe to Edit from) PLUS call paths between them and a blast-radius summary of what depends on them.
+A \`.codegraph/\` index exists here: SQLite knowledge graph of every symbol, edge, and file (30+ languages). It answers structural code questions with verbatim, line-numbered source (treat codegraph output as already Read — safe to Edit from).
 
-- For structural questions (how does X work / where is X / who calls Y / what breaks if I change Z), call \`codegraph_explore\` INSTEAD of grep + read — usually ONE call answers the whole question.
-- Call it BEFORE and WHILE writing or editing code: it puts the blast radius in view before you touch a symbol you can name.
-- Flow tracing: name endpoint symbols (e.g. \`mutateElement renderScene\`) to surface the path across dynamic-dispatch hops.
+- For structural questions (how does X work / where is X / who calls Y / what breaks if I change Z), use the codegraph_* tools INSTEAD of grep + read — usually ONE call answers the whole question.
+- Choose the right tool:
+  - \`codegraph_query\` — locate a symbol: locations + signatures only.
+  - \`codegraph_node\` — one symbol's source + caller/callee trail (chain it to follow a call graph).
+  - \`codegraph_callers\` — who calls a symbol. \`codegraph_callees\` — what a symbol calls.
+  - \`codegraph_impact\` — blast radius of changing a symbol (call before editing).
+  - \`codegraph_files\` — indexed file tree (tree/flat/grouped by language).
+  - \`codegraph_explore\` — broad questions: relevant symbols' source + call paths in one shot. Name endpoint symbols (e.g. \`mutateElement renderScene\`) to surface paths across dynamic-dispatch hops.
 - Anti-patterns: don't grep or Read first; don't re-verify codegraph output with grep (AST-derived, more accurate than grep); don't reconstruct a flow by hand.
 - "Already sent earlier in this conversation": pointer means content is already in context — do not re-fetch or Read.
 - Staleness: if tool output contains "⚠️ Some files referenced below were edited since the last index sync", read only those flagged files directly.
 - Multi-project / Monorepo: pass \`path\` to query any indexed sub-project directory.
 - If a project has no \`.codegraph/\`, use built-in tools there; indexing is the user's decision — suggest /codegraph-init if it comes up.`;
 
-export default function codegraphExtension(pi: ExtensionAPI) {
+// When the CLI is absent, register nothing but a one-shot hint handler: no
+// tools, no commands, no resources_discover (so no skill injection), no sync.
+export function registerMissingCliHint(pi: ExtensionAPI) {
+	pi.on("session_start", async (_event, ctx) => {
+		if ((globalThis as Record<symbol, boolean>)[MISSING_CLI_HINTED]) return;
+		(globalThis as Record<symbol, boolean>)[MISSING_CLI_HINTED] = true;
+		if (ctx.hasUI) ctx.ui.notify(INSTALL_HINT, "warning");
+	});
+}
+
+export default async function codegraphExtension(pi: ExtensionAPI) {
+	if (!(await ensureCli(pi))) {
+		registerMissingCliHint(pi);
+		return;
+	}
 	// ── codegraph_explore tool ─────────────────────────────────────────────
 	pi.registerTool({
 		name: "codegraph_explore",
 		label: "CodeGraph Explore",
 		description:
-			"PRIMARY tool for code questions — call it BEFORE grep/read when the project has a .codegraph/ index. " +
-			"One query returns the relevant symbols' verbatim line-numbered source plus the call paths between them and a blast-radius summary. " +
-			"If the project is not indexed the output says so: continue with built-in tools and suggest the user run /codegraph-init.",
+			"Broad code exploration in one shot: relevant symbols' verbatim line-numbered source, call paths between them, and a blast-radius summary.",
 		promptSnippet:
 			"codegraph_explore: symbol source + call paths in one shot from the project's CodeGraph index",
 		promptGuidelines: [
@@ -109,7 +131,7 @@ export default function codegraphExtension(pi: ExtensionAPI) {
 			}),
 			path: Type.Optional(
 				Type.String({
-					description: "Project path to query; defaults to the current working directory",
+					description: "Project path (default: cwd)",
 				}),
 			),
 			maxFiles: Type.Optional(
@@ -137,6 +159,193 @@ export default function codegraphExtension(pi: ExtensionAPI) {
 		},
 	});
 
+	// ── codegraph_* fine-grained tools (CLI parity with the MCP tools) ────
+	// Each maps 1:1 to a codegraph CLI subcommand; `path` selects the project,
+	// defaults to the session cwd (same convention as codegraph_explore).
+	const projectPath = () =>
+		Type.Optional(
+			Type.String({
+				description: "Project path (default: cwd)",
+			}),
+		);
+
+	type CliToolDef = {
+		name: string;
+		label: string;
+		description: string;
+		snippet: string;
+		guidelines: string[];
+		subcommand: string;
+		parameters: TSchema;
+		positional?: (p: Record<string, unknown>) => string[];
+		flags?: (p: Record<string, unknown>) => string[];
+		timeout?: number;
+	};
+
+	function registerCliTool(pi: ExtensionAPI, def: CliToolDef) {
+		pi.registerTool({
+			name: def.name,
+			label: def.label,
+			description: def.description,
+			promptSnippet: def.snippet,
+			promptGuidelines: def.guidelines,
+			parameters: def.parameters,
+			execute: async (_toolCallId, params: Record<string, unknown>, signal, _onUpdate, ctx) => {
+				const cwd = (params.path as string | undefined) ?? ctx.cwd;
+				const args = [
+					def.subcommand,
+					...(def.positional?.(params) ?? []),
+					"-p",
+					cwd,
+					...(def.flags?.(params) ?? []),
+				];
+				const result = await execCg(pi, args, {
+					signal,
+					timeout: def.timeout ?? 60_000,
+				});
+				if (result.killed) return textResult(`codegraph ${def.subcommand} timed out`);
+				// Non-zero exits carry upstream's agent-friendly guidance — pass it through.
+				if (result.code !== 0) return textResult(outputOf(result));
+				return textResult(result.stdout.trim());
+			},
+		});
+	}
+
+	const cliTools: CliToolDef[] = [
+		{
+			name: "codegraph_query",
+			label: "CodeGraph Query",
+			description:
+				"Search symbols by name. Returns locations and signatures only (no source). Use to locate where a symbol is declared.",
+			snippet: "codegraph_query: symbol locations + signatures by name",
+			guidelines: [
+				"To locate where a symbol is declared (kind, file, line), use codegraph_query before grep.",
+			],
+			subcommand: "query",
+			parameters: Type.Object({
+				search: Type.String({ description: "Symbol name or partial name to search" }),
+				kind: Type.Optional(
+					Type.String({
+						description:
+							"Filter by node kind: function, method, class, interface, type, variable, route, component",
+					}),
+				),
+				limit: Type.Optional(Type.Integer({ description: "Maximum results (default 10)" })),
+				path: projectPath(),
+			}),
+			positional: (p) => [p.search as string],
+			flags: (p) => [
+				...(p.kind ? ["--kind", p.kind as string] : []),
+				...(typeof p.limit === "number" && p.limit > 0 ? ["--limit", String(p.limit)] : []),
+			],
+		},
+		{
+			name: "codegraph_node",
+			label: "CodeGraph Node",
+			description:
+				"One symbol's source plus its caller/callee trail. Chain it to follow a call graph across files.",
+			snippet: "codegraph_node: a symbol's source + caller/callee trail",
+			guidelines: [
+				"To deep-dive one known symbol (verbatim source + who it calls / is called by), use codegraph_node.",
+			],
+			subcommand: "node",
+			parameters: Type.Object({
+				name: Type.String({ description: "Symbol name to inspect" }),
+				path: projectPath(),
+			}),
+			positional: (p) => [p.name as string],
+		},
+		{
+			name: "codegraph_callers",
+			label: "CodeGraph Callers",
+			description: "Find all functions or methods that call a specific symbol.",
+			snippet: "codegraph_callers: who calls a symbol",
+			guidelines: [
+				"To find what calls a symbol (reverse dependencies), use codegraph_callers.",
+			],
+			subcommand: "callers",
+			parameters: Type.Object({
+				symbol: Type.String({ description: "Symbol name whose callers to find" }),
+				limit: Type.Optional(Type.Integer({ description: "Maximum results (default 20)" })),
+				path: projectPath(),
+			}),
+			positional: (p) => [p.symbol as string],
+			flags: (p) => [
+				...(typeof p.limit === "number" && p.limit > 0 ? ["--limit", String(p.limit)] : []),
+			],
+		},
+		{
+			name: "codegraph_callees",
+			label: "CodeGraph Callees",
+			description: "Find all functions or methods that a specific symbol calls.",
+			snippet: "codegraph_callees: what a symbol calls",
+			guidelines: [
+				"To find what a symbol calls (its outgoing edges), use codegraph_callees.",
+			],
+			subcommand: "callees",
+			parameters: Type.Object({
+				symbol: Type.String({ description: "Symbol name whose callees to find" }),
+				limit: Type.Optional(Type.Integer({ description: "Maximum results (default 20)" })),
+				path: projectPath(),
+			}),
+			positional: (p) => [p.symbol as string],
+			flags: (p) => [
+				...(typeof p.limit === "number" && p.limit > 0 ? ["--limit", String(p.limit)] : []),
+			],
+		},
+		{
+			name: "codegraph_impact",
+			label: "CodeGraph Impact",
+			description: "Analyze what code is affected by changing a symbol (blast radius).",
+			snippet: "codegraph_impact: blast radius of changing a symbol",
+			guidelines: [
+				"Before editing a symbol, use codegraph_impact to see what depends on it.",
+			],
+			subcommand: "impact",
+			parameters: Type.Object({
+				symbol: Type.String({ description: "Symbol name to analyze impact of changing" }),
+				depth: Type.Optional(Type.Integer({ description: "Traversal depth (default 2)" })),
+				path: projectPath(),
+			}),
+			positional: (p) => [p.symbol as string],
+			flags: (p) => [
+				...(typeof p.depth === "number" && p.depth > 0 ? ["--depth", String(p.depth)] : []),
+			],
+		},
+		{
+			name: "codegraph_files",
+			label: "CodeGraph Files",
+			description:
+				"Show the indexed project's file structure (tree, flat, or grouped by language), with per-file symbol counts.",
+			snippet: "codegraph_files: indexed file tree with symbol counts",
+			guidelines: [
+				"To get a structured view of the project files, use codegraph_files.",
+			],
+			subcommand: "files",
+			parameters: Type.Object({
+				dir: Type.Optional(Type.String({ description: "Subdirectory within the project to show" })),
+				pattern: Type.Optional(Type.String({ description: "Glob pattern to filter files" })),
+				format: Type.Optional(
+					Type.Union([Type.Literal("tree"), Type.Literal("flat"), Type.Literal("grouped")]),
+				),
+				maxDepth: Type.Optional(Type.Integer({ description: "Maximum directory depth for tree format" })),
+				path: projectPath(),
+			}),
+			positional: (p) => (p.dir ? [p.dir as string] : []),
+			flags: (p) => [
+				...(p.pattern ? ["--pattern", p.pattern as string] : []),
+				...(p.format ? ["--format", p.format as string] : []),
+				...(typeof p.maxDepth === "number" && p.maxDepth > 0
+					? ["--max-depth", String(p.maxDepth)]
+					: []),
+			],
+		},
+	];
+
+	for (const tool of cliTools) {
+		registerCliTool(pi, tool);
+	}
+
 	// ── /codegraph-init ────────────────────────────────────────────────────
 	pi.registerCommand("codegraph-init", {
 		description: "Build the CodeGraph index for the current project (codegraph init)",
@@ -238,17 +447,15 @@ export default function codegraphExtension(pi: ExtensionAPI) {
 		},
 	});
 
-	// ── session_start: CLI check + incremental sync + context hint ────────
-	pi.on("session_start", async (event, ctx) => {
-		if (!(await ensureCli(pi))) {
-			updateStatusBar(ctx, false);
-			if (ctx.hasUI && !notifiedMissing) {
-				notifiedMissing = true;
-				ctx.ui.notify(INSTALL_HINT, "warning");
-			}
-			return;
-		}
+	// ── resources_discover: contribute the skill only when the CLI exists ──
+	pi.on("resources_discover", async () => {
+		return {
+			skillPaths: [fileURLToPath(new URL("../skills/codegraph/SKILL.md", import.meta.url))],
+		};
+	});
 
+	// ── session_start: incremental sync + context hint ────────────────────
+	pi.on("session_start", async (event, ctx) => {
 		const indexed = await isIndexed(ctx.cwd);
 		if (indexed) {
 			updateStatusBar(ctx, "sync");

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@liuxincuit/pi-codegraph",
-	"version": "0.1.0",
+	"version": "0.1.2",
 	"description": "CodeGraph support for pi — symbol source + call paths via the codegraph CLI",
 	"type": "module",
 	"keywords": [
@@ -31,9 +31,6 @@
 	"pi": {
 		"extensions": [
 			"./extensions"
-		],
-		"skills": [
-			"./skills"
 		]
 	},
 	"files": [

package/skills/codegraph/SKILL.md

@@ -1,27 +1,30 @@
----
-name: codegraph
-description: Query the project's CodeGraph index (symbol source + call paths) via the codegraph_explore tool. Use when answering structural code questions — how X works, where X is, what a change affects — in a project that has a .codegraph/ index.
----
-
-# CodeGraph
-
-The `codegraph_explore` tool answers structural code questions in one shot: the relevant symbols' verbatim line-numbered source, the call paths between them, and a blast-radius summary. It reads the project's CodeGraph index (`.codegraph/`), built and maintained by the `codegraph` CLI.
-
-## When to use
-
-- "How does X work?" / "Where is X?" / "What calls Y?" / "What breaks if I change Z?"
-- Before an edit, to map the symbols you are about to touch and inspect the blast radius.
-- Prefer it over grep/read for structural exploration **when the project has a `.codegraph/` index**.
-
-## How to query
-
-- `query`: symbol names (`CodeGraph open`, `MCPSession`), endpoint flows (`mutateElement renderScene`), or a natural-language question. Naming a file or symbol returns its current line-numbered source.
-- `path`: optional project path. Defaults to the current working directory. In a monorepo, pass the sub-project directory that contains `.codegraph/`.
-- `maxFiles`: optional integer to limit how many file sources are returned.
-
-## Anti-patterns & Guidance
-
-- **Trust AST results.** Don't re-verify codegraph output with grep.
-- **Already sent earlier in this conversation.** When this pointer appears, the lines are already in your session context — scroll back instead of re-fetching or reading the file.
-- **Staleness banner.** If output warns `⚠️ Some files referenced below were edited since the last index sync`, read only those specific files directly; other files in the response remain fresh.
-- **No index, no tool.** If the output says the project isn't indexed, stop calling `codegraph_explore` for that project this session and use built-in tools. Indexing is the user's decision — suggest the user run `/codegraph-init` if appropriate.
+---
+name: codegraph
+description: Query the project's CodeGraph index (symbol source, call paths, blast radius) via the codegraph_* tools. Use when answering structural code questions — how X works, where X is, who calls Y, what a change affects — in a project that has a .codegraph/ index.
+---
+
+# CodeGraph
+
+The `codegraph_*` tools answer structural code questions from the project's CodeGraph index (`.codegraph/`), built and maintained by the `codegraph` CLI. Prefer them over grep/read for structural exploration **when the project has a `.codegraph/` index**.
+
+## Picking a tool
+
+- `codegraph_query` — locate a symbol: locations + signatures only. Start here when you don't know where something is declared.
+- `codegraph_node` — one known symbol's verbatim source + caller/callee trail. Chain it to follow a call graph across files.
+- `codegraph_callers` / `codegraph_callees` — who calls a symbol / what a symbol calls.
+- `codegraph_impact` — blast radius of changing a symbol; call before editing.
+- `codegraph_files` — indexed file tree (tree/flat/grouped by language) with symbol counts.
+- `codegraph_explore` — broad questions: relevant symbols' source + call paths in one shot. Name endpoint symbols (`mutateElement renderScene`) to surface paths across dynamic-dispatch hops.
+
+## How to query
+
+- Every tool accepts `path`: the project to query. Defaults to the current working directory. In a monorepo, pass the sub-project directory that contains `.codegraph/`.
+- `codegraph_query`: `search` (symbol name or partial), optional `kind` (function, method, class, ...) and `limit`.
+- `codegraph_explore`: `query` (symbol names or natural language) and optional `maxFiles` to cap source lines returned.
+
+## Anti-patterns & Guidance
+
+- **Trust AST results.** Don't re-verify codegraph output with grep.
+- **Already sent earlier in this conversation.** When this pointer appears, the lines are already in your session context — scroll back instead of re-fetching or reading the file.
+- **Staleness banner.** If output warns `⚠️ Some files referenced below were edited since the last index sync`, read only those specific files directly; other files in the response remain fresh.
+- **No index, no tool.** If output says the project isn't indexed, stop calling `codegraph_*` for that project this session and use built-in tools. Indexing is the user's decision — suggest the user run `/codegraph-init` if appropriate.