@zenobius/pi-worktrees 0.2.0 → 0.3.0-next.1

package/README.md

@@ -1,5 +1,8 @@
 # `@zenobius/pi-worktrees`
 
+<img width="1531" height="1172" alt="image" src="https://github.com/user-attachments/assets/33fe4c01-4d9b-41ec-a326-116db6e750df" />
+
+
 Git worktree management for [Pi Coding Agent](https://github.com/badlogic/pi-mono) with a clean `/worktree` command surface.
 
 This extension helps you spin up isolated feature workspaces quickly, with safety checks and optional post-create automation.
@@ -44,6 +47,28 @@ If Pi is already running, use `/reload` to load newly installed extensions.
 
 ---
 
+## Getting started in 2 minutes
+
+1. Install the extension:
+
+```bash
+pi install npm:@zenobius/pi-worktrees
+```
+
+2. Open a git repo in Pi and run:
+
+```text
+/worktree init
+/worktree create auth-refactor
+/worktree list
+```
+
+3. Optional: jump into it from your shell using the printed path:
+
+```text
+/worktree cd auth-refactor
+```
+
 ## Quick start
 
 In Pi:
@@ -58,11 +83,9 @@ In Pi:
 /worktree prune
 ```
 
-### How I use `/worktrees`
-
-Since I use nvim and zellij, i want the worktrees I create to be clones of the workspace
-I have for the current one, so to this end, my `onCreate` looks like: 
+### Example: How I use `/worktree`
 
+I use Neovim and Zellij, and I want each new worktree to boot a ready-to-code workspace. My `onCreate` looks like:
 ```json
 {
   "worktrees": {
@@ -78,12 +101,9 @@ I have for the current one, so to this end, my `onCreate` looks like:
     }
   }
 }
-
 ```
 
-This means when ever i create a new worktree, it creates a new zellij tab with nvim and pi running
-in it on the new worktree path.
-
+This creates a new Zellij tab with Neovim and Pi running in the new worktree path.
 ---
 
 ## Command reference
@@ -92,7 +112,7 @@ in it on the new worktree path.
 |---|---|
 | `/worktree init` | Interactive setup for extension settings |
 | `/worktree settings` | Show all current settings |
-| `/worktree settings <key>` | Get one setting (`worktreeRoot`, `onCreate`) |
+| `/worktree settings <key>` | Get one setting (`worktreeRoot`, `parentDir` alias, `onCreate`) |
 | `/worktree settings <key> <value>` | Set one setting |
 | `/worktree create <feature-name>` | Create a new worktree + branch `feature/<feature-name>` |
 | `/worktree list` | List all worktrees (`/worktree ls` alias) |
@@ -121,6 +141,13 @@ Settings live in `~/.pi/agent/pi-worktrees-settings.json`.
     }
   },
   "matchingStrategy": "fail-on-tie",
+  "onCreateDisplayOutputMaxLines": 5,
+  "onCreateCmdDisplayPending": "[ ] {{cmd}}",
+  "onCreateCmdDisplaySuccess": "[x] {{cmd}}",
+  "onCreateCmdDisplayError": "[ ] {{cmd}} [ERROR]",
+  "onCreateCmdDisplayPendingColor": "dim",
+  "onCreateCmdDisplaySuccessColor": "success",
+  "onCreateCmdDisplayErrorColor": "error",
   "worktree": {
     "worktreeRoot": "~/.local/share/worktrees/{{project}}",
     "onCreate": "mise setup"
@@ -128,14 +155,30 @@ Settings live in `~/.pi/agent/pi-worktrees-settings.json`.
 }
 ```
 
+### Configuration reference
+
+| Key | Type | Default | Description |
+|---|---|---|---|
+| `worktrees` | `Record<string, WorktreeSettings>` | `{}` | Pattern-matched settings by repo URL or glob. |
+| `matchingStrategy` | `'fail-on-tie' \| 'first-wins' \| 'last-wins'` | `fail-on-tie` | Tie-break behavior for equally specific patterns. |
+| `onCreateDisplayOutputMaxLines` | `number` (integer, `>= 0`) | `5` | Number of latest stdout/stderr lines shown in live UI updates during `onCreate`. |
+| `onCreateCmdDisplayPending` | `string` | `[ ] {{cmd}}` | Template for pending/running command display lines. |
+| `onCreateCmdDisplaySuccess` | `string` | `[x] {{cmd}}` | Template for successful command display lines. |
+| `onCreateCmdDisplayError` | `string` | `[ ] {{cmd}} [ERROR]` | Template for failed command display lines. |
+| `onCreateCmdDisplayPendingColor` | `string` | `dim` | Pi theme color name for pending/running command lines. |
+| `onCreateCmdDisplaySuccessColor` | `string` | `success` | Pi theme color name for successful command lines. |
+| `onCreateCmdDisplayErrorColor` | `string` | `error` | Pi theme color name for failed command lines. |
+| `worktree` (legacy) | `WorktreeSettings` | n/a | Legacy fallback shape; migrated automatically. |
+
 ### Matching model
 
 For the current repository, settings are resolved in this order:
-
 1. Exact URL match in `worktrees`
 2. Most-specific glob match in `worktrees`
-3. Fallback to legacy `worktree`
+3. Normalized fallback pattern `"**"`
 
+At runtime, the extension normalizes the matcher input map to always include `worktrees["**"]`.
+If not explicitly configured, that fallback is seeded from built-in defaults (`worktreeRoot: "{{mainWorktree}}.worktrees"`, `onCreate: "echo \"Created {{path}}\""`).
 `matchingStrategy` controls ties between equally specific patterns:
 
 - `fail-on-tie` (default)
@@ -151,6 +194,34 @@ For the current repository, settings are resolved in this order:
 
 When an array is used, commands run sequentially and stop on first failure.
 
+### `onCreateDisplayOutputMaxLines`
+
+Controls only live UI output verbosity for `onCreate` command execution.
+- **Default**: `5`
+- **Scope**: display only
+- **Does not affect**: logfile contents (full stdout/stderr is still logged)
+
+### `onCreate` command line display templates
+
+These templates control how each command line is rendered in the live progress list.
+
+- `onCreateCmdDisplayPending` (default: `[ ] {{cmd}}`)
+- `onCreateCmdDisplaySuccess` (default: `[x] {{cmd}}`)
+- `onCreateCmdDisplayError` (default: `[ ] {{cmd}} [ERROR]`)
+
+Supported token:
+- `{{cmd}}` (or `{cmd}`) → expanded command string
+
+### `onCreate` command line display colors
+
+These settings use Pi theme color names:
+
+- `onCreateCmdDisplayPendingColor` (default: `dim`)
+- `onCreateCmdDisplaySuccessColor` (default: `success`)
+- `onCreateCmdDisplayErrorColor` (default: `error`)
+
+Supported color names in this extension: `dim`, `accent`, `info`, `success`, `warning`, `error`.
+
 ### `worktreeRoot`
 
 Where new worktrees are created.

package/dist/cmds/shared.d.ts

@@ -11,6 +11,13 @@ export interface OnCreateResult {
 }
 export interface OnCreateHookOptions {
     logPath?: string;
+    displayOutputMaxLines?: number;
+    cmdDisplayPending?: string;
+    cmdDisplaySuccess?: string;
+    cmdDisplayError?: string;
+    cmdDisplayPendingColor?: string;
+    cmdDisplaySuccessColor?: string;
+    cmdDisplayErrorColor?: string;
 }
 /**
  * Runs post-create hooks sequentially.