pi-onedev-toolkit 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,9 @@
+# Changelog
+
+## 0.1.0
+
+- Initial release.
+- `onedev_tools` domain activator with context, login, and attachment-download actions.
+- `onedev_issue`, `onedev_pull`, `onedev_build` tools wrapping the TOD CLI.
+- `/od-context` and `/od-health` commands; session status line with the inferred project.
+- `onedev-issue-to-pr` and `onedev-pr-review` skills.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alper Tarhan
+
+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/README.md

@@ -0,0 +1,57 @@
+# pi-onedev-toolkit
+
+Lightweight [OneDev](https://onedev.io/) integration for [Pi](https://pi.dev/), built on the official [TOD CLI](https://code.onedev.io/onedev/tod): repo-aware issue, pull request, and build tools plus issue-to-PR and PR-review skills.
+
+The agent never shells out to `tod` itself and never sees tokens. The extension resolves the OneDev project from the repository's git remotes once per session, and the tools speak OneDev terms (`123`, `PROJ-123`, `project#123` all resolve server-side).
+
+## Requirements
+
+- OneDev 15.1+
+- The `tod` CLI installed and configured:
+
+```bash
+curl -fsSL https://code.onedev.io/onedev/tod/~raw/main/install.sh | bash
+tod config set   # server-url + access-token (or set ONEDEV_SERVER_URL / ONEDEV_ACCESS_TOKEN)
+```
+
+## Install
+
+```bash
+pi install npm:pi-onedev-toolkit
+# or from source
+pi install git:github.com/alpertarhan/pi-onedev-toolkit
+```
+
+Then run `/od-health` once. When the current directory is a OneDev repository, the status line shows the active project.
+
+## Tools
+
+| Tool | Domains | Covers |
+| --- | --- | --- |
+| `onedev_tools` (always active) | — | Activate domains; session context; login name; download issue/PR attachments |
+| `onedev_issue` | issue | Query/get/comment issues, change fields/labels/state, log work, issue branches |
+| `onedev_pull` | pull | PR metadata/comments/code comments/labels/builds/patch, create/edit, approve, request changes, guarded merge/discard |
+| `onedev_build` | build | Build queries, logs, code-problem reports, changes since last success, run jobs (incl. uncommitted local changes), build-spec validation |
+
+Lazy by design: domain tools activate only through `onedev_tools`, keeping the default tool list light. `merge` and `discard` additionally require `confirm: true`.
+
+## Commands
+
+- `/od-context` — active server, inferred project, login
+- `/od-health` — re-check tod configuration and server reachability
+
+## Skills
+
+- `onedev-issue-to-pr` — gather issue context, branch, implement, present for review, then push and open the PR
+- `onedev-pr-review` — full-context PR review with line-anchored findings; submits only on explicit request
+
+## Development
+
+```bash
+bun install
+bun run check   # typecheck + vitest
+```
+
+## License
+
+MIT

package/extensions/onedev/index.ts

@@ -0,0 +1 @@
+export { default } from "../../src/extension.js";

package/package.json

@@ -0,0 +1,67 @@
+{
+	"name": "pi-onedev-toolkit",
+	"version": "0.1.0",
+	"description": "Lightweight OneDev integration for Pi via the TOD CLI: repo-aware issue, pull request, and build tools",
+	"type": "module",
+	"author": {
+		"name": "Alper Tarhan",
+		"url": "https://github.com/alpertarhan"
+	},
+	"homepage": "https://github.com/alpertarhan/pi-onedev-toolkit#readme",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/alpertarhan/pi-onedev-toolkit.git"
+	},
+	"bugs": {
+		"url": "https://github.com/alpertarhan/pi-onedev-toolkit/issues"
+	},
+	"keywords": [
+		"pi-package",
+		"pi",
+		"pi-extension",
+		"onedev",
+		"tod",
+		"coding-agent",
+		"developer-tools"
+	],
+	"license": "MIT",
+	"files": [
+		"extensions",
+		"skills",
+		"src",
+		"README.md",
+		"CHANGELOG.md",
+		"LICENSE"
+	],
+	"scripts": {
+		"check": "bun run typecheck && bun run test",
+		"typecheck": "tsc --noEmit",
+		"test": "vitest run",
+		"prepack": "bun run check"
+	},
+	"pi": {
+		"extensions": [
+			"./extensions"
+		],
+		"skills": [
+			"./skills"
+		]
+	},
+	"peerDependencies": {
+		"@earendil-works/pi-ai": "*",
+		"@earendil-works/pi-coding-agent": "*",
+		"typebox": "*"
+	},
+	"devDependencies": {
+		"@earendil-works/pi-ai": "0.84.1",
+		"@earendil-works/pi-coding-agent": "0.84.1",
+		"@types/node": "^20.17.0",
+		"typebox": "1.3.12",
+		"typescript": "^7.0.2",
+		"vitest": "^4.1.10"
+	},
+	"engines": {
+		"node": ">=20.3"
+	},
+	"packageManager": "bun@1.3.14"
+}

package/skills/onedev-issue-to-pr/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: onedev-issue-to-pr
+description: Implement a OneDev issue end to end - gather issue context, branch, implement, then (after user approval) push and open a linked pull request. Use when the user asks to work on, implement, or fix a OneDev issue.
+---
+
+# OneDev issue to pull request
+
+## Prerequisites
+
+- Call `onedev_tools` with domains `["issue", "pull"]` first; note your login name from the returned context.
+- The current repository belongs to the issue's project (plain refs like `123` resolve against it).
+
+## Workflow
+
+1. **Resolve the issue reference.** Use the reference from the prompt, or derive it
+   with `onedev_issue` action `current_reference`. If neither works, stop and report.
+
+2. **Prepare the checkout** (unless the user says otherwise):
+   `onedev_issue` action `checkout` with `ref` and `for_write: true`.
+   It creates the server-side issue branch and sets up tracking.
+   If the working copy is dirty, report it and stop — do not stash on your own.
+
+3. **Read the full issue context** — never work from the prompt alone:
+   - `onedev_issue` `get` (title, description, fields, submitter)
+   - `onedev_issue` `get_comments`
+   - Match your login name against submitter/comment authors to understand your role.
+   - Download embedded resources (screenshots, logs) with `onedev_tools` action
+     `download`, passing the URL exactly as it appears in the markdown.
+   - If a failed build is part of the issue, gather evidence with `onedev_build`
+     (`get`, `get_log`) before planning changes. Follow `Dependency build … failed`
+     chains: same-commit dependency failures are the real target; different-commit
+     ones mean the failure is inherited.
+
+4. **Implement the work.** Code changes, or an explanatory issue comment if no code
+   is needed. Run the smallest relevant test. Optionally validate CI locally with
+   `onedev_build` `run` (`mode: "local"`) before committing.
+
+5. **STOP — present for review.** Summarize the change and the comment you intend
+   to post. Do not push or post anything yet. This is the mandatory checkpoint.
+
+6. **After explicit user approval, submit:**
+   - Compose the commit message against the server requirements:
+     `onedev_pull` `commit_message_requirement` (and `title_description_requirement`
+     before creating the PR). Empty output means no requirement.
+   - `git add -A && git commit && git push` on the issue branch.
+   - Create the PR: `onedev_pull` `create` with `title`, `description`, and
+     `target_branch` (source branch defaults to the current branch). The issue link
+     is inferred from the branch; state it in the description if not.
+   - Post the drafted comment with `onedev_issue` `add_comment` if one was prepared.
+
+## Notes
+
+- Write comment text in Markdown.
+- Reference entities as `#123` (current project), `project#123`, or `PROJ-123`.
+- If blocked mid-workflow, report the command and error, and stop.

package/skills/onedev-pr-review/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: onedev-pr-review
+description: Review a OneDev pull request - gather PR context, builds, and fixed issues, read the review-scoped patch, draft findings with line-anchored code comments, and submit the review or merge only on explicit request. Use when the user asks to review, address feedback on, or merge a OneDev pull request.
+---
+
+# OneDev pull request review
+
+## Prerequisites
+
+- Call `onedev_tools` with domains `["pull", "issue", "build"]`; note your login name.
+- The current repository belongs to the PR's source or target project.
+
+## Gather context (never review from the patch alone)
+
+1. **Resolve the PR reference** from the prompt or `onedev_pull` `current_reference`.
+
+2. **Checkout** for inspection: `onedev_pull` `checkout` (`for_write: true` when you
+   will change code). Dirty working copy → report and stop.
+
+3. **Read everything:**
+   - `onedev_pull` `get` — title, description, source/target, merge strategy, status,
+     submitter, reviewers, review state.
+   - `onedev_pull` `get_comments` and `get_code_comments` — note code-comment `id`s,
+     file, line range, resolution state, replies.
+   - Fixed issues: `onedev_issue` `list` with query `fixed in pull request "<ref>"`,
+     then `get` / `get_comments` on each. Treat fixed issues as the primary spec
+     for what the PR should accomplish.
+   - `onedev_pull` `get_builds` — investigate every `FAILED` build with
+     `onedev_build` `get` / `get_log` before reviewing code.
+   - Download embedded resources via `onedev_tools` `download`.
+   - Match your login name against authors to understand your role
+     (pending reviewer, prior commenter, outsider).
+
+## Review
+
+1. Read the review-scoped patch: `onedev_pull` `get_patch` with
+   `for_code_review: true`. Read files in the checkout when the patch lacks context.
+   Check correctness, edge cases, security, style, and test coverage.
+
+2. **Triage prior discussion:** resolve addressed code comments, reply where new
+   information is needed, leave unrelated unresolved ones alone. Never modify
+   another user's code comments.
+
+3. **Draft findings:**
+   - Line-anchored findings → `onedev_pull` `add_code_comment` (`file`, `from_line`,
+     optional `to_line` — must be an added or context line visible in the patch).
+   - Outside-patch findings → one overall PR comment with file paths and lines.
+   - Review outcome if you are a pending reviewer: `approve` or `request_changes`
+     with a `summary`.
+
+4. **STOP — present the draft** (findings, replies, outcomes, merge plan).
+   Submit nothing yet.
+
+5. **On explicit request only:**
+   - Post findings/comments/review outcome.
+   - Merge: `merge` requires `confirm: true`. For squash merges, compose the commit
+     message from PR title/description + fixed issues, satisfying
+     `commit_message_requirement` for the target project/branch.
+   - Resolving merge conflicts: fetch the target branch, merge with the PR's
+     strategy without committing, resolve, verify clean `git status`, commit.
+     For rebase-based strategies, ask for direction before rewriting commits.
+
+## Notes
+
+- Comment text is Markdown; entity refs are `#123`, `project#123`, or `PROJ-123`.

package/src/context.ts

@@ -0,0 +1,97 @@
+import type { CommandExecutor } from "./tod.js";
+import { runTod } from "./tod.js";
+
+export interface OneDevSessionContext {
+	readonly cwd: string;
+	readonly status: "ready" | "unavailable";
+	readonly serverUrl?: string;
+	/** Project path inferred from the repository's git remotes (e.g. "group/myproject"). */
+	readonly project?: string;
+	readonly loginName?: string;
+	/** Human-readable setup guidance when status is "unavailable". */
+	readonly problem?: string;
+}
+
+export const TOD_INSTALL_HINT =
+	"tod is not installed. Install it (curl -fsSL https://code.onedev.io/onedev/tod/~raw/main/install.sh | bash), then run `tod config set`.";
+
+function unavailable(cwd: string, problem: string): OneDevSessionContext {
+	return { cwd, status: "unavailable", problem };
+}
+
+/**
+ * Probe the local OneDev setup once per session:
+ * 1. `tod config get server-url` — tod present and configured
+ * 2. `tod get-login-name` — server reachable and access token accepted
+ * 3. `tod project current` — repo-aware project context (optional)
+ */
+export async function probeOneDevContext(
+	exec: CommandExecutor,
+	cwd: string,
+	signal?: AbortSignal,
+): Promise<OneDevSessionContext> {
+	let serverUrl: string;
+	try {
+		const configured = await runTod(exec, ["config", "get", "server-url"], {
+			cwd,
+			timeoutMs: 10_000,
+			signal,
+			maxOutputBytes: 2_000,
+		});
+		serverUrl = configured.text.trim();
+	} catch (cause) {
+		const message = cause instanceof Error ? cause.message : String(cause);
+		return unavailable(
+			cwd,
+			message.startsWith("tod is not usable") ? TOD_INSTALL_HINT : message,
+		);
+	}
+	if (!serverUrl) {
+		return unavailable(
+			cwd,
+			"tod is installed but not configured. Run `tod config set` (server-url and access-token), or set ONEDEV_SERVER_URL and ONEDEV_ACCESS_TOKEN.",
+		);
+	}
+
+	let loginName: string | undefined;
+	try {
+		const login = await runTod(exec, ["get-login-name"], {
+			cwd,
+			timeoutMs: 15_000,
+			signal,
+			maxOutputBytes: 2_000,
+		});
+		loginName = login.text.trim() || undefined;
+	} catch (cause) {
+		return unavailable(
+			cwd,
+			`OneDev server or access token rejected (${cause instanceof Error ? cause.message : String(cause)}). Run \`tod config set\` to fix credentials.`,
+		);
+	}
+
+	let project: string | undefined;
+	try {
+		const current = await runTod(exec, ["project", "current"], {
+			cwd,
+			timeoutMs: 15_000,
+			signal,
+			maxOutputBytes: 2_000,
+		});
+		project = current.text.trim() || undefined;
+	} catch {
+		// Not a OneDev repository: fine. Tools accept explicit projects/qualified refs.
+	}
+
+	return { cwd, status: "ready", serverUrl, loginName, project };
+}
+
+export function formatContext(context: OneDevSessionContext): string {
+	if (context.status === "unavailable") {
+		return `OneDev unavailable: ${context.problem ?? "unknown problem"}`;
+	}
+	const parts = [`server ${context.serverUrl}`];
+	if (context.project) parts.push(`project ${context.project}`);
+	else parts.push("no OneDev project inferred from git remotes");
+	if (context.loginName) parts.push(`user ${context.loginName}`);
+	return `OneDev ready: ${parts.join(" · ")}`;
+}

package/src/extension.ts

@@ -0,0 +1,72 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import {
+	formatContext,
+	probeOneDevContext,
+	type OneDevSessionContext,
+} from "./context.js";
+import {
+	registerOnedevTools,
+	type OnedevToolController,
+} from "./tools/index.js";
+import type { ToolDeps } from "./tools/common.js";
+
+export default function onedevExtension(pi: ExtensionAPI): void {
+	let context: OneDevSessionContext | undefined;
+	let controller: OnedevToolController | undefined;
+
+	const deps: ToolDeps = {
+		exec: (command, args, options) => pi.exec(command, args, options),
+		context: () => {
+			if (!context) throw new Error("OneDev extension is still initializing");
+			return context;
+		},
+	};
+
+	const applyStatus = (ctx: {
+		hasUI: boolean;
+		ui: { setStatus: (key: string, value: string | undefined) => void };
+	}): void => {
+		if (!ctx.hasUI) return;
+		if (context?.status === "ready" && context.project) {
+			ctx.ui.setStatus("onedev", `onedev: ${context.project}`);
+		} else {
+			ctx.ui.setStatus("onedev", undefined);
+		}
+	};
+
+	pi.registerCommand("od-context", {
+		description: "Show the active OneDev server, project, and user",
+		handler: async (_args, ctx) => {
+			if (!context) throw new Error("OneDev extension is still initializing");
+			ctx.ui.notify(
+				formatContext(context),
+				context.status === "ready" ? "info" : "warning",
+			);
+		},
+	});
+
+	pi.registerCommand("od-health", {
+		description: "Re-check the tod CLI configuration and OneDev server",
+		handler: async (_args, ctx) => {
+			context = await probeOneDevContext(deps.exec, ctx.cwd);
+			applyStatus(ctx);
+			ctx.ui.notify(
+				formatContext(context),
+				context.status === "ready" ? "info" : "warning",
+			);
+		},
+	});
+
+	controller = registerOnedevTools(pi, deps);
+
+	pi.on("session_start", async (_event, ctx) => {
+		controller?.reset();
+		context = await probeOneDevContext(deps.exec, ctx.cwd);
+		applyStatus(ctx);
+	});
+
+	pi.on("session_shutdown", async (_event, ctx) => {
+		if (ctx.hasUI) ctx.ui.setStatus("onedev", undefined);
+		context = undefined;
+	});
+}

package/src/tod.ts

@@ -0,0 +1,103 @@
+/**
+ * Thin executor around the OneDev `tod` CLI.
+ *
+ * Contract (verified against tod source): every subcommand writes the raw
+ * OneDev server payload to stdout and logs progress to stderr, so stdout is
+ * the tool result and stderr is error/diagnostic context.
+ */
+
+export interface ExecResult {
+	stdout: string;
+	stderr: string;
+	code: number;
+	killed: boolean;
+}
+
+export type CommandExecutor = (
+	command: string,
+	args: string[],
+	options?: { cwd?: string; timeout?: number; signal?: AbortSignal },
+) => Promise<ExecResult>;
+
+export class TodError extends Error {
+	constructor(message: string, options?: { cause?: unknown }) {
+		super(message, options);
+		this.name = "TodError";
+	}
+}
+
+export interface TodRunOptions {
+	cwd?: string;
+	timeoutMs?: number;
+	signal?: AbortSignal;
+	maxOutputBytes?: number;
+}
+
+export interface TodOutput {
+	text: string;
+	truncated: boolean;
+	originalBytes: number;
+}
+
+export const DEFAULT_TIMEOUT_MS = 30_000;
+export const BUILD_RUN_TIMEOUT_MS = 10 * 60_000;
+export const DEFAULT_MAX_OUTPUT_BYTES = 48_000;
+
+function tail(value: string, maxChars = 500): string {
+	const cleaned = value.replace(/\s+/g, " ").trim();
+	return cleaned.length > maxChars ? `…${cleaned.slice(-maxChars)}` : cleaned;
+}
+
+/**
+ * Byte-bounded view keeping the head (metadata) and tail (newest entries,
+ * log ends) of a large payload.
+ */
+export function truncateMiddle(text: string, maxBytes: number): TodOutput {
+	const buffer = Buffer.from(text, "utf8");
+	const originalBytes = buffer.length;
+	if (originalBytes <= maxBytes) {
+		return { text, truncated: false, originalBytes };
+	}
+	const head = Math.floor(maxBytes * 0.6);
+	const tailBytes = maxBytes - head;
+	const omitted = originalBytes - maxBytes;
+	return {
+		text:
+			buffer.subarray(0, head).toString("utf8") +
+			`\n[… truncated ${omitted} bytes …]\n` +
+			buffer.subarray(originalBytes - tailBytes).toString("utf8"),
+		truncated: true,
+		originalBytes,
+	};
+}
+
+export async function runTod(
+	exec: CommandExecutor,
+	args: readonly string[],
+	options: TodRunOptions = {},
+): Promise<TodOutput> {
+	let result: ExecResult;
+	try {
+		result = await exec("tod", [...args], {
+			cwd: options.cwd,
+			timeout: options.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+			signal: options.signal,
+		});
+	} catch (cause) {
+		throw new TodError(
+			`tod is not usable: ${cause instanceof Error ? cause.message : String(cause)}`,
+			{ cause },
+		);
+	}
+	if (result.code !== 0) {
+		const scope = args.slice(0, 2).join(" ");
+		const detail = tail(result.stderr || result.stdout);
+		throw new TodError(
+			`tod ${scope} failed (exit ${result.code})${detail ? `: ${detail}` : ""}`,
+		);
+	}
+	return truncateMiddle(
+		result.stdout.trimEnd(),
+		options.maxOutputBytes ?? DEFAULT_MAX_OUTPUT_BYTES,
+	);
+}