pi-onedev-toolkit 0.1.0

package/src/tools/build.ts

@@ -0,0 +1,170 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { StringEnum } from "@earendil-works/pi-ai";
+import { Type, type Static } from "typebox";
+import {
+	pushRepeated,
+	QUERY_DESCRIPTION,
+	REF_DESCRIPTION,
+	requireParam,
+	runInContext,
+	toolResult,
+	withFooter,
+	type ToolDeps,
+} from "./common.js";
+import { BUILD_RUN_TIMEOUT_MS } from "../tod.js";
+
+const BUILD_ACTIONS = [
+	"list",
+	"get",
+	"get_log",
+	"get_code_problems",
+	"get_changes_since_success",
+	"run",
+	"check_spec",
+	"get_spec_schema",
+	"query_description",
+] as const;
+export type BuildAction = (typeof BUILD_ACTIONS)[number];
+
+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;
+	severity?: (typeof SEVERITY_LEVELS)[number];
+	job?: string;
+	mode?: (typeof RUN_MODES)[number];
+	branch?: string;
+	tag?: string;
+	params?: string[];
+	project?: string;
+	query?: string;
+	count?: number;
+	offset?: number;
+}
+
+export function buildBuildArgs(params: BuildParams): string[] {
+	const args: string[] = ["build"];
+	const action = requireParam(params.action, "build", "action");
+	const ref = (): string => requireParam(params.ref, action, "ref");
+	switch (action) {
+		case "list":
+			args.push("list");
+			if (params.project !== undefined) args.push("--project", params.project);
+			if (params.query !== undefined) args.push("--query", params.query);
+			if (params.offset !== undefined)
+				args.push("--offset", String(params.offset));
+			args.push("--count", String(params.count ?? 25));
+			return args;
+		case "get":
+			return [...args, "get", ref()];
+		case "get_log":
+			return [...args, "get-log", ref()];
+		case "get_code_problems":
+			return [
+				...args,
+				"get-code-problems",
+				ref(),
+				requireParam(params.reportName, action, "report_name"),
+				requireParam(params.severity, action, "severity"),
+			];
+		case "get_changes_since_success":
+			return [...args, "get-changes-since-success", ref()];
+		case "run":
+			args.push("run", requireParam(params.job, action, "job"));
+			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"),
+				);
+			} else {
+				args.push("--tag", requireParam(params.tag, action, "tag"));
+			}
+			pushRepeated(args, "-p", params.params);
+			return args;
+		case "check_spec":
+			return [...args, "check-spec"];
+		case "get_spec_schema":
+			return [...args, "get-spec-schema"];
+		case "query_description":
+			return [...args, "get-query-description"];
+	}
+}
+
+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",
+		}),
+		ref: Type.Optional(Type.String({ description: REF_DESCRIPTION })),
+		reportName: Type.Optional(
+			Type.String({ description: "Report name quoted in the build log" }),
+		),
+		severity: Type.Optional(StringEnum(SEVERITY_LEVELS)),
+		job: Type.Optional(
+			Type.String({ description: "Job name defined in .onedev-buildspec.yml" }),
+		),
+		mode: Type.Optional(
+			StringEnum(RUN_MODES, {
+				description:
+					"run: local (uncommitted changes), branch, or tag; default local",
+			}),
+		),
+		branch: Type.Optional(
+			Type.String({ description: "run with mode=branch: branch to run against" }),
+		),
+		tag: Type.Optional(
+			Type.String({ description: "run with mode=tag: tag to run against" }),
+		),
+		params: Type.Optional(
+			Type.Array(Type.String(), {
+				description: 'Job parameters as "key=value", repeatable (-p)',
+			}),
+		),
+		project: Type.Optional(
+			Type.String({
+				description: "Project path for list; defaults to the current project",
+			}),
+		),
+		query: Type.Optional(Type.String({ description: QUERY_DESCRIPTION })),
+		count: Type.Optional(Type.Integer({ minimum: 1, maximum: 100 })),
+		offset: Type.Optional(Type.Integer({ minimum: 0 })),
+	});
+	type Params = Static<typeof parameters>;
+
+	pi.registerTool({
+		name: "onedev_build",
+		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) {
+			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,
+			});
+			return toolResult(
+				withFooter(output.text, deps.context(), output.truncated),
+				{
+					action: params.action,
+					truncated: output.truncated,
+				},
+			);
+		},
+	});
+}

package/src/tools/common.ts

@@ -0,0 +1,102 @@
+import type { OneDevSessionContext } from "../context.js";
+import {
+	TodError,
+	runTod,
+	type CommandExecutor,
+	type TodOutput,
+} from "../tod.js";
+
+export interface ToolDeps {
+	exec: CommandExecutor;
+	/** Session OneDev context; throws a friendly error before initialization. */
+	context: () => OneDevSessionContext;
+}
+
+export const REF_DESCRIPTION =
+	"OneDev reference: plain number (123), #number, project#number (myproject#123), or issue key (PROJ-123). Plain numbers resolve against the current repository's project.";
+export const FIELDS_DESCRIPTION =
+	'Issue field assignments as "key=value" strings, repeatable. Discover valid fields and values with the valid_fields action.';
+export const QUERY_DESCRIPTION =
+	"OneDev query, e.g. '\"State\" is \"Open\"' or 'assignee is me'. Syntax reference: query_description action.";
+
+export function toolResult(
+	text: string,
+	data?: unknown,
+): {
+	content: Array<{ type: "text"; text: string }>;
+	details: { data?: unknown };
+} {
+	return {
+		content: [{ type: "text", text }],
+		details: data === undefined ? {} : { data },
+	};
+}
+
+/** Run tod with session cwd and pass the abort signal through. */
+export async function runInContext(
+	deps: ToolDeps,
+	args: readonly string[],
+	options: {
+		timeoutMs?: number;
+		signal?: AbortSignal;
+		maxOutputBytes?: number;
+	} = {},
+): Promise<TodOutput> {
+	const context = deps.context();
+	return runTod(deps.exec, args, {
+		cwd: context.cwd,
+		signal: options.signal,
+		timeoutMs: options.timeoutMs,
+		maxOutputBytes: options.maxOutputBytes,
+	});
+}
+
+export function requireParam<T>(
+	value: T | undefined,
+	action: string,
+	name: string,
+): T {
+	if (value === undefined || value === null) {
+		throw new TodError(`action '${action}' requires parameter '${name}'`);
+	}
+	return value;
+}
+
+/** Append `--flag value` pairs for every entry of a repeatable string array. */
+export function pushRepeated(
+	args: string[],
+	flag: string,
+	values: readonly string[] | undefined,
+): void {
+	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 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`;
+}
+
+export function withFooter(
+	body: string,
+	context: OneDevSessionContext,
+	truncated: boolean,
+): string {
+	const parts = [body || "(no output)"];
+	if (truncated)
+		parts.push("(output truncated; narrow the query or fetch a single entity)");
+	parts.push(contextFooter(context));
+	return parts.filter(Boolean).join("\n\n");
+}

package/src/tools/index.ts

@@ -0,0 +1,126 @@
+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 { registerBuildTool } from "./build.js";
+import { registerIssueTool } from "./issue.js";
+import { registerPullTool } from "./pull.js";
+
+const ONEDev_TOOL_DOMAINS = ["issue", "pull", "build"] as const;
+type OneDevToolDomain = (typeof ONEDev_TOOL_DOMAINS)[number];
+
+const LAZY_TOOL_NAMES = [
+	"onedev_issue",
+	"onedev_pull",
+	"onedev_build",
+] as const;
+const LAZY_TOOLS = new Set<string>(LAZY_TOOL_NAMES);
+const DOMAIN_TOOL_NAMES = {
+	issue: ["onedev_issue"],
+	pull: ["onedev_pull"],
+	build: ["onedev_build"],
+} as const satisfies Record<OneDevToolDomain, readonly string[]>;
+
+export interface OnedevToolController {
+	/** Deactivate lazy OneDev tools unless the user explicitly enabled them. */
+	reset(): void;
+}
+
+function supportsDynamicTools(pi: ExtensionAPI): boolean {
+	return (
+		typeof pi.getActiveTools === "function" &&
+		typeof pi.setActiveTools === "function"
+	);
+}
+
+export function registerOnedevTools(
+	pi: ExtensionAPI,
+	deps: ToolDeps,
+): OnedevToolController {
+	registerIssueTool(pi, deps);
+	registerPullTool(pi, deps);
+	registerBuildTool(pi, deps);
+
+	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.",
+		promptGuidelines: [
+			"Use onedev_tools before an unavailable OneDev 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), {
+					minItems: 1,
+					maxItems: 3,
+					uniqueItems: true,
+					description: "issue, pull, build — activate all you need 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",
+				}),
+			),
+		}),
+		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]);
+				return toolResult(
+					added.length > 0
+						? `Enabled OneDev tools: ${added.join(", ")}`
+						: `Requested OneDev tools already active: ${selected.join(", ")}`,
+					{ requested, 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");
+			}
+			await runInContext(deps, ["download", params.url, params.outputFile], {
+				signal,
+			});
+			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)));
+		},
+	};
+}

package/src/tools/issue.ts

@@ -0,0 +1,225 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { StringEnum } from "@earendil-works/pi-ai";
+import { Type, type Static } from "typebox";
+import {
+	confirmGate,
+	FIELDS_DESCRIPTION,
+	pushRepeated,
+	QUERY_DESCRIPTION,
+	REF_DESCRIPTION,
+	requireParam,
+	runInContext,
+	toolResult,
+	withFooter,
+	type ToolDeps,
+} from "./common.js";
+
+const ISSUE_ACTIONS = [
+	"list",
+	"get",
+	"get_comments",
+	"create",
+	"edit",
+	"change_state",
+	"add_comment",
+	"link",
+	"log_work",
+	"create_branch",
+	"checkout",
+	"current_reference",
+	"valid_fields",
+	"valid_links",
+	"query_description",
+] as const;
+export type IssueAction = (typeof ISSUE_ACTIONS)[number];
+
+export interface IssueParams {
+	action?: IssueAction;
+	ref?: string;
+	title?: string;
+	description?: string;
+	state?: string;
+	comment?: string;
+	content?: string;
+	linkName?: string;
+	targetRef?: string;
+	hours?: number;
+	fields?: string[];
+	iterations?: string[];
+	ownEstimatedTime?: number;
+	confidential?: boolean;
+	forWrite?: boolean;
+	project?: string;
+	query?: string;
+	count?: number;
+	offset?: number;
+}
+
+export function buildIssueArgs(params: IssueParams): string[] {
+	const args: string[] = ["issue"];
+	const action = requireParam(params.action, "issue", "action");
+	const ref = (): string => requireParam(params.ref, action, "ref");
+	switch (action) {
+		case "list":
+			args.push("list");
+			if (params.project !== undefined) args.push("--project", params.project);
+			if (params.query !== undefined) args.push("--query", params.query);
+			if (params.offset !== undefined)
+				args.push("--offset", String(params.offset));
+			args.push("--count", String(params.count ?? 25));
+			return args;
+		case "get":
+			return [...args, "get", ref()];
+		case "get_comments":
+			return [...args, "get-comments", ref()];
+		case "create":
+			args.push("create", requireParam(params.title, action, "title"));
+			if (params.description !== undefined)
+				args.push("--description", params.description);
+			if (params.project !== undefined) args.push("--project", params.project);
+			pushRepeated(args, "--field", params.fields);
+			pushRepeated(args, "--iteration", params.iterations);
+			if (params.ownEstimatedTime !== undefined)
+				args.push("--own-estimated-time", String(params.ownEstimatedTime));
+			if (params.confidential === true) args.push("--confidential");
+			return args;
+		case "edit":
+			args.push("edit", ref());
+			if (params.title !== undefined) args.push("--title", params.title);
+			if (params.description !== undefined)
+				args.push("--description", params.description);
+			pushRepeated(args, "--field", params.fields);
+			pushRepeated(args, "--iteration", params.iterations);
+			if (params.ownEstimatedTime !== undefined)
+				args.push("--own-estimated-time", String(params.ownEstimatedTime));
+			if (params.confidential !== undefined)
+				args.push("--confidential", String(params.confidential));
+			return args;
+		case "change_state":
+			args.push(
+				"change-state",
+				ref(),
+				requireParam(params.state, action, "state"),
+			);
+			if (params.comment !== undefined) args.push("--comment", params.comment);
+			pushRepeated(args, "--field", params.fields);
+			return args;
+		case "add_comment":
+			return [
+				...args,
+				"add-comment",
+				ref(),
+				requireParam(params.content, action, "content"),
+			];
+		case "link":
+			return [
+				...args,
+				"link",
+				ref(),
+				requireParam(params.linkName, action, "link_name"),
+				requireParam(params.targetRef, action, "target_ref"),
+			];
+		case "log_work":
+			args.push(
+				"log-work",
+				ref(),
+				String(requireParam(params.hours, action, "hours")),
+			);
+			if (params.comment !== undefined) args.push("--comment", params.comment);
+			return args;
+		case "create_branch":
+			return [...args, "create-branch", ref()];
+		case "checkout":
+			args.push("checkout", ref());
+			if (params.forWrite === true) args.push("--for-write");
+			return args;
+		case "current_reference":
+			return [...args, "current-reference"];
+		case "valid_fields":
+			return [...args, "get-valid-fields"];
+		case "valid_links":
+			return [...args, "get-valid-links"];
+		case "query_description":
+			return [...args, "get-query-description"];
+	}
+}
+
+export function registerIssueTool(pi: ExtensionAPI, deps: ToolDeps): void {
+	const parameters = Type.Object({
+		action: StringEnum(ISSUE_ACTIONS, {
+			description:
+				"list (query issues), get, get_comments, create, edit, change_state, add_comment, link, log_work, create_branch, checkout (branch locally), current_reference (issue for current branch), valid_fields, valid_links, query_description",
+		}),
+		ref: Type.Optional(Type.String({ description: REF_DESCRIPTION })),
+		title: Type.Optional(Type.String()),
+		description: Type.Optional(Type.String({ description: "Markdown body" })),
+		state: Type.Optional(
+			Type.String({
+				description:
+					"Target state, e.g. Open or Released; discover via valid_fields",
+			}),
+		),
+		comment: Type.Optional(
+			Type.String({ description: "Markdown note attached to the action" }),
+		),
+		content: Type.Optional(Type.String({ description: "Markdown comment text" })),
+		linkName: Type.Optional(
+			Type.String({ description: "Issue link name; discover via valid_links" }),
+		),
+		targetRef: Type.Optional(
+			Type.String({ description: "Target issue reference for the link action" }),
+		),
+		hours: Type.Optional(
+			Type.Integer({ minimum: 1, description: "Hours to log for log_work" }),
+		),
+		fields: Type.Optional(
+			Type.Array(Type.String(), { description: FIELDS_DESCRIPTION }),
+		),
+		iterations: Type.Optional(Type.Array(Type.String())),
+		ownEstimatedTime: Type.Optional(
+			Type.Integer({ minimum: 0, description: "Estimated hours" }),
+		),
+		confidential: Type.Optional(Type.Boolean()),
+		forWrite: Type.Optional(
+			Type.Boolean({ description: "checkout: set up the branch for pushing" }),
+		),
+		project: Type.Optional(
+			Type.String({
+				description:
+					"Project path for list/create; defaults to the current project",
+			}),
+		),
+		query: Type.Optional(Type.String({ description: QUERY_DESCRIPTION })),
+		count: Type.Optional(
+			Type.Integer({
+				minimum: 1,
+				maximum: 100,
+				description: "Page size for list (default 25, max 100)",
+			}),
+		),
+		offset: Type.Optional(Type.Integer({ minimum: 0 })),
+	});
+	type Params = Static<typeof parameters>;
+
+	pi.registerTool({
+		name: "onedev_issue",
+		label: "OneDev Issues",
+		description:
+			"Read and edit OneDev issues: query, inspect, comment, change fields/labels/state, log work, manage issue branches. Runs in the current repository's project; plain numbers resolve against it.",
+		promptGuidelines: [
+			"Use onedev_issue valid_fields before setting fields or state you have not seen this session.",
+			"Post comments and field changes only after presenting the intent to the user.",
+		],
+		parameters,
+		async execute(_toolCallId, params: Params, signal) {
+			const output = await runInContext(deps, buildIssueArgs(params), { signal });
+			return toolResult(
+				withFooter(output.text, deps.context(), output.truncated),
+				{
+					action: params.action,
+					truncated: output.truncated,
+				},
+			);
+		},
+	});
+}