pi-onedev-toolkit 0.1.0 → 0.2.0

package/src/tools/build.ts

@@ -1,7 +1,11 @@
+import { copyFile, mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { isAbsolute, join, resolve } from "node:path";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { StringEnum } from "@earendil-works/pi-ai";
 import { Type, type Static } from "typebox";
 import {
+	confirmMutation,
 	pushRepeated,
 	QUERY_DESCRIPTION,
 	REF_DESCRIPTION,
@@ -11,13 +15,20 @@ import {
 	withFooter,
 	type ToolDeps,
 } from "./common.js";
-import { BUILD_RUN_TIMEOUT_MS } from "../tod.js";
+import {
+	BUILD_RUN_TIMEOUT_MS,
+	runTod,
+	TodError,
+	type TodOutput,
+} from "../tod.js";
+import type { MutationOperation } from "../mutation-approvals.js";
 
 const BUILD_ACTIONS = [
 	"list",
 	"get",
 	"get_log",
 	"get_code_problems",
+	"get_unit_test_report",
 	"get_changes_since_success",
 	"run",
 	"check_spec",
@@ -26,13 +37,18 @@ const BUILD_ACTIONS = [
 ] as const;
 export type BuildAction = (typeof BUILD_ACTIONS)[number];
 
+const BUILD_MUTATIONS: Partial<Record<BuildAction, MutationOperation>> = {
+	run: "build.run",
+	check_spec: "build.check_spec",
+};
+
 export const SEVERITY_LEVELS = ["CRITICAL", "HIGH", "MEDIUM", "LOW"] as const;
 export const RUN_MODES = ["local", "branch", "tag"] as const;
 
 export interface BuildParams {
 	action?: BuildAction;
 	ref?: string;
-	reportName?: string;
+	report_name?: string;
 	severity?: (typeof SEVERITY_LEVELS)[number];
 	job?: string;
 	mode?: (typeof RUN_MODES)[number];
@@ -67,23 +83,42 @@ export function buildBuildArgs(params: BuildParams): string[] {
 				...args,
 				"get-code-problems",
 				ref(),
-				requireParam(params.reportName, action, "report_name"),
+				requireParam(params.report_name, action, "report_name"),
 				requireParam(params.severity, action, "severity"),
 			];
+		case "get_unit_test_report":
+			return [
+				...args,
+				"get-unit-test-report",
+				ref(),
+				requireParam(params.report_name, action, "report_name"),
+			];
 		case "get_changes_since_success":
 			return [...args, "get-changes-since-success", ref()];
 		case "run":
 			args.push("run", requireParam(params.job, action, "job"));
+			if (params.branch !== undefined && params.tag !== undefined) {
+				throw new Error("run accepts either branch or tag, not both");
+			}
+			if (
+				params.mode === "local" &&
+				(params.branch !== undefined || params.tag !== undefined)
+			) {
+				throw new Error("local run mode does not accept branch or tag");
+			}
+			if (params.mode === "branch" && params.tag !== undefined) {
+				throw new Error("branch run mode does not accept tag");
+			}
+			if (params.mode === "tag" && params.branch !== undefined) {
+				throw new Error("tag run mode does not accept branch");
+			}
 			if (
 				params.mode === "local" ||
 				(params.mode === undefined && !params.branch && !params.tag)
 			) {
 				args.push("--local");
 			} else if (params.mode === "branch" || params.branch !== undefined) {
-				args.push(
-					"--branch",
-					requireParam(params.branch ?? params.job, action, "branch"),
-				);
+				args.push("--branch", requireParam(params.branch, action, "branch"));
 			} else {
 				args.push("--tag", requireParam(params.tag, action, "tag"));
 			}
@@ -95,6 +130,72 @@ export function buildBuildArgs(params: BuildParams): string[] {
 			return [...args, "get-spec-schema"];
 		case "query_description":
 			return [...args, "get-query-description"];
+		default:
+			throw new Error(`unsupported build action: ${String(action)}`);
+	}
+}
+
+async function ensureUnitTestReportSupport(
+	deps: ToolDeps,
+	signal?: AbortSignal,
+): Promise<void> {
+	const help = await runInContext(deps, ["build", "--help"], {
+		signal,
+		maxOutputBytes: 12_000,
+	});
+	if (!/^\s+get-unit-test-report\s/m.test(help.text)) {
+		throw new TodError(
+			"the installed tod does not support build get-unit-test-report; update tod from https://code.onedev.io/onedev/tod",
+		);
+	}
+}
+
+async function runLocalBuildWithIsolatedIndex(
+	deps: ToolDeps,
+	args: string[],
+	signal?: AbortSignal,
+): Promise<TodOutput> {
+	if (process.platform === "win32") {
+		throw new TodError(
+			"local build mode is disabled on Windows because TOD modifies the git index; use branch or tag mode",
+		);
+	}
+	const context = deps.context();
+	const indexResult = await deps.exec(
+		"git",
+		["rev-parse", "--git-path", "index"],
+		{ cwd: context.cwd, timeout: 10_000, signal },
+	);
+	if (indexResult.killed || indexResult.code !== 0) {
+		throw new TodError(
+			`could not isolate the git index for local build mode: ${(indexResult.stderr || indexResult.stdout).trim() || "git rev-parse failed"}`,
+		);
+	}
+	const indexPath = indexResult.stdout.trim();
+	const sourceIndex = isAbsolute(indexPath)
+		? indexPath
+		: resolve(context.cwd, indexPath);
+	const directory = await mkdtemp(join(tmpdir(), "pi-onedev-index-"));
+	const isolatedIndex = join(directory, "index");
+	try {
+		await copyFile(sourceIndex, isolatedIndex);
+		return await runTod(deps.exec, args, {
+			cwd: context.cwd,
+			signal,
+			timeoutMs: BUILD_RUN_TIMEOUT_MS,
+			maxOutputBytes: 24_000,
+			environment: { GIT_INDEX_FILE: isolatedIndex },
+		});
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code === "ENOENT") {
+			throw new TodError(
+				"local build mode requires an existing git index and at least one commit",
+				{ cause: error },
+			);
+		}
+		throw error;
+	} finally {
+		await rm(directory, { recursive: true, force: true });
 	}
 }
 
@@ -102,10 +203,10 @@ export function registerBuildTool(pi: ExtensionAPI, deps: ToolDeps): void {
 	const parameters = Type.Object({
 		action: StringEnum(BUILD_ACTIONS, {
 			description:
-				"list, get, get_log, get_code_problems (needs report_name+severity), get_changes_since_success, run (job against local/branch/tag), check_spec (validate .onedev-buildspec.yml), get_spec_schema, query_description",
+				"list, get, get_log, get_code_problems, get_unit_test_report, get_changes_since_success, run, check_spec (may upgrade .onedev-buildspec.yml), get_spec_schema, query_description",
 		}),
 		ref: Type.Optional(Type.String({ description: REF_DESCRIPTION })),
-		reportName: Type.Optional(
+		report_name: Type.Optional(
 			Type.String({ description: "Report name quoted in the build log" }),
 		),
 		severity: Type.Optional(StringEnum(SEVERITY_LEVELS)),
@@ -137,7 +238,7 @@ export function registerBuildTool(pi: ExtensionAPI, deps: ToolDeps): void {
 		query: Type.Optional(Type.String({ description: QUERY_DESCRIPTION })),
 		count: Type.Optional(Type.Integer({ minimum: 1, maximum: 100 })),
 		offset: Type.Optional(Type.Integer({ minimum: 0 })),
-	});
+	}, { additionalProperties: false });
 	type Params = Static<typeof parameters>;
 
 	pi.registerTool({
@@ -145,19 +246,40 @@ export function registerBuildTool(pi: ExtensionAPI, deps: ToolDeps): void {
 		label: "OneDev Builds",
 		description:
 			"Inspect OneDev CI/CD: query builds, read logs and code-problem reports, diff changes since the last success, validate the build spec, and run jobs (including against uncommitted local changes).",
-		promptGuidelines: [
-			"Use onedev_build get_log before guessing at build failures.",
-			"run with mode=local pushes uncommitted changes to a temporary server ref; prefer it over committing just to test.",
-		],
 		parameters,
-		async execute(_toolCallId, params: Params, signal) {
+		async execute(_toolCallId, params: Params, signal, _onUpdate, ctx) {
 			const isRun = params.action === "run";
-			// ponytail: build run streams the full log; keep the tail, the failure sits at the end
-			const output = await runInContext(deps, buildBuildArgs(params), {
-				signal,
-				timeoutMs: isRun ? BUILD_RUN_TIMEOUT_MS : undefined,
-				maxOutputBytes: isRun ? 24_000 : undefined,
-			});
+			const args = buildBuildArgs(params);
+			if (params.action === "get_unit_test_report") {
+				await ensureUnitTestReportSupport(deps, signal);
+			}
+			const operation = BUILD_MUTATIONS[params.action];
+			if (operation) {
+				await confirmMutation(deps, ctx, {
+					operation,
+					title: `Approve OneDev build action: ${params.action}`,
+					details:
+						params.action === "check_spec"
+							? "TOD may upgrade .onedev-buildspec.yml in the working tree."
+							: `Job: ${params.job ?? "?"} · mode: ${params.mode ?? "local"}`,
+					signal,
+				});
+			}
+			// ponytail: build run streams the full log; preserve bounded metadata and the failure tail
+			const isLocalRun =
+				isRun &&
+				(params.mode === "local" ||
+					(params.mode === undefined && !params.branch && !params.tag));
+			let output: TodOutput;
+			if (isLocalRun) {
+				output = await runLocalBuildWithIsolatedIndex(deps, args, signal);
+			} else {
+				output = await runInContext(deps, args, {
+					signal,
+					timeoutMs: isRun ? BUILD_RUN_TIMEOUT_MS : undefined,
+					maxOutputBytes: isRun ? 24_000 : undefined,
+				});
+			}
 			return toolResult(
 				withFooter(output.text, deps.context(), output.truncated),
 				{

package/src/tools/common.ts

@@ -1,4 +1,12 @@
-import type { OneDevSessionContext } from "../context.js";
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type {
+	ContextRefreshOptions,
+	OneDevSessionContext,
+} from "../context.js";
+import type {
+	MutationApprovalManager,
+	MutationApprovalRequest,
+} from "../mutation-approvals.js";
 import {
 	TodError,
 	runTod,
@@ -10,6 +18,10 @@ export interface ToolDeps {
 	exec: CommandExecutor;
 	/** Session OneDev context; throws a friendly error before initialization. */
 	context: () => OneDevSessionContext;
+	refreshContext: (
+		options?: ContextRefreshOptions,
+	) => Promise<OneDevSessionContext>;
+	approvals: MutationApprovalManager;
 }
 
 export const REF_DESCRIPTION =
@@ -43,6 +55,12 @@ export async function runInContext(
 	} = {},
 ): Promise<TodOutput> {
 	const context = deps.context();
+	if (context.status !== "ready" || !context.project) {
+		throw new TodError(
+			context.problem ??
+				"OneDev tools require a repository whose project can be inferred from a OneDev remote",
+		);
+	}
 	return runTod(deps.exec, args, {
 		cwd: context.cwd,
 		signal: options.signal,
@@ -71,22 +89,19 @@ export function pushRepeated(
 	for (const value of values ?? []) args.push(flag, value);
 }
 
-export function confirmGate(
-	action: string,
-	confirmed: boolean | undefined,
-): void {
-	if (confirmed !== true) {
-		throw new TodError(
-			`action '${action}' changes remote state; re-run with confirm: true once the user has approved it`,
-		);
-	}
+export function confirmMutation(
+	deps: ToolDeps,
+	ctx: ExtensionContext,
+	request: MutationApprovalRequest,
+): Promise<void> {
+	return deps.approvals.confirm(deps.context(), ctx, request);
 }
 
-export function contextFooter(context: OneDevSessionContext): string {
+function contextFooter(context: OneDevSessionContext): string {
 	if (context.status === "ready" && context.project) {
 		return `Context: project ${context.project} · server ${context.serverUrl}`;
 	}
-	return `Context: server ${context.serverUrl ?? "?"} · no project inferred from git remotes; qualify refs or pass project explicitly`;
+	return `Context unavailable: ${context.problem ?? "no OneDev project inferred from git remotes"}`;
 }
 
 export function withFooter(

package/src/tools/index.ts

@@ -1,29 +1,34 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { StringEnum } from "@earendil-works/pi-ai";
 import { Type } from "typebox";
-import { formatContext } from "../context.js";
-import { runInContext, toolResult, type ToolDeps } from "./common.js";
+import { formatContext, setupGuidance } from "../context.js";
+import type { OneDevSourceWatchManager } from "../source-watch.js";
+import { toolResult, type ToolDeps } from "./common.js";
 import { registerBuildTool } from "./build.js";
 import { registerIssueTool } from "./issue.js";
 import { registerPullTool } from "./pull.js";
+import { registerWatchTool } from "./watch.js";
 
-const ONEDev_TOOL_DOMAINS = ["issue", "pull", "build"] as const;
-type OneDevToolDomain = (typeof ONEDev_TOOL_DOMAINS)[number];
+const ONEDEV_TOOL_DOMAINS = ["issue", "pull", "build", "watch"] as const;
+type OneDevToolDomain = (typeof ONEDEV_TOOL_DOMAINS)[number];
 
+const ALWAYS_ACTIVE_TOOLS = ["onedev_context", "onedev_tools"] as const;
 const LAZY_TOOL_NAMES = [
 	"onedev_issue",
 	"onedev_pull",
 	"onedev_build",
+	"onedev_watch",
 ] as const;
 const LAZY_TOOLS = new Set<string>(LAZY_TOOL_NAMES);
 const DOMAIN_TOOL_NAMES = {
 	issue: ["onedev_issue"],
 	pull: ["onedev_pull"],
 	build: ["onedev_build"],
+	watch: ["onedev_watch"],
 } as const satisfies Record<OneDevToolDomain, readonly string[]>;
 
 export interface OnedevToolController {
-	/** Deactivate lazy OneDev tools unless the user explicitly enabled them. */
+	/** Restore only the small context/loader surface at session boundaries. */
 	reset(): void;
 }
 
@@ -34,93 +39,116 @@ function supportsDynamicTools(pi: ExtensionAPI): boolean {
 	);
 }
 
+function registerContextTool(pi: ExtensionAPI, deps: ToolDeps): void {
+	pi.registerTool({
+		name: "onedev_context",
+		label: "OneDev Context",
+		description:
+			"Inspect OneDev readiness without loading domain tools. Use health for an authenticated re-check and setup for actionable configuration guidance.",
+		parameters: Type.Object(
+			{
+				action: StringEnum(["current", "health", "login_name", "setup"]),
+			},
+			{ additionalProperties: false },
+		),
+		async execute(_toolCallId, params, signal) {
+			if (params.action === "current") {
+				return toolResult(formatContext(deps.context()));
+			}
+			if (params.action === "setup") {
+				return toolResult(setupGuidance(deps.context()));
+			}
+			const context = await deps.refreshContext({
+				verifyAuth: true,
+				force: true,
+				signal,
+			});
+			if (params.action === "login_name" && context.status === "ready") {
+				return toolResult(context.loginName ?? "(no login name)");
+			}
+			return toolResult(formatContext(context));
+		},
+	});
+}
+
 export function registerOnedevTools(
 	pi: ExtensionAPI,
 	deps: ToolDeps,
+	watches: OneDevSourceWatchManager,
 ): OnedevToolController {
+	registerContextTool(pi, deps);
 	registerIssueTool(pi, deps);
 	registerPullTool(pi, deps);
 	registerBuildTool(pi, deps);
+	registerWatchTool(pi, watches);
 
 	pi.registerTool({
 		name: "onedev_tools",
 		label: "OneDev Tools",
 		description:
-			"Activate OneDev tool domains for the current task, or inspect the session OneDev context (server, project inferred from git remotes, login). Misc actions: download linked issue/PR resources.",
+			"Activate only the OneDev domains needed for the current task. Returns authenticated server, project, and login context with the activation result.",
 		promptGuidelines: [
-			"Use onedev_tools before an unavailable OneDev operation.",
+			"Use onedev_tools before an unavailable OneDev domain operation.",
 		],
-		parameters: Type.Object({
-			action: StringEnum(["activate", "context", "login_name", "download"], {
-				description:
-					"activate (default; pass domains), context (server/project/user), login_name, download (fetch an issue/PR-attached resource)",
-			}),
-			domains: Type.Optional(
-				Type.Array(StringEnum(ONEDev_TOOL_DOMAINS), {
+		parameters: Type.Object(
+			{
+				action: StringEnum(["activate"]),
+				domains: Type.Array(StringEnum(ONEDEV_TOOL_DOMAINS), {
 					minItems: 1,
-					maxItems: 3,
+					maxItems: 4,
 					uniqueItems: true,
-					description: "issue, pull, build — activate all you need in one call",
+					description: "Activate issue, pull, build, and/or watch in one call",
 				}),
-			),
-			url: Type.Optional(
-				Type.String({
-					description:
-						"download: resource URL exactly as it appears in the markdown",
-				}),
-			),
-			outputFile: Type.Optional(
-				Type.String({
-					description: "download: local path to write the resource to",
-				}),
-			),
-		}),
+			},
+			{ additionalProperties: false },
+		),
 		async execute(_toolCallId, params, signal) {
-			const action = params.action ?? "activate";
-			if (action === "activate") {
-				const requested = params.domains ?? [...ONEDev_TOOL_DOMAINS];
-				if (!supportsDynamicTools(pi)) {
-					return toolResult(
-						"Dynamic OneDev tool activation is unavailable in this Pi version; registered tools remain unchanged.",
-						{ requested },
-					);
-				}
-				const selected = [
-					...new Set(requested.flatMap((domain) => DOMAIN_TOOL_NAMES[domain])),
-				];
-				const active = pi.getActiveTools();
-				const added = selected.filter((name) => !active.includes(name));
-				if (added.length > 0) pi.setActiveTools([...active, ...added]);
+			const context = await deps.refreshContext({ verifyAuth: true, signal });
+			if (context.status !== "ready") {
 				return toolResult(
-					added.length > 0
-						? `Enabled OneDev tools: ${added.join(", ")}`
-						: `Requested OneDev tools already active: ${selected.join(", ")}`,
-					{ requested, added },
+					`${formatContext(context)}\nNo domain tools were activated. Use onedev_context setup for the next step.`,
+					{ requested: params.domains, added: [] },
 				);
 			}
-			if (action === "context") {
-				return toolResult(formatContext(deps.context()));
-			}
-			if (action === "login_name") {
-				const output = await runInContext(deps, ["get-login-name"], { signal });
-				return toolResult(output.text || "(no login name)");
-			}
-			if (!params.url || !params.outputFile) {
-				throw new Error("download requires url and output_file");
+			if (!supportsDynamicTools(pi)) {
+				return toolResult(
+					`Dynamic OneDev tool activation is unavailable in this Pi version.\n${formatContext(context)}`,
+					{ requested: params.domains, added: [] },
+				);
 			}
-			await runInContext(deps, ["download", params.url, params.outputFile], {
-				signal,
+			const selected = [
+				...new Set(
+					params.domains.flatMap((domain) => DOMAIN_TOOL_NAMES[domain]),
+				),
+			];
+			const active = pi.getActiveTools();
+			const added = selected.filter((name) => !active.includes(name));
+			if (added.length > 0) pi.setActiveTools([...active, ...added]);
+			const activation =
+				added.length > 0
+					? `Enabled OneDev tools: ${added.join(", ")}`
+					: `Requested OneDev tools already active: ${selected.join(", ")}`;
+			return toolResult(`${activation}\n${formatContext(context)}`, {
+				requested: params.domains,
+				added,
 			});
-			return toolResult(`Downloaded ${params.url} to ${params.outputFile}`);
 		},
 	});
 
 	return {
 		reset() {
 			if (!supportsDynamicTools(pi)) return;
-			const active = pi.getActiveTools();
-			if (!active.includes("onedev_tools")) return;
-			pi.setActiveTools(active.filter((name) => !LAZY_TOOLS.has(name)));
+			const current = pi.getActiveTools();
+			const next = current.filter((name) => !LAZY_TOOLS.has(name));
+			for (const name of ALWAYS_ACTIVE_TOOLS) {
+				if (!next.includes(name)) next.push(name);
+			}
+			if (
+				next.length !== current.length ||
+				next.some((name, index) => name !== current[index])
+			) {
+				pi.setActiveTools(next);
+			}
 		},
 	};
 }