yggtree 1.0.0 → 1.1.0

package/README.md

@@ -1,6 +1,11 @@
 # 🌳 Yggdrasil Worktree (yggtree)
 
-**Yggdrasil Worktree** (invoked as `yggtree`) is a powerful, interactive CLI designed to streamline your Git worktree workflow. Like the mythical world tree connecting the realms, Yggdrasil connects your branches into isolated, manageable worktrees.
+[![npm version](https://img.shields.io/npm/v/yggtree.svg)](https://www.npmjs.com/package/yggtree)
+[![license](https://img.shields.io/npm/l/yggtree.svg)](https://www.npmjs.com/package/yggtree)
+
+**Yggdrasil Worktree** (invoked as `yggtree`) is an interactive CLI designed to turn Git worktrees into a first‑class workflow.
+
+Like the mythical world tree connecting realms, Yggdrasil lets you grow isolated, parallel environments where ideas can evolve independently without colliding.
 
 ---
 
@@ -8,56 +13,158 @@
 
 ### Installation
 
+Run without installing:
+
 ```bash
-# Clone the repository
-git clone https://github.com/leoreisdias/yggtree.git
-cd yggtree
+npx yggtree
+```
 
-# Install dependencies and build
-npm install
-npm run build
+Or install globally:
 
-# Link the CLI globally
-npm link
+```bash
+npm install -g yggtree
 ```
 
-### Usage
+### Basic Usage
 
-Simply run `yggtree` to open the interactive menu:
+Run with no arguments to open the interactive menu:
 
 ```bash
 yggtree
 ```
 
-Or use specific commands:
+Or use commands directly:
 
 ```bash
-yggtree wt create      # Smart branch-based creation
-yggtree wt list        # View all managed worktrees
-yggtree wt prune       # Clean up stale worktree data
+yggtree wt create
+yggtree wt list
+yggtree wt enter my-feature
+```
+
+---
+
+## 🧠 Mental Model
+
+Yggdrasil is built around a few core ideas:
+
+* **Branches are ideas**
+* **Worktrees are realities**
+* **Each task deserves its own realm**
+
+Instead of constantly switching branches in one working directory, Yggdrasil creates **isolated worktrees**, each mapped to a branch, living outside your main repo.
+
+All managed worktrees live under:
+
+```
+~/.yggtree/<repo-name>/<worktree-slug>
 ```
 
+This keeps your main repository clean while enabling true parallelism.
+
+---
+
+## 🤔 Why Yggdrasil Worktree?
+
+Git worktrees are powerful, but once you start doing **parallel work**, they become tedious to manage manually.
+
+Modern development looks like this:
+
+* Fixing a bug
+* Reviewing a PR
+* Prototyping a feature
+* Letting AI agents explore refactors
+* Running tests in isolation
+
+All at the same time.
+
+Yggdrasil exists to solve three problems together:
+
+1. Parallel work without context collision
+2. Fast, repeatable environment setup
+3. Agent‑friendly isolation for AI workflows
+
+Each worktree becomes its own **small realm**, safe to explore and easy to discard.
+
 ---
 
 ## ✨ Key Features
 
-### 🌿 Smart Branch Creation (`wt create`)
-The primary way to start working. Instead of worrying about folder names, just tell Yggdrasil which branch you want to work on.
-- **Auto-Slug**: Converts `feat/eng-123-ui` to a clean folder name like `feat-eng-123-ui`.
-- **Auto-Branching**: If the branch doesn't exist, Yggdrasil creates it for you from a base branch.
-- **Remote Awareness**: Seamlessly base your work on `origin/main` or local refs.
+🌳 **First-class worktree workflow**
+Create, manage, and navigate Git worktrees as a primary workflow, not an afterthought.
+
+🧠 **Parallel development by default**
+Work on multiple branches at the same time, each in its own isolated environment.
+
+🤖 **AI-friendly isolation**
+One worktree per agent, per experiment, per idea. No shared state, no collisions.
+
+⚡ **Automatic bootstrapping**
+Run installs, submodules, and setup scripts automatically for each worktree.
+
+🚪 **Enter, exec, and exit with ease**
+Enter worktrees, execute commands, or run tasks without changing directories.
+
+📍 **Predictable structure**
+All managed worktrees live under `~/.yggtree`, keeping your repository clean.
+
+🧭 **Interactive or scriptable**
+Use the interactive UI or drive everything through commands and flags.
+
+---
+
+## 🧠 Parallel Development, Done Right
+
+```bash
+yggtree wt create feat/eng-2581-state-selection
+yggtree wt create fix/eng-2610-validation
+yggtree wt create chore/cleanup-api
+```
+
+Each command creates:
+
+* A clean folder
+* A dedicated branch
+* A bootstrapped environment
+
+No stash juggling.
+No branch confusion.
+No shared state accidents.
+
+---
+
+## 🤖 Built for AI‑Assisted Workflows
+
+Yggdrasil shines when paired with AI agents.
+
+Instead of running agents against the same directory, you can assign **one worktree per agent**.
+
+```bash
+yggtree wt create feat/ai-refactor-a --exec "cursor ."
+yggtree wt create feat/ai-refactor-b --exec "codex"
+```
+
+Each agent operates in its own realm:
 
-### 🌳 Batch Creation (`wt create-multi`)
-Need to spin up multiple features? Provide branch names separated by spaces, and Yggdrasil will provision all of them in one go.
+* Model A refactors architecture
+* Model B focuses on tests
+* Model C explores performance
 
-### 🚀 Custom Bootstrapping
-Configure your environment automatically using an `anvil-worktree.json` (also compatible with `.cursor/worktrees.json`) file in your project root.
+All in parallel. All reviewable. All isolated.
 
 ---
 
-## ⚙️ Configuration
+## ⚡ Bootstrapping & Configuration
+
+Yggdrasil automatically prepares each worktree.
+
+Resolution order:
+
+1. `yggtree-worktree.json` inside the worktree
+2. `yggtree-worktree.json` in the repo root
+3. `.cursor/worktrees.json`
+4. Fallback: `npm install` + submodules
 
-Yggdrasil looks for setup instructions in your project root:
+### Example configuration
 
 ```json
 {
@@ -65,26 +172,268 @@ Yggdrasil looks for setup instructions in your project root:
     "npm install",
     "git submodule sync --recursive",
     "git submodule update --init --recursive",
-    "npm run build",
-    "echo '🌳 The realm is ready!'"
+    "echo \"🌳 Realm ready\""
   ]
 }
 ```
 
 ---
 
-## 🛠️ Commands Reference
+## 🛠️ Command Reference
+
+### `yggtree`
+
+Open the interactive menu.
+
+---
+
+### `yggtree wt create [branch]`
+
+Create a worktree from a branch.
+
+Options:
+
+* `--base <ref>`
+* `--source local|remote`
+* `--no-bootstrap`
+* `--enter / --no-enter`
+* `--exec "<command>"`
+
+<details>
+<summary>Example</summary>
+
+```bash
+yggtree wt create feat/new-ui --base main --exec "cursor ."
+```
+
+</details>
+
+---
+
+### `yggtree wt create-multi`
+
+Create multiple worktrees at once.
+
+<details>
+<summary>Example</summary>
+
+```bash
+yggtree wt create-multi --base main
+```
+
+</details>
+
+---
+
+### `yggtree wt list`
+
+List all worktrees with state.
+
+Columns:
+
+* TYPE (MAIN / MANAGED)
+* STATE (clean / dirty)
+* BRANCH
+* PATH
+
+---
+
+### `yggtree wt enter [worktree]`
+
+Enter a worktree using a sub‑shell.
+
+* Uses your default shell
+* Type `exit` to return
+
+Optional:
+
+* `--exec "<command>"`
+
+<details>
+<summary>Example</summary>
+
+```bash
+yggtree wt enter feat/new-ui --exec "npm test"
+```
+
+</details>
+
+---
+
+### `yggtree wt exec [worktree] -- <command>`
+
+Run a command inside a worktree **without entering**.
+
+<details>
+<summary>Example</summary>
+
+```bash
+yggtree wt exec feat/new-ui -- npm test
+```
+
+</details>
+
+---
+
+### `yggtree wt path [worktree]`
+
+Print a `cd` command for a worktree.
+
+Useful for scripting and shell aliases.
+
+---
+
+### `yggtree wt bootstrap`
+
+Re‑run bootstrap commands for a worktree.
+
+---
+
+### `yggtree wt delete`
+
+Interactively delete managed worktrees.
+
+---
+
+### `yggtree wt prune`
+
+Clean up stale git worktree metadata.
+
+---
+
+## 🌱 When Should You Use Yggdrasil?
+
+Yggdrasil is ideal when:
+
+* You work on multiple tasks in parallel
+* You use AI agents for exploration
+* You want isolation without duplication
+* You value scripted, repeatable setups
+* `git checkout` no longer scales
+
+---
+
+## 📝 Practical Examples
+
+<details>
+<summary>Create a worktree and enter it immediately</summary>
+
+**Command:**
+
+```
+yggtree wt create feat/login-flow
+```
+
+**What happens:**
+
+* Creates a new branch if it doesn’t exist
+* Creates a dedicated worktree
+* Runs bootstrap if enabled
+* Drops you into a sub-shell inside the worktree
+
+</details>
+---
+
+<details>
+<summary>Create a worktree without bootstrap and without entering</summary>
+
+**Command:**
+
+```
+yggtree wt create feat/cleanup-api --no-bootstrap --no-enter
+```
+
+**When to use:**
+
+* You just want the folder ready
+* You’ll enter it later
+* You don’t want installs running automatically
+
+</details>
+---
+
+<details>
+<summary>Create a worktree and open it in your IDE</summary>
+
+**Command:**
+
+```
+yggtree wt create feat/ui-refactor --exec "cursor ."
+```
+
+Works with:
+
+* `cursor .`
+* `code .`
+* `codex`
+* Any custom command available in your shell
+
+</details>
+---
+
+<details>
+<summary>Execute a command inside an existing worktree (no shell)</summary>
+
+**Command:**
+
+```
+yggtree wt exec test -- npm test
+```
+
+**What this does:**
+
+* Runs the command inside the selected worktree
+* Does not enter a sub-shell
+* Ideal for CI-like checks, scripts, or quick validations
+
+</details>
+---
+
+<details>
+<summary>Enter a worktree and run a command before entering</summary>
+
+**Command:**
+
+```
+yggtree wt enter test --exec "codex"
+```
+
+**What happens:**
+
+* Executes the command inside the worktree
+* Then drops you into a sub-shell
+* Type `exit` to return to your original directory
+
+</details>
+---
+
+<details>
+<summary>Get the path to a worktree</summary>
+
+**Command:**
+
+```
+yggtree wt path test
+```
+
+**Output:**
+
+```
+cd ~/.yggtree/your-repo-name/test
+```
+
+Useful when you want to manually navigate or copy the path into scripts.
+
+</details>
+
+---
+
+## 🌍 Philosophy
+
+Branches are ideas.
+Worktrees are realities.
 
-| Command | Description |
-| :--- | :--- |
-| `yggtree` | Open the interactive main menu. |
-| `yggtree wt create` | Create a worktree by branch name (Recommended). |
-| `yggtree wt create-multi` | Create multiple worktrees in a single command. |
-| `yggtree wt create-slug` | Manually specify both folder name and branch ref. |
-| `yggtree wt list` | List all managed worktrees and their status. |
-| `yggtree wt delete` | Interactively select and remove a worktree. |
-| `yggtree wt bootstrap` | Re-run the setup commands for an existing worktree. |
-| `yggtree wt prune` | Clean up Git's internal data for worktrees. |
+Yggdrasil helps you grow many worlds and decide later which ones deserve to merge.
 
 ---
 

package/dist/commands/wt/bootstrap.js

@@ -17,10 +17,13 @@ export async function bootstrapCommand() {
             log.info('No managed worktrees found to bootstrap.');
             return;
         }
-        const choices = managedWts.map(wt => ({
-            name: `${chalk.bold(path.basename(wt.path))} (${chalk.dim(wt.branch || wt.HEAD)})`,
-            value: wt.path,
-        }));
+        const choices = managedWts.map(wt => {
+            const relative = path.relative(WORKTREES_ROOT, wt.path);
+            return {
+                name: `${chalk.bold(relative)} (${chalk.dim(wt.branch || wt.HEAD)})`,
+                value: wt.path,
+            };
+        });
         const { selectedPath } = await inquirer.prompt([
             {
                 type: 'list',
@@ -35,7 +38,7 @@ export async function bootstrapCommand() {
         log.success('Bootstrap completed!');
     }
     catch (error) {
-        log.error(error.message);
+        log.actionableError(error.message, 'yggtree wt bootstrap');
         process.exit(1);
     }
 }

package/dist/commands/wt/create-branch.js

@@ -1,7 +1,7 @@
 import chalk from 'chalk';
 import inquirer from 'inquirer';
 import path from 'path';
-import { getRepoRoot, verifyRef, fetchAll, getCurrentBranch } from '../../lib/git.js';
+import { getRepoRoot, getRepoName, verifyRef, fetchAll, getCurrentBranch } from '../../lib/git.js';
 import { runBootstrap } from '../../lib/config.js';
 import { WORKTREES_ROOT } from '../../lib/paths.js';
 import { log, ui, createSpinner } from '../../lib/ui.js';
@@ -41,37 +41,45 @@ export async function createCommandNew(options) {
                     { name: 'Local', value: 'local' },
                 ],
                 default: 'remote',
-                when: !options.base,
+                when: !options.base && !options.source,
             },
             {
                 type: 'confirm',
                 name: 'bootstrap',
                 message: 'Run bootstrap? (npm install + submodules)',
                 default: true,
-                when: options.bootstrap !== false,
+                when: options.bootstrap !== false && options.bootstrap !== true,
+            },
+            {
+                type: 'confirm',
+                name: 'shouldEnter',
+                message: 'Do you want to enter the new worktree now?',
+                default: true,
+                when: options.enter === undefined,
             },
+            {
+                type: 'input',
+                name: 'exec',
+                message: 'Command to run after creation (optional):',
+                default: options.exec,
+                when: options.exec === undefined,
+            }
         ]);
-        let shouldEnter = false;
-        if (!options.branch) {
-            const finalAnswer = await inquirer.prompt([{
-                    type: 'confirm',
-                    name: 'shouldEnter',
-                    message: 'Do you want to enter the new worktree now?',
-                    default: true
-                }]);
-            shouldEnter = finalAnswer.shouldEnter;
-        }
         const branchName = options.branch || answers.branch;
         let baseRef = options.base || answers.base;
+        const source = options.source || answers.source;
+        const shouldEnter = options.enter !== undefined ? options.enter : answers.shouldEnter;
+        const shouldBootstrap = options.bootstrap !== undefined ? options.bootstrap : answers.bootstrap;
+        const execCommandStr = options.exec || answers.exec;
         // Append origin/ if remote is selected and not already present
-        if (!options.base && answers.source === 'remote' && !baseRef.startsWith('origin/')) {
+        if (!options.base && source === 'remote' && !baseRef.startsWith('origin/')) {
             baseRef = `origin/${baseRef}`;
         }
-        const shouldBootstrap = options.bootstrap === false ? false : answers.bootstrap;
         // Convert branch name to slug (friendly folder name)
         // e.g. feat/eng-2222-new-button -> feat-eng-2222-new-button
         const slug = branchName.replace(/[\/\\]/g, '-').replace(/\s+/g, '-');
-        const wtPath = path.join(WORKTREES_ROOT, slug);
+        const repoName = await getRepoName();
+        const wtPath = path.join(WORKTREES_ROOT, repoName, slug);
         // 2. Validation
         if (!slug)
             throw new Error('Invalid name');
@@ -106,14 +114,38 @@ export async function createCommandNew(options) {
         }
         catch (e) {
             spinner.fail('Failed to create worktree.');
-            log.error(e.message);
+            const cmd = targetBranchExists
+                ? `git worktree add ${wtPath} ${branchName}`
+                : `git worktree add -b ${branchName} ${wtPath} ${baseRef}`;
+            log.actionableError(e.message, cmd, wtPath, [
+                'Check if the folder already exists: ls ' + wtPath,
+                'Check if the branch is already used: git worktree list',
+                'Try pruning stale worktrees: yggtree wt prune',
+                `Run manually: ${cmd}`
+            ]);
             return;
         }
-        // 4. Bootstrap
         if (shouldBootstrap) {
             await runBootstrap(wtPath, repoRoot);
         }
-        // 5. Final Output
+        // 5. Exec Command
+        if (execCommandStr && execCommandStr.trim()) {
+            log.info(`Executing: ${execCommandStr} in ${ui.path(wtPath)}`);
+            try {
+                await execa(execCommandStr, {
+                    cwd: wtPath,
+                    stdio: 'inherit',
+                    shell: true
+                });
+            }
+            catch (error) {
+                log.actionableError(error.message, execCommandStr, wtPath, [
+                    `cd ${wtPath} && ${execCommandStr}`,
+                    'Check your command syntax and environment variables'
+                ]);
+            }
+        }
+        // 6. Final Output
         log.success('Worktree ready!');
         if (shouldEnter) {
             log.info(`Spawning sub-shell in ${ui.path(wtPath)}...`);
@@ -132,7 +164,7 @@ export async function createCommandNew(options) {
         }
     }
     catch (error) {
-        log.error(error.message);
+        log.actionableError(error.message, 'yggtree wt create');
         process.exit(1);
     }
 }