David Kong
dd2202f54c
## Summary Register all four git worktree tools with correct TypeBox schemas and placeholder implementations. ## Changes - Added `.pi/extensions/pi-worktree.ts` with four tool registrations: - `git_worktree_list` — no params, lists linked worktrees - `git_worktree_create` — path, branch?, create_branch? params - `git_worktree_switch` — target param for switching cwd - `git_worktree_remove` — path param for removing worktrees - Each tool returns "Not implemented yet." placeholder response ## Testing - [x] All four tools registered with correct TypeBox schemas - [x] Calling each tool returns a response (placeholder) - [ ] Extension loads without errors when pi starts (manual verification needed) ## Checklist - [ ] Self-reviewed the diff - [ ] Code follows project conventions - [ ] Descriptive naming (no single-character variables) Co-authored-by: David Kong <davkon@gmail.com> Reviewed-on: #15
101 lines
3.1 KiB
Markdown
101 lines
3.1 KiB
Markdown
# AGENTS.md — pi-worktree Extension
|
|
|
|
## Repo Details
|
|
|
|
| Property | Value |
|
|
|----------|-------|
|
|
| **Host** | `git.excelera.net` |
|
|
| **Remote** | `https://git.excelera.net/david/pi-worktrees.git` |
|
|
| **Owner** | david |
|
|
| **Repo** | pi-worktrees |
|
|
|
|
## Using `fj` CLI to Pull Issues
|
|
|
|
This repo uses the [`fj`](https://git.excelera.net/david/fj) CLI tool (Forgejo CLI) for issue operations. It's auto-detected from the git remote, so `-H` is optional inside this repo:
|
|
|
|
```bash
|
|
# Search open issues in this repo
|
|
fj issue search --repo pi-worktrees
|
|
|
|
# View a specific issue
|
|
fj issue view <ISSUE_NUM>
|
|
|
|
# List all open issues
|
|
fj issue search --state open
|
|
```
|
|
|
|
### Prerequisites
|
|
|
|
- `fj` must be installed and authenticated (`fj whoami`)
|
|
- Credentials stored at `~/.local/share/forgejo-cli/keys.json`
|
|
- Auth via OAuth login or application token on `git.excelera.net`
|
|
|
|
## Project Structure
|
|
|
|
```
|
|
.pi/extensions/pi-worktree.ts # Single-file extension (all tool + command logic)
|
|
README.md # User-facing documentation
|
|
DESIGN.md # Architecture and design decisions
|
|
DOMAIN.md # Domain concepts and terminology
|
|
```
|
|
|
|
## Tech Stack
|
|
|
|
- **Language**: TypeScript
|
|
- **Schema**: TypeBox (`@sinclair/typebox`) for tool parameter schemas
|
|
- **Runtime**: pi coding agent extension API (`ExtensionAPI`, `ExtensionContext`)
|
|
- **Git**: native via `pi.exec("git", [...])` — no external git packages
|
|
- **No npm dependencies** in v1 beyond what pi provides
|
|
|
|
## Extension Entry Point
|
|
|
|
The extension is a single default-exported function:
|
|
|
|
```typescript
|
|
import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
|
|
import { Type } from "typebox";
|
|
|
|
export default function (pi: ExtensionAPI) {
|
|
// register tools and commands here
|
|
}
|
|
```
|
|
|
|
## Tool Conventions
|
|
|
|
- Each tool is a `Type.Object` schema + async execute function.
|
|
- Execute signature: `(toolCallId, params, signal, onUpdate, ctx)`
|
|
- Always check `result.exitCode !== 0` for git failures — surface the message with suggested fixes.
|
|
- **Fail fast**: refuse dangerous operations (existing paths, current branch, uncommitted changes) with clear messages and suggestions. No silent auto-correction.
|
|
|
|
## Command Conventions
|
|
|
|
- Register via `pi.registerCommand("name", { description, handler })`.
|
|
- Use `ctx.ui.select()` for interactive pickers.
|
|
- Parse structured data from tool results (not raw text).
|
|
|
|
## State Management
|
|
|
|
- Tools are **stateless** — each call works independently based on current git state.
|
|
- Session memory is ephemeral (per pi process lifetime) for back-switching behavior only.
|
|
|
|
## Error Handling Pattern
|
|
|
|
```typescript
|
|
if (result.exitCode !== 0) {
|
|
return {
|
|
content: [{ type: "text", text: `Error: ${result.stderr}. Suggestion: <fix>` }],
|
|
isError: true
|
|
};
|
|
}
|
|
```
|
|
|
|
Always include a suggested fix in error messages.
|
|
|
|
## Validation Checklist
|
|
|
|
- [ ] Extension loads without errors when pi starts
|
|
- [ ] All four tools registered with correct signatures
|
|
- [ ] Error paths return `isError: true` with helpful messages
|
|
- [ ] `/worktree` command shows interactive picker
|
|
- [ ] Branch display updates after switching worktrees
|
|
- [ ] No external dependencies beyond TypeBox + pi SDK
|