@fatdoge/wtree 0.1.9 → 0.2.0

package/skills/wtree/SKILL.md

@@ -0,0 +1,162 @@
+---
+name: wtree
+description: "Manage git worktrees using the wtree CLI. Use when the user wants to create, list, delete, open, lock, unlock, or prune git worktrees, or work with multiple branches simultaneously."
+allowed-tools: Bash
+user-invocable: true
+---
+
+# wtree - Git Worktree Manager
+
+You manage git worktrees using the `wtree` CLI tool. Always use non-interactive flags so commands complete without user input.
+
+## Prerequisites
+
+The `wtree` CLI must be installed globally (`npm install -g @fatdoge/wtree`) or run via `npx @fatdoge/wtree`. If working inside the wtree project itself, use `node dist-node/api/cli/wtree.js`.
+
+## Important Rules
+
+1. **Always use `--json` flag** when you need to parse output programmatically
+2. **Always use `--yes`** to skip all confirmation prompts
+3. **Always use `--no-editor`** unless the user explicitly asks to open an editor
+4. **Always use `--no-install`** unless the user explicitly asks to install dependencies
+5. **Use `--repo <path>`** if the current working directory is not inside the target git repository
+6. **Never run `wtree` without a subcommand** — that enters interactive mode
+
+## Commands Reference
+
+### List Worktrees
+
+```bash
+wtree list --json
+# With specific repo:
+wtree list --json --repo /path/to/repo
+```
+
+Returns a JSON array of worktree objects:
+```json
+[
+  {
+    "id": "<base64url-encoded-path>",
+    "path": "/absolute/path/to/worktree",
+    "head": "<commit-sha>",
+    "branch": "branch-name",
+    "isMain": true,
+    "isLocked": false
+  }
+]
+```
+
+### Create Worktree
+
+For an **existing** local or remote branch:
+```bash
+wtree create <branch-name> --yes --no-editor --no-install --json
+```
+
+For a **new branch** based on a reference:
+```bash
+wtree create <new-branch-name> --base <base-ref> --yes --no-editor --no-install --json
+```
+
+With a specific target directory:
+```bash
+wtree create <branch> --dir <relative-path> --yes --no-editor --no-install --json
+```
+
+Parameters:
+- `<branch-name>` (positional, required): The branch to check out or create
+- `--dir <path>`: Worktree directory, relative to repo root (default: `worktrees/<branch-sanitized>`)
+- `--base <ref>`: Base reference for new branch creation (e.g., `main`, `origin/main`)
+- `--yes`: Auto-confirm new branch creation and accept default directory
+- `--editor <name>`: Open in specific editor after creation (`trae`, `cursor`, `code`)
+- `--no-editor`: Do not open any editor
+- `--no-install`: Skip automatic dependency installation
+- `--json`: Output result as JSON
+
+Returns on success:
+```json
+{"ok": true, "data": {"id": "...", "path": "...", "head": "...", "branch": "...", "isMain": false, "isLocked": false}}
+```
+
+### Delete Worktree
+
+Delete one or more worktrees by branch name or path:
+```bash
+wtree delete <branch-or-path> --yes --json
+wtree delete <branch1> <branch2> --yes --json
+```
+
+Force delete (even with uncommitted changes):
+```bash
+wtree delete <branch> --yes --force --json
+```
+
+Parameters:
+- Positional args: Worktree identifiers (branch name, path, or directory basename)
+- `--yes`: Skip deletion confirmation
+- `--force`: Force-delete even if there are uncommitted changes
+- `--json`: Output result as JSON
+
+### Open Worktree
+
+```bash
+wtree open <branch-or-path>
+```
+
+Opens the worktree directory in the system file manager.
+
+### Lock / Unlock Worktree
+
+```bash
+wtree lock <branch-or-path>
+wtree unlock <branch-or-path>
+```
+
+### Prune Invalid Worktrees
+
+```bash
+wtree prune
+```
+
+Removes worktree records for directories that no longer exist.
+
+### Configuration
+
+```bash
+wtree config                       # Show all config as JSON
+wtree config get <key>            # Get a single config value
+wtree config set <key> <value>    # Set a config value
+```
+
+Available config keys: `baseDir`, `openCommand`, `editorCommand`
+
+## Workflow Examples
+
+### Create a worktree for a new feature branch
+
+```bash
+# 1. List existing worktrees
+wtree list --json
+
+# 2. Create worktree with new branch from main
+wtree create feature/my-feature --base main --yes --no-editor --no-install --json
+```
+
+### Clean up old worktrees
+
+```bash
+# 1. List all worktrees
+wtree list --json
+
+# 2. Delete unwanted ones
+wtree delete feature/old-branch --yes --json
+
+# 3. Prune stale records
+wtree prune
+```
+
+### Create worktree for an existing remote branch
+
+```bash
+wtree create feature/existing-branch --yes --no-editor --no-install --json
+```

package/src/App.tsx

@@ -4,7 +4,7 @@ import Worktrees from "@/pages/Worktrees";
 import CreateWorktree from "@/pages/CreateWorktree";
 import SettingsPage from "@/pages/SettingsPage";
 import HelpPage from "@/pages/HelpPage";
-import ToastHost from "@/components/ToastHost";
+import { Toaster } from "sonner";
 import { useThemeStore } from "@/stores/themeStore";
 
 export default function App() {
@@ -16,7 +16,7 @@ export default function App() {
 
   return (
     <Router>
-      <ToastHost />
+      <Toaster position="top-right" richColors theme="system" />
       <Routes>
         <Route path="/" element={<Worktrees />} />
         <Route path="/create" element={<CreateWorktree />} />

package/src/pages/CreateWorktree.tsx

@@ -4,9 +4,9 @@ import { Link, useNavigate } from 'react-router-dom'
 import { useTranslation } from 'react-i18next'
 import Button from '@/components/Button'
 import Input from '@/components/Input'
-import { useToastStore } from '@/stores/toastStore'
 import { useWorktreeStore } from '@/stores/worktreeStore'
 import type { CreateWorktreeRequest } from '../../shared/wtui-types'
+import { toast } from 'sonner'
 
 type Mode = 'existing' | 'new'
 
@@ -16,7 +16,6 @@ export default function CreateWorktree() {
   const create = useWorktreeStore((s) => s.create)
   const branches = useWorktreeStore((s) => s.branches)
   const fetchBranches = useWorktreeStore((s) => s.fetchBranches)
-  const toast = useToastStore((s) => s.push)
 
   useEffect(() => {
     fetchBranches()
@@ -51,14 +50,14 @@ export default function CreateWorktree() {
       }
       const created = await create(payload)
       if (!created) {
-        toast({ type: 'error', title: '创建失败' })
+        toast.error('创建失败')
         return
       }
       setResultPath(created.path)
-      toast({ type: 'success', title: '创建成功' })
+      toast.success('创建成功')
     } catch (e: unknown) {
       const msg = e instanceof Error ? e.message : String(e)
-      toast({ type: 'error', title: '创建失败', detail: msg })
+      toast.error('创建失败', { description: msg })
     } finally {
       setSubmitting(false)
     }

package/src/pages/SettingsPage.tsx

@@ -4,15 +4,14 @@ import { Link } from 'react-router-dom'
 import { useTranslation } from 'react-i18next'
 import Button from '@/components/Button'
 import Input from '@/components/Input'
-import { useToastStore } from '@/stores/toastStore'
 import { useWorktreeStore } from '@/stores/worktreeStore'
 import { useThemeStore } from '@/stores/themeStore'
 import { apiGet, apiPut } from '@/utils/api'
 import type { WtuiConfig } from '../../shared/wtui-types'
+import { toast } from 'sonner'
 
 export default function SettingsPage() {
   const { t, i18n } = useTranslation()
-  const toast = useToastStore((s) => s.push)
   const prune = useWorktreeStore((s) => s.prune)
   const { theme, setTheme } = useThemeStore()
   const [cfg, setCfg] = useState<WtuiConfig>({})
@@ -34,11 +33,11 @@ export default function SettingsPage() {
       const r = await apiPut<WtuiConfig, WtuiConfig>('/api/config', cfg)
       if (!r.ok) {
         const msg = (r as { ok: false; error: { message: string } }).error.message
-        toast({ type: 'error', title: t('settings.toast.saveFailed'), detail: msg })
+        toast.error(t('settings.toast.saveFailed'), { description: msg })
         return
       }
       setCfg(r.data)
-      toast({ type: 'success', title: t('settings.toast.saveSuccess') })
+      toast.success(t('settings.toast.saveSuccess'))
     } finally {
       setLoading(false)
     }
@@ -51,11 +50,11 @@ export default function SettingsPage() {
       const r = await apiPut<WtuiConfig, WtuiConfig>('/api/config', {})
       if (!r.ok) {
         const msg = (r as { ok: false; error: { message: string } }).error.message
-        toast({ type: 'error', title: t('settings.toast.resetFailed', '重置失败'), detail: msg })
+        toast.error(t('settings.toast.resetFailed', '重置失败'), { description: msg })
         return
       }
       setCfg(r.data)
-      toast({ type: 'info', title: t('settings.toast.resetSuccess', '已重置') })
+      toast.info(t('settings.toast.resetSuccess', '已重置'))
     } finally {
       setLoading(false)
     }
@@ -65,7 +64,11 @@ export default function SettingsPage() {
     setPruning(true)
     try {
       const ok = await prune()
-      toast({ type: ok ? 'success' : 'error', title: ok ? t('settings.toast.pruneSuccess') : t('settings.toast.pruneFailed') })
+      if (ok) {
+        toast.success(t('settings.toast.pruneSuccess'))
+      } else {
+        toast.error(t('settings.toast.pruneFailed'))
+      }
     } finally {
       setPruning(false)
     }

package/src/pages/Worktrees.tsx

@@ -4,8 +4,8 @@ import { Link } from 'react-router-dom'
 import { useTranslation } from 'react-i18next'
 import Button from '@/components/Button'
 import Modal from '@/components/Modal'
-import { useToastStore } from '@/stores/toastStore'
 import { useWorktreeStore } from '@/stores/worktreeStore'
+import { toast } from 'sonner'
 
 function truncatePath(p: string) {
   if (p.length <= 70) return p
@@ -23,7 +23,6 @@ export default function Worktrees() {
   const open = useWorktreeStore((s) => s.open)
   const lock = useWorktreeStore((s) => s.lock)
   const unlock = useWorktreeStore((s) => s.unlock)
-  const toast = useToastStore((s) => s.push)
 
   const [removeId, setRemoveId] = useState<string | null>(null)
   const [forceDelete, setForceDelete] = useState(false)
@@ -47,24 +46,20 @@ export default function Worktrees() {
     try {
       const res = await remove(removeId, forceDelete)
       if (res.success) {
-        toast({ type: 'success', title: forceDelete ? t('worktrees.toast.forceDeleteSuccess') : t('worktrees.toast.deleteSuccess') })
+        toast.success(forceDelete ? t('worktrees.toast.forceDeleteSuccess') : t('worktrees.toast.deleteSuccess'))
         closeModal()
       } else {
         const msg = res.error || ''
         if (msg.toLowerCase().includes('force') || msg.includes('modified') || msg.includes('untracked')) {
           setForceDelete(true)
-          toast({
-            type: 'error',
-            title: t('worktrees.toast.deleteFailed'),
-            detail: t('worktrees.toast.deleteWarning'),
-          })
+          toast.error(t('worktrees.toast.deleteFailed'), { description: t('worktrees.toast.deleteWarning') })
         } else {
-          toast({ type: 'error', title: t('worktrees.toast.deleteFailed'), detail: msg })
+          toast.error(t('worktrees.toast.deleteFailed'), { description: msg })
         }
       }
     } catch (e: unknown) {
       const msg = e instanceof Error ? e.message : String(e)
-      toast({ type: 'error', title: t('worktrees.toast.deleteFailed'), detail: msg })
+      toast.error(t('worktrees.toast.deleteFailed'), { description: msg })
     } finally {
       setIsDeleting(false)
     }
@@ -73,9 +68,9 @@ export default function Worktrees() {
   const onCopy = async (text: string) => {
     try {
       await navigator.clipboard.writeText(text)
-      toast({ type: 'success', title: t('worktrees.toast.copySuccess') })
+      toast.success(t('worktrees.toast.copySuccess'))
     } catch {
-      toast({ type: 'error', title: t('worktrees.toast.copyFailed') })
+      toast.error(t('worktrees.toast.copyFailed'))
     }
   }
 
@@ -177,10 +172,9 @@ export default function Worktrees() {
                           onClick={(e) => {
                             e.stopPropagation()
                             open(wt.id).then((ok) =>
-                              toast({
-                                type: ok ? 'success' : 'error',
-                                title: ok ? t('worktrees.toast.folderSuccess') : t('worktrees.toast.folderFailed'),
-                              }),
+                              ok
+                                ? toast.success(t('worktrees.toast.folderSuccess'))
+                                : toast.error(t('worktrees.toast.folderFailed')),
                             )
                           }}
                         >
@@ -255,10 +249,7 @@ export default function Worktrees() {
                       const msg = selected.isLocked ? t('worktrees.toast.unlockSuccess') : t('worktrees.toast.lockSuccess')
                       const msgFail = selected.isLocked ? t('worktrees.toast.unlockFailed') : t('worktrees.toast.lockFailed')
                       action(selected.id).then((ok) =>
-                        toast({
-                          type: ok ? 'success' : 'error',
-                          title: ok ? msg : msgFail,
-                        }),
+                        ok ? toast.success(msg) : toast.error(msgFail),
                       )
                     }}
                   >
@@ -271,10 +262,7 @@ export default function Worktrees() {
                     size="sm"
                     onClick={() =>
                       open(selected.id, 'editor').then((ok) =>
-                        toast({
-                          type: ok ? 'success' : 'error',
-                          title: ok ? t('worktrees.toast.ideSuccess') : t('worktrees.toast.ideFailed'),
-                        }),
+                        ok ? toast.success(t('worktrees.toast.ideSuccess')) : toast.error(t('worktrees.toast.ideFailed')),
                       )
                     }
                   >
@@ -287,10 +275,7 @@ export default function Worktrees() {
                     size="sm"
                     onClick={() =>
                       open(selected.id, 'folder').then((ok) =>
-                        toast({
-                          type: ok ? 'success' : 'error',
-                          title: ok ? t('worktrees.toast.folderSuccess') : t('worktrees.toast.folderFailed'),
-                        }),
+                        ok ? toast.success(t('worktrees.toast.folderSuccess')) : toast.error(t('worktrees.toast.folderFailed')),
                       )
                     }
                   >
@@ -351,4 +336,3 @@ export default function Worktrees() {
     </div>
   )
 }
-