@zenobius/pi-worktrees 0.1.0 → 0.2.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,6 +83,27 @@ In Pi:
 /worktree prune
 ```
 
+### 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": {
+    "**": {
+      "worktreeRoot": "{{mainWorktree}}.worktrees",
+      "onCreate": [
+        "mise trust --yes",
+        "mise setup",
+        "zellij action new-tab --name {{name}} --cwd {{path}}",
+        "zellij action new-pane --in-place --cwd {{path}} -- nvim",
+        "zellij action new-pane --cwd {{path}} --direction right -- pi"
+      ]
+    }
+  }
+}
+```
+
+This creates a new Zellij tab with Neovim and Pi running in the new worktree path.
 ---
 
 ## Command reference
@@ -66,7 +112,7 @@ In Pi:
 |---|---|
 | `/worktree init` | Interactive setup for extension settings |
 | `/worktree settings` | Show all current settings |
-| `/worktree settings <key>` | Get one setting (`parentDir`, `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) |
@@ -74,47 +120,147 @@ In Pi:
 | `/worktree cd <name>` | Print matching worktree path |
 | `/worktree remove <name>` | Remove a worktree (`/worktree rm` alias) |
 | `/worktree prune` | Remove stale worktree metadata |
+| `/worktree templates` | Preview template variables with current + generated values |
 
 ---
 
 ## Configuration
 
-Settings live in `~/.pi/agent/pi-worktrees-settings.json` under `worktree`: 
+Settings live in `~/.pi/agent/pi-worktrees-settings.json`.
 
 ```json
 {
+  "worktrees": {
+    "github.com/org/repo": {
+      "worktreeRoot": "~/work/org/repo.worktrees",
+      "onCreate": ["mise install", "bun install"]
+    },
+    "github.com/org/*": {
+      "worktreeRoot": "~/work/org/shared.worktrees",
+      "onCreate": "mise setup"
+    }
+  },
+  "matchingStrategy": "fail-on-tie",
+  "onCreateDisplayOutputMaxLines": 5,
+  "onCreateCmdDisplayPending": "[ ] {{cmd}}",
+  "onCreateCmdDisplaySuccess": "[x] {{cmd}}",
+  "onCreateCmdDisplayError": "[ ] {{cmd}} [ERROR]",
+  "onCreateCmdDisplayPendingColor": "dim",
+  "onCreateCmdDisplaySuccessColor": "success",
+  "onCreateCmdDisplayErrorColor": "error",
   "worktree": {
-    "parentDir": "~/.local/share/worktrees/{{project}}",
+    "worktreeRoot": "~/.local/share/worktrees/{{project}}",
     "onCreate": "mise setup"
   }
 }
 ```
 
-### `parentDir`
+### Configuration reference
 
-Where new worktrees are created.
+| 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. |
 
-- **Default**: `../<project>.worktrees/` (relative to your main worktree)
-- Supports template variables
+### 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`
+
+`matchingStrategy` controls ties between equally specific patterns:
+
+- `fail-on-tie` (default)
+- `first-wins`
+- `last-wins`
 
 ### `onCreate`
 
-Optional command run **after** successful worktree creation, in the new worktree directory.
+`onCreate` accepts either:
+
+- a single string command
+- an array of commands
+
+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
 
-Useful examples:
+These templates control how each command line is rendered in the live progress list.
 
-- `mise setup`
-- `bun install`
-- `mise setup && bun install`
+- `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.
+
+- **Default**: `{{mainWorktree}}.worktrees`
+- Supports template variables
+
+> Backward compatibility: `parentDir` is still accepted as a deprecated alias for `worktreeRoot`.
+> The extension will migrate existing `parentDir` values to `worktreeRoot` automatically.
 ### Template variables
 
-Available in `parentDir` and `onCreate` strings:
+Available in `worktreeRoot` and `onCreate` values:
 
 - `{{path}}` → created worktree path
 - `{{name}}` → feature/worktree name
 - `{{branch}}` → created branch name
 - `{{project}}` → repository name
+- `{{mainWorktree}}` → main worktree path (repository root)
+
+### Migration note
+
+Legacy single-worktree config remains supported and is migrated through the shared
+`@zenobius/pi-extension-config` migration chain.
+```json
+{
+  "worktree": {
+    "worktreeRoot": "...",
+    "onCreate": "..."
+  }
+}
+```
+
+Migration behavior:
+
+1. Legacy flat keys are normalized to `worktree`
+2. Legacy `worktree` is migrated to `worktrees["**"]`
+3. Migration version metadata is managed by `@zenobius/pi-extension-config`
+
+Deprecation timing follows the migration policy in `@zenobius/pi-extension-config`.
+This extension does not apply a separate ad-hoc deprecation mechanism.
 
 ---
 

package/dist/cmds/cmdCd.d.ts

@@ -0,0 +1,3 @@
+import type { ExtensionCommandContext } from '@mariozechner/pi-coding-agent';
+import type { CommandDeps } from '../types.ts';
+export declare function cmdCd(args: string, ctx: ExtensionCommandContext, deps: CommandDeps): Promise<void>;

package/dist/cmds/cmdCreate.d.ts

@@ -0,0 +1,3 @@
+import type { ExtensionCommandContext } from '@mariozechner/pi-coding-agent';
+import type { CommandDeps } from '../types.ts';
+export declare function cmdCreate(args: string, ctx: ExtensionCommandContext, deps: CommandDeps): Promise<void>;

package/dist/cmds/cmdInit.d.ts

@@ -0,0 +1,3 @@
+import type { ExtensionCommandContext } from '@mariozechner/pi-coding-agent';
+import type { CommandDeps } from '../types.ts';
+export declare function cmdInit(_args: string, ctx: ExtensionCommandContext, deps: CommandDeps): Promise<void>;

package/dist/cmds/cmdList.d.ts

@@ -0,0 +1,2 @@
+import { CmdHandler } from '../types.ts';
+export declare const cmdList: CmdHandler;

package/dist/cmds/cmdPrune.d.ts

@@ -0,0 +1,2 @@
+import type { ExtensionCommandContext } from '@mariozechner/pi-coding-agent';
+export declare function cmdPrune(_args: string, ctx: ExtensionCommandContext): Promise<void>;

package/dist/cmds/cmdRemove.d.ts

@@ -0,0 +1,3 @@
+import type { ExtensionCommandContext } from '@mariozechner/pi-coding-agent';
+import type { CommandDeps } from '../types.ts';
+export declare function cmdRemove(args: string, ctx: ExtensionCommandContext, deps: CommandDeps): Promise<void>;

package/dist/cmds/cmdSettings.d.ts

@@ -0,0 +1,3 @@
+import type { ExtensionCommandContext } from '@mariozechner/pi-coding-agent';
+import type { CommandDeps } from '../types.ts';
+export declare function cmdSettings(args: string, ctx: ExtensionCommandContext, deps: CommandDeps): Promise<void>;

package/dist/cmds/cmdStatus.d.ts

@@ -0,0 +1,2 @@
+import type { ExtensionCommandContext } from '@mariozechner/pi-coding-agent';
+export declare function cmdStatus(_args: string, ctx: ExtensionCommandContext): Promise<void>;

package/dist/cmds/cmdTemplates.d.ts

@@ -0,0 +1,3 @@
+import type { ExtensionCommandContext } from '@mariozechner/pi-coding-agent';
+import type { CommandDeps } from '../types.ts';
+export declare function cmdTemplates(_args: string, ctx: ExtensionCommandContext, deps: CommandDeps): Promise<void>;

package/dist/cmds/shared.d.ts

@@ -0,0 +1,26 @@
+import type { WorktreeCreatedContext } from '../types.ts';
+import { WorktreeSettingsConfig } from '../services/config/schema.ts';
+export interface OnCreateResult {
+    success: boolean;
+    executed: string[];
+    failed?: {
+        command: string;
+        code: number;
+        error: string;
+    };
+}
+export interface OnCreateHookOptions {
+    logPath?: string;
+    displayOutputMaxLines?: number;
+    cmdDisplayPending?: string;
+    cmdDisplaySuccess?: string;
+    cmdDisplayError?: string;
+    cmdDisplayPendingColor?: string;
+    cmdDisplaySuccessColor?: string;
+    cmdDisplayErrorColor?: string;
+}
+/**
+ * Runs post-create hooks sequentially.
+ * Stops at first failure and reports the failing command.
+ */
+export declare function runOnCreateHook(createdCtx: WorktreeCreatedContext, settings: WorktreeSettingsConfig, notify: (msg: string, type: 'info' | 'error' | 'warning') => void, options?: OnCreateHookOptions): Promise<OnCreateResult>;

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Worktree Extension - Git worktree management for isolated workspaces
+ *
+ * Provides commands to create, list, and manage git worktrees for feature development.
+ * Codifies the patterns from the using-git-worktrees skill into an interactive command.
+ */
+import type { ExtensionFactory } from '@mariozechner/pi-coding-agent';
+declare const PiWorktreeExtension: ExtensionFactory;
+export default PiWorktreeExtension;