@maxiaochao/pi-toolkit 0.9.6 → 0.10.1

package/packages/tiny-subagent/src/runner.ts

@@ -1,319 +0,0 @@
-import { createWriteStream, existsSync, realpathSync } from "node:fs";
-import { mkdtemp, rm, writeFile } from "node:fs/promises";
-import { basename, join } from "node:path";
-import { tmpdir } from "node:os";
-import { spawn } from "node:child_process";
-
-export const MAX_INLINE_BYTES = 16 * 1024;
-const CHILD_ENV = "PI_SUBAGENT_CHILD";
-const BINARY_ENV = "PI_TINY_SUBAGENT_PI_BINARY";
-
-export interface TinySubagentOptions {
- model?: string;
- thinking?: string;
- tools?: string[];
- systemPrompt?: string;
- cwd?: string;
- signal?: AbortSignal;
- onUpdate?: (result: TinySubagentResult) => void;
-}
-
-export interface TinySubagentArtifacts {
- directory: string;
- stdout: string;
- stderr: string;
- finalOutput?: string;
- cleanup: "remove directory when no longer needed";
-}
-
-export interface TinySubagentContent {
- type?: string;
- text?: string;
- name?: string;
- arguments?: Record<string, unknown>;
-}
-
-export interface TinySubagentMessage {
- role?: string;
- content?: string | TinySubagentContent[];
- toolCallId?: string;
- toolName?: string;
- isError?: boolean;
- stopReason?: string;
- errorMessage?: string;
- model?: string;
-}
-
-export interface TinySubagentResult {
- ok: boolean;
- output: string;
- outputBytes: number;
- stderr: string;
- stderrBytes: number;
- stdout: string;
- stdoutBytes: number;
- protocolErrors: string[];
- errorMessage?: string;
- stopReason?: string;
- exitCode: number | null;
- signal: NodeJS.Signals | null;
- model?: string;
- cwd: string;
- durationMs: number;
- messages: TinySubagentMessage[];
- artifacts?: TinySubagentArtifacts;
-}
-
-interface JsonEvent {
- type?: string;
- message?: TinySubagentMessage;
-}
-
-class Capture {
-	private readonly stream;
-	private inline = "";
-	private truncated = false;
-	bytes = 0;
-
-	readonly path: string;
-	constructor(path: string) {
-		this.path = path;
-		this.stream = createWriteStream(path, { encoding: "utf8", mode: 0o600 });
-	}
-
-
-	write(text: string): void {
-		this.bytes += Buffer.byteLength(text, "utf8");
-		this.stream.write(text);
-		if (this.truncated) return;
-		const next = this.inline + text;
-		if (Buffer.byteLength(next, "utf8") <= MAX_INLINE_BYTES) {
-			this.inline = next;
-			return;
-		}
-		this.inline = truncateUtf8(next, MAX_INLINE_BYTES);
-		this.truncated = true;
-	}
-
-	async close(): Promise<void> {
-		await new Promise<void>((resolve, reject) => {
-			this.stream.once("error", reject);
-			this.stream.once("finish", resolve);
-			this.stream.end();
-		});
-	}
-
-	preview(): string {
-		return this.truncated ? `${this.inline}\n[truncated after ${MAX_INLINE_BYTES} bytes; see artifact file]` : this.inline;
-	}
-}
-
-function truncateUtf8(text: string, maxBytes: number): string {
-	let result = text.slice(0, maxBytes);
-	while (Buffer.byteLength(result, "utf8") > maxBytes) result = result.slice(0, -1);
-	return result;
-}
-
-function getFinalText(messages: TinySubagentMessage[]): string {
- for (let i = messages.length - 1; i >= 0; i--) {
-  const message = messages[i];
-  if (message.role !== "assistant" || !Array.isArray(message.content)) continue;
-  return message.content
-   .filter((part) => part.type === "text" && typeof part.text === "string")
-   .map((part) => part.text as string)
-   .join("");
- }
- return "";
-}
-
-function parseLine(line: string, messages: TinySubagentMessage[], protocolErrors: string[]): boolean {
- if (!line.trim()) return false;
- try {
-  const event = JSON.parse(line) as JsonEvent;
-  if ((event.type === "message_end" || event.type === "tool_result_end") && event.message) {
-   messages.push(event.message);
-   return true;
-  }
- } catch {
-  if (protocolErrors.length < 20) protocolErrors.push(truncateUtf8(line, 4096));
- }
- return false;
-}
-
-function getPiInvocation(args: string[]): { command: string; args: string[] } {
-	const configuredBinary = process.env[BINARY_ENV]?.trim();
-	if (configuredBinary) return { command: configuredBinary, args };
-
-	const entry = process.argv[1];
-	if (entry && existsSync(entry) && /\.(?:mjs|cjs|js)$/i.test(entry)) {
-		try {
-			const resolved = realpathSync(entry);
-			if (resolved === entry || existsSync(resolved)) return { command: process.execPath, args: [entry, ...args] };
-		} catch {
-			// Fall through to the Pi binary on PATH.
-		}
-	}
-
-	if (/^pi(?:\.exe)?$/i.test(basename(process.execPath))) return { command: process.execPath, args };
-	return { command: "pi", args };
-}
-
-function stopReasonIsFailure(stopReason: string | undefined): boolean {
-	return stopReason === "error" || stopReason === "aborted";
-}
-
-export async function runTinySubagent(prompt: string, options: TinySubagentOptions = {}): Promise<TinySubagentResult> {
-	const cwd = options.cwd ?? process.cwd();
-	const artifactDirectory = await mkdtemp(join(tmpdir(), "pi-tiny-subagent-"));
-	const stdoutCapture = new Capture(join(artifactDirectory, "stdout.jsonl"));
-	const stderrCapture = new Capture(join(artifactDirectory, "stderr.log"));
-	const args = ["--mode", "json", "--print", "--no-session", "--no-extensions", "--no-skills"];
-	if (options.model?.trim()) args.push("--model", options.model.trim());
-	if (options.thinking?.trim()) args.push("--thinking", options.thinking.trim());
-	if (options.tools?.length) args.push("--tools", options.tools.join(","));
-	if (options.systemPrompt?.trim()) {
-		const systemPromptPath = join(artifactDirectory, "system-prompt.md");
-		await writeFile(systemPromptPath, options.systemPrompt, { encoding: "utf8", mode: 0o600 });
-		args.push("--append-system-prompt", systemPromptPath);
-	}
-	args.push("--", prompt);
-
-	const startedAt = Date.now();
-	const messages: TinySubagentMessage[] = [];
-	const protocolErrors: string[] = [];
-	let stdoutBuffer = "";
-	let errorMessage: string | undefined;
-	let aborted = false;
-	let exitCode: number | null = null;
-	let childSignal: NodeJS.Signals | null = null;
-	let spawnError: Error | undefined;
-	let child: ReturnType<typeof spawn> | undefined;
-	const invocation = getPiInvocation(args);
-
-
-	const emitUpdate = () => {
-		if (!options.onUpdate) return;
-		const output = getFinalText(messages);
-		const lastAssistant = [...messages].reverse().find((message) => message.role === "assistant");
-		options.onUpdate({
-			ok: false,
-			output,
-			outputBytes: Buffer.byteLength(output, "utf8"),
-			stderr: stderrCapture.preview(),
-			stderrBytes: stderrCapture.bytes,
-			stdout: stdoutCapture.preview(),
-			stdoutBytes: stdoutCapture.bytes,
-			protocolErrors: [...protocolErrors],
-			...(lastAssistant?.stopReason ? { stopReason: lastAssistant.stopReason } : {}),
-			exitCode,
-			signal: childSignal,
-			...(options.model ?? lastAssistant?.model ? { model: options.model ?? lastAssistant?.model } : {}),
-			cwd,
-			durationMs: Date.now() - startedAt,
-			messages: messages.slice(),
-		});
-	};
-
-	emitUpdate();
-	await new Promise<void>((resolve) => {
-		let settled = false;
-		const finish = () => {
-			if (settled) return;
-			settled = true;
-			resolve();
-		};
-		try {
-			child = spawn(invocation.command, invocation.args, {
-				cwd,
-				shell: false,
-				stdio: ["ignore", "pipe", "pipe"],
-				env: { ...process.env, [CHILD_ENV]: "1" },
-			});
-		} catch (error) {
-			spawnError = error instanceof Error ? error : new Error(String(error));
-			finish();
-			return;
-		}
-		child.stdout?.on("data", (chunk: Buffer | string) => {
-			const text = chunk.toString();
-			stdoutCapture.write(text);
-			stdoutBuffer += text;
-			const lines = stdoutBuffer.split("\n");
-			stdoutBuffer = lines.pop() ?? "";
-			for (const line of lines) {
-				if (parseLine(line, messages, protocolErrors)) emitUpdate();
-			}
-		});
-		child.stderr?.on("data", (chunk: Buffer | string) => stderrCapture.write(chunk.toString()));
-		child.once("error", (error) => {
-			spawnError = error;
-		});
-		child.once("close", (code, signal) => {
-			if (stdoutBuffer && parseLine(stdoutBuffer, messages, protocolErrors)) emitUpdate();
-			// Node may report a negative pseudo-exit code for ENOENT; expose a stable process failure code and keep the real error in errorMessage.
-			exitCode = spawnError ? 1 : code;
-			childSignal = signal;
-			finish();
-		});
-
-		const terminate = () => {
-			if (aborted) return;
-			aborted = true;
-			child?.kill("SIGTERM");
-			setTimeout(() => {
-				if (child && !child.killed) child.kill("SIGKILL");
-			}, 5000).unref();
-		};
-		if (options.signal) {
-			if (options.signal.aborted) terminate();
-			else options.signal.addEventListener("abort", terminate, { once: true });
-		}
-	});
-
-	await Promise.all([stdoutCapture.close(), stderrCapture.close()]);
-	const finalOutput = getFinalText(messages);
-	const lastAssistant = [...messages].reverse().find((message) => message.role === "assistant");
-	const stopReason = lastAssistant?.stopReason;
-	errorMessage = spawnError?.message ?? lastAssistant?.errorMessage;
-	if (aborted) errorMessage ||= "Tiny subagent was aborted";
-	if (!finalOutput && exitCode === 0 && !stopReason) errorMessage ||= "No assistant output received";
-	if (protocolErrors.length > 0 && !finalOutput && !errorMessage) errorMessage = "Pi emitted invalid JSON output";
-	if (stopReasonIsFailure(stopReason)) errorMessage ||= `Subagent stopped with reason: ${stopReason}`;
-
-	const outputBytes = Buffer.byteLength(finalOutput, "utf8");
-	const keepArtifacts = stdoutCapture.bytes > MAX_INLINE_BYTES || stderrCapture.bytes > MAX_INLINE_BYTES || outputBytes > MAX_INLINE_BYTES;
-	let artifacts: TinySubagentArtifacts | undefined;
-	if (keepArtifacts) {
-		const finalOutputPath = join(artifactDirectory, "final-output.txt");
-		if (outputBytes > 0) await writeFile(finalOutputPath, finalOutput, { encoding: "utf8", mode: 0o600 });
-		artifacts = {
-			directory: artifactDirectory,
-			stdout: stdoutCapture.path,
-			stderr: stderrCapture.path,
-			cleanup: "remove directory when no longer needed",
-			...(outputBytes > MAX_INLINE_BYTES ? { finalOutput: finalOutputPath } : {}),
-		};
-	} else {
-		await rm(artifactDirectory, { recursive: true, force: true });
-	}
-
-	return {
-		ok: !errorMessage && exitCode === 0 && childSignal === null && !stopReasonIsFailure(stopReason),
-		output: outputBytes > MAX_INLINE_BYTES ? `${truncateUtf8(finalOutput, MAX_INLINE_BYTES)}\n[truncated after ${MAX_INLINE_BYTES} bytes; see artifact file]` : finalOutput,
-		outputBytes,
-		stderr: stderrCapture.preview(),
-		stderrBytes: stderrCapture.bytes,
-		stdout: stdoutCapture.preview(),
-		stdoutBytes: stdoutCapture.bytes,
-		protocolErrors,
-		...(errorMessage ? { errorMessage } : {}),
-		...(stopReason ? { stopReason } : {}),
-		exitCode,
-		signal: childSignal,
-		...(options.model ?? lastAssistant?.model ? { model: options.model ?? lastAssistant?.model } : {}),
-		cwd,
-		durationMs: Date.now() - startedAt,
-		messages: messages.slice(),
-		...(artifacts ? { artifacts } : {}),
-	};
-}

package/packages/tiny-subagent/tests/run-tests.mjs

@@ -1,111 +0,0 @@
-import { chmodSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
-import { join } from "node:path";
-import { tmpdir } from "node:os";
-import { discoverPackageAgents, parseAgentMarkdown } from "../src/personas.ts";
-import { MAX_INLINE_BYTES, runTinySubagent } from "../src/runner.ts";
-
-let passed = 0;
-let failed = 0;
-function check(name, condition, detail = "") {
-	if (condition) {
-		passed += 1;
-		console.log(`PASS ${name}`);
-	} else {
-		failed += 1;
-		console.log(`FAIL ${name} ${detail}`);
-	}
-}
-
-const root = mkdtempSync(join(tmpdir(), "pi-tiny-subagent-test-"));
-const fakePi = join(root, "fake-pi.mjs");
-writeFileSync(fakePi, `#!/usr/bin/env node
-import { appendFileSync, readFileSync } from "node:fs";
-const args = process.argv.slice(2);
-const capture = process.env.TINY_CAPTURE;
-if (capture) appendFileSync(capture, JSON.stringify({ args, cwd: process.cwd(), child: process.env.PI_SUBAGENT_CHILD, promptFile: args[args.indexOf("--append-system-prompt") + 1] ? readFileSync(args[args.indexOf("--append-system-prompt") + 1], "utf8") : null }) + "\\n");
-const mode = process.env.TINY_MODE || "success";
-if (mode === "abort") { setTimeout(() => {}, 30000); }
-if (mode === "success") {
-  process.stdout.write(JSON.stringify({ type: "message_end", message: { role: "assistant", model: "fake/model", stopReason: "stop", content: [{ type: "text", text: "worker result" }] } }) + "\\n");
-} else if (mode === "events") {
-  process.stdout.write(JSON.stringify({ type: "message_end", message: { role: "assistant", content: [{ type: "toolCall", name: "bash", arguments: { command: "printf live" } }] } }) + "\\n");
-  process.stdout.write(JSON.stringify({ type: "tool_result_end", message: { role: "toolResult", toolName: "bash", toolCallId: "call-1", isError: false, content: [{ type: "text", text: "live result" }] } }) + "\\n");
-  process.stdout.write(JSON.stringify({ type: "message_end", message: { role: "assistant", model: "fake/model", stopReason: "stop", content: [{ type: "text", text: "event result" }] } }) + "\\n");
-} else if (mode === "error") {
-  process.stderr.write("provider failed\\n");
-  process.stdout.write(JSON.stringify({ type: "message_end", message: { role: "assistant", stopReason: "error", errorMessage: "rate limited", content: [] } }) + "\\n");
-  process.exitCode = 7;
-} else if (mode === "protocol") {
-  process.stdout.write("not-json\\n");
-  process.exitCode = 2;
-} else if (mode === "large") {
-  const text = "x".repeat(${MAX_INLINE_BYTES + 1000});
-  process.stderr.write("e".repeat(${MAX_INLINE_BYTES + 1000}));
-  process.stdout.write(JSON.stringify({ type: "message_end", message: { role: "assistant", stopReason: "stop", content: [{ type: "text", text }] } }) + "\\n");
-}
-`, { encoding: "utf8", mode: 0o700 });
-chmodSync(fakePi, 0o700);
-
-const capture = join(root, "capture.jsonl");
-const oldEnv = { ...process.env };
-function setEnv(values) {
-	for (const key of Object.keys(process.env)) delete process.env[key];
-	Object.assign(process.env, oldEnv, values);
-}
-function restoreEnv() {
-	for (const key of Object.keys(process.env)) delete process.env[key];
-	Object.assign(process.env, oldEnv);
-}
-
-try {
-	setEnv({ PI_TINY_SUBAGENT_PI_BINARY: fakePi, TINY_CAPTURE: capture, TINY_MODE: "success" });
-	const success = await runTinySubagent("hello", { cwd: root, model: "fake/model", tools: ["read"], systemPrompt: "You are a worker." });
-	const launch = JSON.parse(readFileSync(capture, "utf8").trim());
-	check("success output", success.ok && success.output === "worker result");
-	check("model, tools, and fresh-process flags", launch.args.includes("--model") && launch.args.includes("fake/model") && launch.args.includes("--tools") && launch.args.includes("read") && launch.args.includes("--no-session") && launch.args.includes("--no-extensions") && launch.args.includes("--no-skills"));
-	check("cwd and child marker", launch.cwd === root && launch.child === "1");
-	check("persona system prompt file", launch.promptFile === "You are a worker.");
-
- setEnv({ PI_TINY_SUBAGENT_PI_BINARY: fakePi, TINY_MODE: "events" });
- const updates = [];
- const events = await runTinySubagent("events", { cwd: root, onUpdate: (partial) => updates.push(partial) });
- check("event transcript and live updates", events.ok && events.output === "event result" && events.messages.length === 3 && events.messages[0].content?.[0]?.type === "toolCall" && events.messages[1].role === "toolResult" && updates.length >= 4 && updates.at(-1).messages.length === 3);
-
-	setEnv({ PI_TINY_SUBAGENT_PI_BINARY: fakePi, TINY_MODE: "error" });
-	const error = await runTinySubagent("fail", { cwd: root });
-	check("Pi error details", !error.ok && error.exitCode === 7 && error.stopReason === "error" && error.errorMessage === "rate limited" && error.stderr.includes("provider failed"));
-	setEnv({ PI_TINY_SUBAGENT_PI_BINARY: fakePi, TINY_MODE: "protocol" });
-	const protocol = await runTinySubagent("bad", { cwd: root });
-	check("protocol error details", !protocol.ok && protocol.exitCode === 2 && protocol.protocolErrors.includes("not-json"));
-
-	setEnv({ PI_TINY_SUBAGENT_PI_BINARY: "/definitely/missing/pi", TINY_MODE: "success" });
-	const missing = await runTinySubagent("missing", { cwd: root });
-	check("spawn error details", !missing.ok && missing.exitCode === 1 && missing.errorMessage?.includes("ENOENT"));
-
-	setEnv({ PI_TINY_SUBAGENT_PI_BINARY: fakePi, TINY_MODE: "large" });
-	const large = await runTinySubagent("large", { cwd: root });
-	check("large output spills to artifacts", large.ok && large.artifacts && large.artifacts.cleanup.includes("remove directory") && large.output.includes("see artifact file") && large.outputBytes > MAX_INLINE_BYTES && large.artifacts.finalOutput && readFileSync(large.artifacts.finalOutput, "utf8").length > MAX_INLINE_BYTES);
-	if (large.artifacts) rmSync(large.artifacts.directory, { recursive: true, force: true });
-
-	setEnv({ PI_TINY_SUBAGENT_PI_BINARY: fakePi, TINY_MODE: "abort" });
-	const controller = new AbortController();
-	const pending = runTinySubagent("abort", { cwd: root, signal: controller.signal });
-	setTimeout(() => controller.abort(), 50);
-	const aborted = await pending;
-	check("abort details", !aborted.ok && aborted.errorMessage === "Tiny subagent was aborted");
-
-	const definition = parseAgentMarkdown(`---\nname: reviewer\ndescription: Review code\nmodel: fake/model\ntools: read, grep\n---\nReview carefully.`, "reviewer.md");
-	check("persona frontmatter parsing", definition.name === "reviewer" && definition.model === "fake/model" && definition.tools?.join(",") === "read,grep" && definition.systemPrompt === "Review carefully.");
-	const agentsDir = join(root, "agents");
-	await import("node:fs/promises").then(({ mkdir }) => mkdir(agentsDir));
-	writeFileSync(join(agentsDir, "worker.md"), `---\nname: worker\ndescription: Worker\n---\nDo work.`);
-	writeFileSync(join(agentsDir, "broken.md"), "not frontmatter");
-	const discovery = discoverPackageAgents(agentsDir);
-	check("persona discovery and diagnostics", discovery.agents.length === 1 && discovery.agents[0].name === "worker" && discovery.diagnostics.length === 1);
-} finally {
-	restoreEnv();
-	rmSync(root, { recursive: true, force: true });
-}
-
-console.log(`${passed} passed, ${failed} failed`);
-if (failed > 0) process.exitCode = 1;

package/skills/calldiff/LICENSE

@@ -1,21 +0,0 @@
-MIT License
-
-Copyright (c) 2026 Tanishq Kancharla
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.

package/skills/calldiff/NOTICE

@@ -1,19 +0,0 @@
-calldiff Skill
-
-This directory is copied verbatim from the calldiff repository:
-https://github.com/tanishqkancharla/calldiff
-skills/calldiff/SKILL.md at commit 2086f6e4e9ed3c410bba7c94ca3dde77791b1956 (main)
-
-The upstream repository is licensed under the MIT License. A copy of that
-license is included in LICENSE.
-
-Upstream publishes no release tags, so this file is pinned to a main commit
-instead of a tag. The CLI can also write its own copy with `calldiff skills
-add` (to ~/.agents/skills/calldiff/SKILL.md), but that generated file is terser
-than the committed one — it leaves the --entry/--file descriptions empty and
-says 22 languages — so pi-toolkit ships the committed file.
-
-To refresh, copy skills/calldiff/SKILL.md and LICENSE from a newer upstream
-commit and update the commit above. The bundled commands were smoke-tested
-against calldiff 0.5.0 (`diff`, `tree`, `reach`, `--entry`, `--file`,
-`--maxDepth`/`--max-depth`, `--locs`, `--format json`).

package/skills/calldiff/SKILL.md

@@ -1,121 +0,0 @@
----
-name: calldiff
-description: Diff call stacks across git commits — like git diff, but for who-calls-whom. Shows which callees appeared, disappeared, or moved under an entrypoint across 23 languages (diff, tree, and reach). Use for agentic code review when call flow changed and line diffs bury the shape of the change.
-requires_bin: calldiff
-command: calldiff
----
-
-# calldiff diff
-
-Diff call stacks between two git trees
-
-## Arguments
-
-| Name | Type | Required | Description |
-|------|------|----------|-------------|
-| `from` | `string` | no | Before ref (default: HEAD) |
-| `to` | `string` | no | After ref (default: working tree) |
-| `paths` | `array` | no | Limit to these path prefixes |
-
-## Options
-
-| Flag | Type | Default | Description |
-|------|------|---------|-------------|
-| `--entry` | `unknown` |  | Entrypoint symbol(s): functionName or ClassName.method |
-| `--file` | `unknown` |  | Entrypoint file(s): indexed source path; expands to that file's exports |
-| `--maxDepth` | `number` | `12` | Max call-tree depth |
-| `--locs` | `boolean` | `false` | Show call-site source locations (file:line) |
-| `--from` | `string` |  | Left / "before" tree |
-| `--to` | `string` |  | Right / "after" tree |
-
-## Examples
-
-```sh
-# HEAD vs working tree
-calldiff diff
-
-# One ref vs working tree
-calldiff diff main
-
-# Two commits / branches
-calldiff diff abc123 def456
-
-# Force entrypoints
-calldiff diff main feature --entry createAgentSession
-
-# File expands to that file's exports
-calldiff diff main feature --file src/routes.ts
-```
-
-> Semantics match git diff: no refs → HEAD vs worktree; one ref → that vs worktree; two refs → compare those trees.
-
----
-
-# calldiff reach
-
-Find all call paths from an entrypoint to a target symbol
-
-## Arguments
-
-| Name | Type | Required | Description |
-|------|------|----------|-------------|
-| `ref` | `string` | no | Git ref (default: working tree) |
-| `paths` | `array` | no | Limit to these path prefixes |
-
-## Options
-
-| Flag | Type | Default | Description |
-|------|------|---------|-------------|
-| `--entry` | `unknown` |  | Entrypoint symbol(s): functionName or ClassName.method |
-| `--file` | `unknown` |  | Entrypoint file(s): indexed source path; expands to that file's exports |
-| `--to` | `string` |  | Target symbol to reach (functionName or ClassName.method) |
-| `--maxDepth` | `number` | `12` | Max call-tree depth |
-| `--locs` | `boolean` | `false` | Show call-site source locations (file:line) |
-
-## Examples
-
-```sh
-# Paths in the working tree
-calldiff reach --entry runCheckout --to sendEmail
-
-# Paths at a commit, limited to a directory
-calldiff reach HEAD examples/checkout --entry runCheckout --to sendEmail
-
-# Paths from every export in a file
-calldiff reach --file packages/api/src/flow.ts --to notify
-```
-
----
-
-# calldiff tree
-
-View a call tree (no diff) for one or more entrypoints
-
-## Arguments
-
-| Name | Type | Required | Description |
-|------|------|----------|-------------|
-| `ref` | `string` | no | Git ref (default: working tree) |
-| `paths` | `array` | no | Limit to these path prefixes |
-
-## Options
-
-| Flag | Type | Default | Description |
-|------|------|---------|-------------|
-| `--entry` | `unknown` |  | Entrypoint symbol(s): functionName or ClassName.method |
-| `--file` | `unknown` |  | Entrypoint file(s): indexed source path; expands to that file's exports |
-| `--maxDepth` | `number` | `12` | Max call-tree depth |
-| `--locs` | `boolean` | `false` | Show call-site source locations (file:line) |
-
-## Examples
-
-```sh
-# Tree from working tree
-calldiff tree --entry createAgentSession
-
-# Tree from a commit
-calldiff tree HEAD --entry PiService.createAgentSession
-
-# Every export in a file
-calldiff tree --file packages/api/src/routes.ts
-```