@nghyane/arcane 0.1.0

package/src/extensibility/custom-commands/bundled/review/index.ts

@@ -0,0 +1,433 @@
+/**
+ * /review command - Interactive code review launcher
+ *
+ * Provides a menu to select review mode:
+ * 1. Review against a base branch (PR style)
+ * 2. Review uncommitted changes
+ * 3. Review a specific commit
+ * 4. Custom review instructions
+ *
+ * Runs git diff upfront, parses results, filters noise, and provides
+ * rich context for the orchestrating agent to distribute work across
+ * multiple reviewer agents based on diff weight and locality.
+ */
+import { renderPromptTemplate } from "../../../../config/prompt-templates";
+import type { CustomCommand, CustomCommandAPI } from "../../../../extensibility/custom-commands/types";
+import type { HookCommandContext } from "../../../../extensibility/hooks/types";
+import reviewRequestTemplate from "../../../../prompts/review-request.md" with { type: "text" };
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Types
+// ─────────────────────────────────────────────────────────────────────────────
+
+interface FileDiff {
+	path: string;
+	linesAdded: number;
+	linesRemoved: number;
+	hunks: string;
+}
+
+interface DiffStats {
+	files: FileDiff[];
+	totalAdded: number;
+	totalRemoved: number;
+	excluded: { path: string; reason: string; linesAdded: number; linesRemoved: number }[];
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Exclusion patterns for noise files
+// ─────────────────────────────────────────────────────────────────────────────
+
+const EXCLUDED_PATTERNS: { pattern: RegExp; reason: string }[] = [
+	// Lock files
+	{ pattern: /\.lock$/, reason: "lock file" },
+	{ pattern: /-lock\.(json|yaml|yml)$/, reason: "lock file" },
+	{ pattern: /package-lock\.json$/, reason: "lock file" },
+	{ pattern: /yarn\.lock$/, reason: "lock file" },
+	{ pattern: /pnpm-lock\.yaml$/, reason: "lock file" },
+	{ pattern: /Cargo\.lock$/, reason: "lock file" },
+	{ pattern: /Gemfile\.lock$/, reason: "lock file" },
+	{ pattern: /poetry\.lock$/, reason: "lock file" },
+	{ pattern: /composer\.lock$/, reason: "lock file" },
+	{ pattern: /flake\.lock$/, reason: "lock file" },
+
+	// Generated/build artifacts
+	{ pattern: /\.min\.(js|css)$/, reason: "minified" },
+	{ pattern: /\.generated\./, reason: "generated" },
+	{ pattern: /\.snap$/, reason: "snapshot" },
+	{ pattern: /\.map$/, reason: "source map" },
+	{ pattern: /^dist\//, reason: "build output" },
+	{ pattern: /^build\//, reason: "build output" },
+	{ pattern: /^out\//, reason: "build output" },
+	{ pattern: /node_modules\//, reason: "vendor" },
+	{ pattern: /vendor\//, reason: "vendor" },
+
+	// Binary/assets (usually shown as binary in diff anyway)
+	{ pattern: /\.(png|jpg|jpeg|gif|ico|webp|avif)$/i, reason: "image" },
+	{ pattern: /\.(woff|woff2|ttf|eot|otf)$/i, reason: "font" },
+	{ pattern: /\.(pdf|zip|tar|gz|rar|7z)$/i, reason: "binary" },
+];
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Diff parsing
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Check if a file path should be excluded from review.
+ * Returns the exclusion reason if excluded, undefined otherwise.
+ */
+function getExclusionReason(path: string): string | undefined {
+	for (const { pattern, reason } of EXCLUDED_PATTERNS) {
+		if (pattern.test(path)) return reason;
+	}
+	return undefined;
+}
+
+/**
+ * Parse unified diff output into per-file stats.
+ * Splits on file boundaries, counts +/- lines, and filters excluded files.
+ */
+function parseDiff(diffOutput: string): DiffStats {
+	const files: FileDiff[] = [];
+	const excluded: DiffStats["excluded"] = [];
+	let totalAdded = 0;
+	let totalRemoved = 0;
+
+	// Split by file boundary: "diff --git a/... b/..."
+	const fileChunks = diffOutput.split(/^diff --git /m).filter(Boolean);
+
+	for (const chunk of fileChunks) {
+		// Extract file path from "a/path b/path" line
+		const headerMatch = chunk.match(/^a\/(.+?) b\/(.+)/);
+		if (!headerMatch) continue;
+
+		const path = headerMatch[2];
+
+		// Count added/removed lines (lines starting with + or - but not ++ or --)
+		let linesAdded = 0;
+		let linesRemoved = 0;
+
+		const lines = chunk.split("\n");
+		for (const line of lines) {
+			if (line.startsWith("+") && !line.startsWith("+++")) {
+				linesAdded++;
+			} else if (line.startsWith("-") && !line.startsWith("---")) {
+				linesRemoved++;
+			}
+		}
+
+		const exclusionReason = getExclusionReason(path);
+		if (exclusionReason) {
+			excluded.push({ path, reason: exclusionReason, linesAdded, linesRemoved });
+		} else {
+			files.push({
+				path,
+				linesAdded,
+				linesRemoved,
+				hunks: `diff --git ${chunk}`,
+			});
+			totalAdded += linesAdded;
+			totalRemoved += linesRemoved;
+		}
+	}
+
+	return { files, totalAdded, totalRemoved, excluded };
+}
+
+/**
+ * Get file extension for display purposes.
+ */
+function getFileExt(path: string): string {
+	const match = path.match(/\.([^.]+)$/);
+	return match ? match[1] : "";
+}
+
+/**
+ * Determine recommended number of reviewer agents based on diff weight.
+ * Uses total lines changed as the primary metric.
+ */
+function getRecommendedAgentCount(stats: DiffStats): number {
+	const totalLines = stats.totalAdded + stats.totalRemoved;
+	const fileCount = stats.files.length;
+
+	// Heuristics:
+	// - Tiny (<100 lines or 1-2 files): 1 agent
+	// - Small (<500 lines): 1-2 agents
+	// - Medium (<2000 lines): 2-4 agents
+	// - Large (<5000 lines): 4-8 agents
+	// - Huge (>5000 lines): 8-16 agents
+
+	if (totalLines < 100 || fileCount <= 2) return 1;
+	if (totalLines < 500) return Math.min(2, fileCount);
+	if (totalLines < 2000) return Math.min(4, Math.ceil(fileCount / 3));
+	if (totalLines < 5000) return Math.min(8, Math.ceil(fileCount / 2));
+	return Math.min(16, fileCount);
+}
+
+/**
+ * Extract first N lines of actual diff content (excluding headers) for preview.
+ */
+function getDiffPreview(hunks: string, maxLines: number): string {
+	const lines = hunks.split("\n");
+	const contentLines: string[] = [];
+
+	for (const line of lines) {
+		// Skip diff headers, keep actual content
+		if (
+			line.startsWith("diff --git") ||
+			line.startsWith("index ") ||
+			line.startsWith("---") ||
+			line.startsWith("+++") ||
+			line.startsWith("@@")
+		) {
+			continue;
+		}
+		contentLines.push(line);
+		if (contentLines.length >= maxLines) break;
+	}
+
+	return contentLines.join("\n");
+}
+
+// Thresholds for diff inclusion
+const MAX_DIFF_CHARS = 50_000; // Don't include diff above this
+const MAX_FILES_FOR_INLINE_DIFF = 20; // Don't include diff if more files than this
+
+/**
+ * Build the full review prompt with diff stats and distribution guidance.
+ */
+function buildReviewPrompt(mode: string, stats: DiffStats, rawDiff: string): string {
+	const agentCount = getRecommendedAgentCount(stats);
+	const skipDiff = rawDiff.length > MAX_DIFF_CHARS || stats.files.length > MAX_FILES_FOR_INLINE_DIFF;
+	const totalLines = stats.totalAdded + stats.totalRemoved;
+	const linesPerFile = skipDiff ? Math.max(5, Math.floor(100 / stats.files.length)) : 0;
+
+	const filesWithExt = stats.files.map(f => ({
+		...f,
+		ext: getFileExt(f.path),
+		hunksPreview: skipDiff ? getDiffPreview(f.hunks, linesPerFile) : "",
+	}));
+
+	return renderPromptTemplate(reviewRequestTemplate, {
+		mode,
+		files: filesWithExt,
+		excluded: stats.excluded,
+		totalAdded: stats.totalAdded,
+		totalRemoved: stats.totalRemoved,
+		totalLines,
+		agentCount,
+		multiAgent: agentCount > 1,
+		skipDiff,
+		rawDiff: rawDiff.trim(),
+		linesPerFile,
+	});
+}
+
+export class ReviewCommand implements CustomCommand {
+	name = "review";
+	description = "Launch interactive code review";
+
+	constructor(private api: CustomCommandAPI) {}
+
+	async execute(_args: string[], ctx: HookCommandContext): Promise<string | undefined> {
+		if (!ctx.hasUI) {
+			return "Use the Review tool to review recent code changes.";
+		}
+
+		const mode = await ctx.ui.select("Review Mode", [
+			"1. Review against a base branch (PR Style)",
+			"2. Review uncommitted changes",
+			"3. Review a specific commit",
+			"4. Custom review instructions",
+		]);
+
+		if (!mode) return undefined;
+
+		const modeNum = parseInt(mode[0], 10);
+
+		switch (modeNum) {
+			case 1: {
+				// PR-style review against base branch
+				const branches = await getGitBranches(this.api);
+				if (branches.length === 0) {
+					ctx.ui.notify("No git branches found", "error");
+					return undefined;
+				}
+
+				const baseBranch = await ctx.ui.select("Select base branch to compare against", branches);
+				if (!baseBranch) return undefined;
+
+				const currentBranch = await getCurrentBranch(this.api);
+				const diffResult = await this.api.exec("git", ["diff", `${baseBranch}...${currentBranch}`], {
+					timeout: 30000,
+				});
+				if (diffResult.code !== 0) {
+					ctx.ui.notify(`Failed to get diff: ${diffResult.stderr}`, "error");
+					return undefined;
+				}
+
+				if (!diffResult.stdout.trim()) {
+					ctx.ui.notify(`No changes between ${baseBranch} and ${currentBranch}`, "warning");
+					return undefined;
+				}
+
+				const stats = parseDiff(diffResult.stdout);
+				if (stats.files.length === 0) {
+					ctx.ui.notify("No reviewable files (all changes filtered out)", "warning");
+					return undefined;
+				}
+
+				return buildReviewPrompt(
+					`Reviewing changes between \`${baseBranch}\` and \`${currentBranch}\` (PR-style)`,
+					stats,
+					diffResult.stdout,
+				);
+			}
+
+			case 2: {
+				// Uncommitted changes - combine staged and unstaged
+				const status = await getGitStatus(this.api);
+				if (!status.trim()) {
+					ctx.ui.notify("No uncommitted changes found", "warning");
+					return undefined;
+				}
+
+				const [unstagedResult, stagedResult] = await Promise.all([
+					this.api.exec("git", ["diff"], { timeout: 30000 }),
+					this.api.exec("git", ["diff", "--cached"], { timeout: 30000 }),
+				]);
+
+				const combinedDiff = [unstagedResult.stdout, stagedResult.stdout].filter(Boolean).join("\n");
+
+				if (!combinedDiff.trim()) {
+					ctx.ui.notify("No diff content found", "warning");
+					return undefined;
+				}
+
+				const stats = parseDiff(combinedDiff);
+				if (stats.files.length === 0) {
+					ctx.ui.notify("No reviewable files (all changes filtered out)", "warning");
+					return undefined;
+				}
+
+				return buildReviewPrompt("Reviewing uncommitted changes (staged + unstaged)", stats, combinedDiff);
+			}
+
+			case 3: {
+				// Specific commit
+				const commits = await getRecentCommits(this.api, 20);
+				if (commits.length === 0) {
+					ctx.ui.notify("No commits found", "error");
+					return undefined;
+				}
+
+				const selected = await ctx.ui.select("Select commit to review", commits);
+				if (!selected) return undefined;
+
+				// Extract commit hash from selection (format: "abc1234 message")
+				const hash = selected.split(" ")[0];
+
+				// Get the commit diff (with timeout)
+				const showResult = await this.api.exec("git", ["show", "--format=", hash], { timeout: 30000 });
+				if (showResult.code !== 0) {
+					ctx.ui.notify(`Failed to get commit: ${showResult.stderr}`, "error");
+					return undefined;
+				}
+
+				if (!showResult.stdout.trim()) {
+					ctx.ui.notify("Commit has no diff content", "warning");
+					return undefined;
+				}
+
+				const stats = parseDiff(showResult.stdout);
+				if (stats.files.length === 0) {
+					ctx.ui.notify("No reviewable files in commit (all changes filtered out)", "warning");
+					return undefined;
+				}
+
+				return buildReviewPrompt(`Reviewing commit \`${hash}\``, stats, showResult.stdout);
+			}
+
+			case 4: {
+				// Custom instructions - still uses the old approach since user provides context
+				const instructions = await ctx.ui.editor("Enter custom review instructions", "Review the following:\n\n");
+				if (!instructions?.trim()) return undefined;
+
+				// For custom, we still try to get current diff for context
+				const diffResult = await this.api.exec("git", ["diff", "HEAD"], { timeout: 30000 });
+				const hasDiff = diffResult.code === 0 && diffResult.stdout.trim();
+
+				if (hasDiff) {
+					const stats = parseDiff(diffResult.stdout);
+					// Even if all files filtered, include the custom instructions
+					return `${buildReviewPrompt(
+						`Custom review: ${instructions.split("\n")[0].slice(0, 60)}…`,
+						stats,
+						diffResult.stdout,
+					)}\n\n### Additional Instructions\n\n${instructions}`;
+				}
+
+				// No diff available, just pass instructions
+				return `## Code Review Request
+
+### Mode
+Custom review instructions
+
+### Instructions
+
+${instructions}
+
+Use the Review tool to execute this review.`;
+			}
+
+			default:
+				return undefined;
+		}
+	}
+}
+
+async function getGitBranches(api: CustomCommandAPI): Promise<string[]> {
+	try {
+		const result = await api.exec("git", ["branch", "-a", "--format=%(refname:short)"]);
+		if (result.code !== 0) return [];
+		return result.stdout
+			.split("\n")
+			.map(b => b.trim())
+			.filter(Boolean);
+	} catch {
+		return [];
+	}
+}
+
+async function getCurrentBranch(api: CustomCommandAPI): Promise<string> {
+	try {
+		const result = await api.exec("git", ["branch", "--show-current"]);
+		return result.stdout.trim() || "HEAD";
+	} catch {
+		return "HEAD";
+	}
+}
+
+async function getGitStatus(api: CustomCommandAPI): Promise<string> {
+	try {
+		const result = await api.exec("git", ["status", "--porcelain"]);
+		return result.stdout;
+	} catch {
+		return "";
+	}
+}
+
+async function getRecentCommits(api: CustomCommandAPI, count: number): Promise<string[]> {
+	try {
+		const result = await api.exec("git", ["log", `-${count}`, "--oneline", "--no-decorate"]);
+		if (result.code !== 0) return [];
+		return result.stdout
+			.split("\n")
+			.map(c => c.trim())
+			.filter(Boolean);
+	} catch {
+		return [];
+	}
+}
+
+export default ReviewCommand;

package/src/extensibility/custom-commands/index.ts

@@ -0,0 +1,15 @@
+export {
+	type DiscoverCustomCommandsOptions,
+	type DiscoverCustomCommandsResult,
+	discoverCustomCommands,
+	type LoadCustomCommandsOptions,
+	loadCustomCommands,
+} from "./loader";
+export type {
+	CustomCommand,
+	CustomCommandAPI,
+	CustomCommandFactory,
+	CustomCommandSource,
+	CustomCommandsLoadResult,
+	LoadedCustomCommand,
+} from "./types";

package/src/extensibility/custom-commands/loader.ts

@@ -0,0 +1,231 @@
+/**
+ * Custom command loader - loads TypeScript command modules using native Bun import.
+ *
+ * Dependencies (@sinclair/typebox and pi-coding-agent) are injected via the CustomCommandAPI
+ * to avoid import resolution issues with custom commands loaded from user directories.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import * as piCodingAgent from "@nghyane/arcane";
+import { isEnoent, logger } from "@nghyane/arcane-utils";
+import { getAgentDir, getProjectDir } from "@nghyane/arcane-utils/dirs";
+import * as typebox from "@sinclair/typebox";
+import { getConfigDirs } from "../../config";
+import { execCommand } from "../../exec/exec";
+import { ReviewCommand } from "./bundled/review";
+import type {
+	CustomCommand,
+	CustomCommandAPI,
+	CustomCommandFactory,
+	CustomCommandSource,
+	CustomCommandsLoadResult,
+	LoadedCustomCommand,
+} from "./types";
+
+/**
+ * Load a single command module using native Bun import.
+ */
+async function loadCommandModule(
+	commandPath: string,
+	_cwd: string,
+	sharedApi: CustomCommandAPI,
+): Promise<{ commands: CustomCommand[] | null; error: string | null }> {
+	try {
+		const module = await import(commandPath);
+		const factory = (module.default ?? module) as CustomCommandFactory;
+
+		if (typeof factory !== "function") {
+			return { commands: null, error: "Command must export a default function" };
+		}
+
+		const result = await factory(sharedApi);
+		const commands = Array.isArray(result) ? result : [result];
+
+		// Validate commands
+		for (const cmd of commands) {
+			if (!cmd.name || typeof cmd.name !== "string") {
+				return { commands: null, error: "Command must have a name" };
+			}
+			if (!cmd.description || typeof cmd.description !== "string") {
+				return { commands: null, error: `Command "${cmd.name}" must have a description` };
+			}
+			if (typeof cmd.execute !== "function") {
+				return { commands: null, error: `Command "${cmd.name}" must have an execute function` };
+			}
+		}
+
+		return { commands, error: null };
+	} catch (err) {
+		const message = err instanceof Error ? err.message : String(err);
+		return { commands: null, error: `Failed to load command: ${message}` };
+	}
+}
+
+export interface DiscoverCustomCommandsOptions {
+	/** Current working directory. Default: getProjectDir() */
+	cwd?: string;
+	/** Agent config directory. Default: from getAgentDir() */
+	agentDir?: string;
+}
+
+export interface DiscoverCustomCommandsResult {
+	/** Paths to command modules */
+	paths: Array<{ path: string; source: CustomCommandSource }>;
+}
+
+/**
+ * Discover custom command modules (TypeScript slash commands).
+ * Markdown slash commands are handled by core/slash-commands.ts.
+ */
+export async function discoverCustomCommands(
+	options: DiscoverCustomCommandsOptions = {},
+): Promise<DiscoverCustomCommandsResult> {
+	const cwd = options.cwd ?? getProjectDir();
+	const agentDir = options.agentDir ?? getAgentDir();
+	const paths: Array<{ path: string; source: CustomCommandSource }> = [];
+	const seen = new Set<string>();
+
+	const addPath = (commandPath: string, source: CustomCommandSource): void => {
+		const resolved = path.resolve(commandPath);
+		if (seen.has(resolved)) return;
+		seen.add(resolved);
+		paths.push({ path: resolved, source });
+	};
+
+	const commandDirs: Array<{ path: string; source: CustomCommandSource }> = [];
+	if (agentDir) {
+		const userCommandsDir = path.join(agentDir, "commands");
+		if (fs.existsSync(userCommandsDir)) {
+			commandDirs.push({ path: userCommandsDir, source: "user" });
+		}
+	}
+
+	for (const entry of getConfigDirs("commands", { cwd, existingOnly: true })) {
+		const source = entry.level === "user" ? "user" : "project";
+		if (!commandDirs.some(d => d.path === entry.path)) {
+			commandDirs.push({ path: entry.path, source });
+		}
+	}
+
+	const indexCandidates = ["index.ts", "index.js", "index.mjs", "index.cjs"];
+	for (const { path: commandsDir, source } of commandDirs) {
+		let entries: fs.Dirent[];
+		try {
+			entries = await fs.promises.readdir(commandsDir, { withFileTypes: true });
+		} catch (error) {
+			if (!isEnoent(error)) {
+				logger.warn("Failed to read custom commands directory", { path: commandsDir, error: String(error) });
+			}
+			continue;
+		}
+		for (const entry of entries) {
+			if (!entry.isDirectory() || entry.name.startsWith(".")) continue;
+			const commandDir = path.join(commandsDir, entry.name);
+
+			for (const filename of indexCandidates) {
+				const candidate = path.join(commandDir, filename);
+				if (fs.existsSync(candidate)) {
+					addPath(candidate, source);
+					break;
+				}
+			}
+		}
+	}
+
+	return { paths };
+}
+
+export interface LoadCustomCommandsOptions {
+	/** Current working directory. Default: getProjectDir() */
+	cwd?: string;
+	/** Agent config directory. Default: from getAgentDir() */
+	agentDir?: string;
+}
+
+/**
+ * Load bundled commands (shipped with pi-coding-agent).
+ */
+function loadBundledCommands(sharedApi: CustomCommandAPI): LoadedCustomCommand[] {
+	const bundled: LoadedCustomCommand[] = [];
+
+	// Add bundled commands here
+	bundled.push({
+		path: "bundled:review",
+		resolvedPath: "bundled:review",
+		command: new ReviewCommand(sharedApi),
+		source: "bundled",
+	});
+
+	return bundled;
+}
+
+/**
+ * Discover and load custom commands from standard locations.
+ */
+export async function loadCustomCommands(options: LoadCustomCommandsOptions = {}): Promise<CustomCommandsLoadResult> {
+	const cwd = options.cwd ?? getProjectDir();
+	const agentDir = options.agentDir ?? getAgentDir();
+
+	const { paths } = await discoverCustomCommands({ cwd, agentDir });
+
+	const commands: LoadedCustomCommand[] = [];
+	const errors: Array<{ path: string; error: string }> = [];
+	const seenNames = new Set<string>();
+
+	// Shared API object - all commands get the same instance
+	const sharedApi: CustomCommandAPI = {
+		cwd,
+		exec: (command: string, args: string[], execOptions) =>
+			execCommand(command, args, execOptions?.cwd ?? cwd, execOptions),
+		typebox,
+		pi: piCodingAgent,
+	};
+
+	// 1. Load bundled commands first (lowest priority - can be overridden)
+	for (const loaded of loadBundledCommands(sharedApi)) {
+		seenNames.add(loaded.command.name);
+		commands.push(loaded);
+	}
+
+	// 2. Load user/project commands (can override bundled)
+	for (const { path: commandPath, source } of paths) {
+		const { commands: loadedCommands, error } = await loadCommandModule(commandPath, cwd, sharedApi);
+
+		if (error) {
+			errors.push({ path: commandPath, error });
+			continue;
+		}
+
+		if (loadedCommands) {
+			for (const command of loadedCommands) {
+				// Allow overriding bundled commands, but not user/project conflicts
+				const existingIdx = commands.findIndex(c => c.command.name === command.name);
+				if (existingIdx !== -1) {
+					const existing = commands[existingIdx];
+					if (existing.source === "bundled") {
+						// Override bundled command
+						commands.splice(existingIdx, 1);
+						seenNames.delete(command.name);
+					} else {
+						// Conflict between user/project commands
+						errors.push({
+							path: commandPath,
+							error: `Command name "${command.name}" conflicts with existing command`,
+						});
+						continue;
+					}
+				}
+
+				seenNames.add(command.name);
+				commands.push({
+					path: commandPath,
+					resolvedPath: path.resolve(commandPath),
+					command,
+					source,
+				});
+			}
+		}
+	}
+
+	return { commands, errors };
+}