.gitignore

@@ -0,0 +1,5 @@
+# Planning files (local working documents)
+findings.md
+progress.md
+task_plan.md
+issue-*-review.md

.pi/extensions/pi-worktree.ts

@@ -0,0 +1,179 @@
+/**
+ * pi-worktree Extension
+ *
+ * Manages git worktrees through tool commands and an interactive `/worktree` command.
+ *
+ * Tools:
+ * - git_worktree_create — Create a linked worktree for a branch
+ * - git_worktree_list — List all linked worktrees
+ * - git_worktree_switch — Switch working directory to a worktree
+ * - git_worktree_remove — Remove a linked worktree
+ *
+ * Command:
+ * - /worktree — Interactive picker to switch between worktrees
+ */
+
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { defineTool } from "@earendil-works/pi-coding-agent";
+import { Type } from "@earendil-works/pi-ai";
+
+// ─── Type Definitions ──────────────────────────────────────────────
+
+/** A single worktree entry parsed from `git worktree list`. */
+interface WorktreeEntry {
+	/** Full path to the worktree directory. */
+	path: string;
+	/** Short commit hash checked out in this worktree. */
+	commit: string;
+	/** Branch name, or "(detached)" for detached HEAD. */
+	branch: string;
+	/** Whether this worktree is the current working directory. */
+	isCurrent: boolean;
+}
+
+/** Result of listing all worktrees. Count available via `worktrees.length`. */
+interface WorktreeListResult {
+	/** All worktrees in the repository. */
+	worktrees: WorktreeEntry[];
+}
+
+/** Error returned when a worktree operation fails. */
+interface WorktreeError {
+	/** Human-readable error message from git or validation. */
+	message: string;
+	/** Suggested fix for the user. */
+	suggestion?: string;
+}
+
+// ─── Tool Parameter Schemas ────────────────────────────────────────
+
+const createWorktreeParams = Type.Object({
+	path: Type.String({ description: "Path for the new worktree (relative or absolute)" }),
+	branch: Type.Optional(Type.String({ description: "Branch name to check out. Defaults to 'main'." })),
+	create_branch: Type.Optional(
+		Type.Boolean({
+			description: "If true and branch doesn't exist, create it. Defaults to false.",
+		}),
+	),
+});
+
+const listWorktreeParams = Type.Object({});
+
+const switchWorktreeParams = Type.Object({
+	target: Type.String({ description: "Path or branch name of the target worktree to switch to." }),
+});
+
+const removeWorktreeParams = Type.Object({
+	path: Type.String({ description: "Path of the worktree to remove." }),
+});
+
+// ─── Helper Functions (stubs) ──────────────────────────────────────
+
+/**
+ * Parse raw `git worktree list` output into structured entries.
+ * @param rawOutput - Raw stdout from `git worktree list`
+ * @param currentDir - Current working directory for comparison
+ * @returns Array of parsed worktree entries
+ */
+function parseWorktreeList(rawOutput: string, currentDir: string): WorktreeEntry[] {
+	throw new Error("not implemented");
+}
+
+/**
+ * Check if the target path exists.
+ * @param path - Path to check
+ * @param ctx - Extension context for file system access
+ * @returns True if the path exists
+ */
+async function pathExists(path: string, ctx: ExtensionContext): Promise<boolean> {
+	throw new Error("not implemented");
+}
+
+/**
+ * Resolve a worktree target (path or branch name) to its full path.
+ * @param target - Path or branch name to resolve
+ * @param worktrees - List of all worktrees
+ * @returns The resolved path, or undefined if not found
+ */
+function resolveWorktreeTarget(target: string, worktrees: WorktreeEntry[]): string | undefined {
+	throw new Error("not implemented");
+}
+
+// ─── Tool Definitions ──────────────────────────────────────────────
+
+/** Create a linked worktree for a branch in the current repo. */
+const gitWorktreeCreateTool = defineTool({
+	name: "git_worktree_create",
+	label: "Git Worktree Create",
+	description: "Create a linked worktree for a branch in the current repo.",
+	parameters: createWorktreeParams,
+	async execute(_toolCallId, _params, _signal, _onUpdate, _ctx) {
+		return {
+			content: [{ type: "text", text: "Error: git_worktree_create is not yet implemented. Suggestion: Use `git worktree add` manually until this tool is complete." }],
+			isError: true,
+		};
+	},
+});
+
+/** List all linked worktrees in the current repo. */
+const gitWorktreeListTool = defineTool({
+	name: "git_worktree_list",
+	label: "Git Worktree List",
+	description: "List all linked worktrees in the current repo.",
+	parameters: listWorktreeParams,
+	async execute(_toolCallId, _params, _signal, _onUpdate, _ctx) {
+		return {
+			content: [{ type: "text", text: "Error: git_worktree_list is not yet implemented. Suggestion: Use `git worktree list` manually until this tool is complete." }],
+			isError: true,
+		};
+	},
+});
+
+/** Switch pi's working directory to a linked worktree. */
+const gitWorktreeSwitchTool = defineTool({
+	name: "git_worktree_switch",
+	label: "Git Worktree Switch",
+	description: "Switch pi's working directory to a linked worktree.",
+	parameters: switchWorktreeParams,
+	async execute(_toolCallId, _params, _signal, _onUpdate, _ctx) {
+		return {
+			content: [{ type: "text", text: "Error: git_worktree_switch is not yet implemented. Suggestion: Use the `/worktree` command or `git worktree` manually until this tool is complete." }],
+			isError: true,
+		};
+	},
+});
+
+/** Remove a linked worktree. */
+const gitWorktreeRemoveTool = defineTool({
+	name: "git_worktree_remove",
+	label: "Git Worktree Remove",
+	description: "Remove a linked worktree.",
+	parameters: removeWorktreeParams,
+	async execute(_toolCallId, _params, _signal, _onUpdate, _ctx) {
+		return {
+			content: [{ type: "text", text: "Error: git_worktree_remove is not yet implemented. Suggestion: Use `git worktree remove` manually until this tool is complete." }],
+			isError: true,
+		};
+	},
+});
+
+// ─── Extension Entry Point ────────────────────────────────────────
+
+export default function (pi: ExtensionAPI) {
+	// Register tools
+	pi.registerTool(gitWorktreeCreateTool);
+	pi.registerTool(gitWorktreeListTool);
+	pi.registerTool(gitWorktreeSwitchTool);
+	pi.registerTool(gitWorktreeRemoveTool);
+
+	// Register /worktree command
+	pi.registerCommand("worktree", {
+		description: "Interactive picker to switch between linked worktrees.",
+		handler: async (_args, _ctx) => {
+			return {
+				content: [{ type: "text", text: "Error: /worktree command is not yet implemented. Suggestion: Use `git worktree list` and navigate manually until this command is complete." }],
+				isError: true,
+			};
+		},
+	});
+}