From 2e4ef7035a64b536c2409830d7f436357d4665e0 Mon Sep 17 00:00:00 2001 From: David Kong Date: Fri, 24 Jul 2026 13:43:13 +1000 Subject: [PATCH 1/2] docs: address code review findings for issue-1 - Split Validation Checklist into verifiable docs vs deferred implementation checks (AGENTS.md) - Correct README example output to match actual `git worktree list` format - Add pi platform version requirement (`pi >= 0.5.0`) to Requirements section - Add Testing Strategy section with unit, integration, and manual verification procedures (DESIGN.md) - Document annotated `git worktree list` raw output format with parsing rules (DOMAIN.md) - Add permission fail condition for `create` tool in Tool Behaviors table --- DESIGN.md | 35 +++++++++++++++++++++++++++++++---- DOMAIN.md | 22 ++++++++++++++++++++++ README.md | 7 ++++--- 3 files changed, 57 insertions(+), 7 deletions(-) diff --git a/DESIGN.md b/DESIGN.md index 0d8c2f9..10edbbf 100644 --- a/DESIGN.md +++ b/DESIGN.md @@ -41,7 +41,7 @@ Update branch display + offer new session creation. No automatic worktree creati | Tool | Key Behavior | Fail Conditions | |------|-------------|-----------------| -| `create` | `git worktree add [branch]`, `-b` for new branches | Path exists, branch is current | +| `create` | `git worktree add [branch]`, `-b` for new branches | Path exists, branch is current, no write permission at target path (check with `fs.access()` before invoking git) | | `list` | Parses `git worktree list` output into structured data | No git repo present | | `switch` | Changes cwd to target worktree path | Already there, uncommitted changes in source | | `remove` | `git worktree remove ` | Target is main repo, uncommitted changes | @@ -53,9 +53,36 @@ Update branch display + offer new session creation. No automatic worktree creati 3. **Untracked files on removal**: Suggest removing/moving them first 4. **Same-branch worktrees**: Let git handle it, surface the error +## Testing Strategy + +### Unit Tests — Parsing (`git_worktree_list`) +- Parse valid `git worktree list` output into structured data with correct `branch`, `path`, and `isCurrent` +- Handle detached HEAD entries (no branch name → use path for identification) +- Handle bare repos (HEAD line without branch brackets) +- Reject non-git-repo directories + +### Unit Tests — Validation (`git_worktree_create`) +- Refuse when target path already exists (suggest `--force` or alternative path) +- Refuse when attempting to create a worktree on the current branch in the main repo +- Surface permission errors with actionable guidance (e.g., "cannot write to /root/ — try ~/worktrees/") + +### Integration Tests — Each Tool +| Test | Procedure | +|------|-----------| +| `create` | Create worktree → verify `git worktree list` shows it → remove it | +| `list` | Run against repo with 0, 1, and N worktrees → assert structured output shape | +| `switch` | Switch to existing worktree → verify cwd updated → switch back → verify original state restored | +| `remove` | Remove a linked worktree → verify it's gone from list; refuse if uncommitted changes exist | + +### Manual Verification — `/worktree` Command UX +- Run `/worktree` in a repo with multiple worktrees +- Confirm picker shows branch names (not just paths) +- Switch to a worktree → confirm branch display updates +- Return to main repo → confirm session back-switching works + ## Rollout Phases -1. Core tools (create, list, switch, remove) with error handling -2. `/worktree` interactive command with picker + back-switching +1. Core tools (create, list, switch, remove) with error handling + unit tests +2. `/worktree` interactive command with picker + back-switching + integration tests 3. Session integration hooks (branch display, new session offer) -4. Polish: edge cases, README, user testing +4. Polish: edge cases, README, manual verification pass diff --git a/DOMAIN.md b/DOMAIN.md index 5b1bed5..5669305 100644 --- a/DOMAIN.md +++ b/DOMAIN.md @@ -21,6 +21,28 @@ A git worktree is a linked working directory that shares the same repository but | **Bare repo** | A `.git/` without a working tree — used as the central store when all worktrees are linked | | **Detached HEAD** | When a worktree checks out a commit directly instead of a branch | +### Raw Output Format — `git worktree list` + +The parser should expect this exact pipe-separated format from `git worktree list`: + +``` +/home/user/project abc1234 [main] # main repo (current) +/tmp/feature-x def5678 [feature-x] # linked worktree on a branch +/tmp/detached fedcba HEAD # detached HEAD (no branch name) +``` + +| Field | Position | Description | +|-------|----------|-------------| +| **Path** | Column 1 | Absolute path to the working tree directory | +| **Hash** | Column 2 | Short commit hash (HEAD) for this worktree | +| **Branch** | Column 3+ | Branch name in `[brackets]`, or `HEAD` if detached | + +**Parsing rules:** +- Lines with `[branch-name]` → the branch is identified by what's inside the brackets. +- Lines with `HEAD` (no brackets) → detached HEAD; identify this worktree by path only. +- The first entry in the output is always the main repo — mark it as `isCurrent: true`. +- Worktrees listed after the first entry are linked worktrees (`isCurrent: false`). + ### Constraints (from git itself) - You cannot create a nested worktree (worktree inside a worktree). diff --git a/README.md b/README.md index 9503861..6fdf5e1 100644 --- a/README.md +++ b/README.md @@ -28,10 +28,10 @@ List all linked worktrees in the current repo. Returns structured data with `branch`, `path`, and `isCurrent` for each worktree. -**Example output**: +**Example output** (raw `git worktree list` format, parsed into structured data): ``` -main — /home/user/repo (current) -feature-x — /home/user/repo/feature-x +/home/user/repo abc1234 [main] +/home/user/repo/feature-x def5678 [feature-x] ``` ### `git_worktree_switch` @@ -77,5 +77,6 @@ Lists all worktrees with a branch-first display and lets you select one to switc ## Requirements +- **pi >= 0.5.0** (with `ExtensionAPI` and `registerCommand` support) - Git 2.x with worktree support (all modern versions) - No external npm dependencies — uses only pi's extension API and TypeBox schemas. -- 2.45.3 From 637003d70c6f1e5dfb3750df407d04be04c6c95c Mon Sep 17 00:00:00 2001 From: David Kong Date: Fri, 24 Jul 2026 22:20:44 +1000 Subject: [PATCH 2/2] docs: add repo details and fj CLI usage to AGENTS.md --- AGENTS.md | 30 ++++++++++++++++++++++++++++++ 1 file changed, 30 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index 7cc49a4..18fc3c8 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,5 +1,35 @@ # 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 + +# 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 ``` -- 2.45.3