yggtree 1.0.1 → 1.1.1

package/README.md

@@ -3,7 +3,9 @@
 [![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 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.
+**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.
 
 ---
 
@@ -11,84 +13,106 @@
 
 ### Installation
 
-You can run it directly without installing:
+Run without installing:
 
 ```bash
 npx yggtree
 ```
 
-Or install it globally for convenience:
+Or install globally:
 
 ```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
 ```
 
 ---
 
-## ✨ Key Features
+## 🧠 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.
 
-### 🌿 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.
+All managed worktrees live under:
 
-### 🌳 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.
+```
+~/.yggtree/<repo-name>/<worktree-slug>
+```
 
-### 🚀 Custom Bootstrapping
-Configure your environment automatically using an `anvil-worktree.json` (also compatible with `.cursor/worktrees.json`) file in your project root.
+This keeps your main repository clean while enabling true parallelism.
 
 ---
 
 ## 🤔 Why Yggdrasil Worktree?
 
-Git worktrees are incredibly powerful, but they are also **painfully manual** once you go beyond a single task.
+Git worktrees are powerful, but once you start doing **parallel work**, they become tedious to manage manually.
 
-Modern development isn’t sequential anymore. You’re constantly switching contexts, juggling experiments, fixes, reviews, and now **AI agents running in parallel**.
+Modern development looks like this:
 
-Yggdrasil exists to solve three modern problems at once:
+* Fixing a bug
+* Reviewing a PR
+* Prototyping a feature
+* Letting AI agents explore refactors
+* Running tests in isolation
 
-1. **Parallel work without context collision**
-2. **Fast environment setup per task**
-3. **Agent-friendly isolation for AI workflows**
+All at the same time.
 
-Instead of juggling branches, folders, and bootstrap scripts by hand, Yggdrasil gives you a repeatable, intentional workflow.
-Each worktree becomes its own **small realm** — isolated, focused, and safe to explore.
+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.
 
 ---
 
-## 🧠 Parallel Development, Done Right
+## ✨ Key Features
 
-Traditional branching assumes *sequential* work.
+🌳 **First-class worktree workflow**
+Create, manage, and navigate Git worktrees as a primary workflow, not an afterthought.
 
-Reality looks more like this:
+🧠 **Parallel development by default**
+Work on multiple branches at the same time, each in its own isolated environment.
 
-* You’re fixing a bug
-* Reviewing a PR
-* Prototyping a feature
-* Letting an AI agent explore refactors
-* Letting another agent generate tests
+🤖 **AI-friendly isolation**
+One worktree per agent, per experiment, per idea. No shared state, no collisions.
 
-All at the same time.
+⚡ **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.
 
-Yggdrasil lets each task live in its **own isolated worktree** — a separate realm where ideas can evolve without colliding.
+🧭 **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
@@ -96,74 +120,184 @@ yggtree wt create fix/eng-2610-validation
 yggtree wt create chore/cleanup-api
 ```
 
-Each command spins up:
+Each command creates:
 
 * A clean folder
 * A dedicated branch
-* A fully bootstrapped environment
+* A bootstrapped environment
 
-No context bleeding.
 No stash juggling.
-No “what branch am I on?” moments.
+No branch confusion.
+No shared state accidents.
 
 ---
 
-## 🤖 Built for AI-Assisted Workflows
-
-Yggdrasil shines when combined with AI agents.
+## 🤖 Built for AI‑Assisted Workflows
 
-Instead of running agents against the same working directory, you can:
+Yggdrasil shines when paired with AI agents.
 
-* Assign one worktree per agent
-* Let each agent explore independently
-* Compare results safely
-* Merge only what makes sense
-
-Example workflow:
+Instead of running agents against the same directory, you can assign **one worktree per agent**.
 
 ```bash
-# Prepare isolated worktrees
-yggtree wt create feat/ai-refactor-a
-yggtree wt create feat/ai-refactor-b
+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, free to experiment without side effects.
-
-This enables patterns like:
+Each agent operates in its own realm:
 
 * Model A refactors architecture
 * Model B focuses on tests
-* Model C explores performance improvements
+* Model C explores performance
 
-All in parallel.
-All reviewable.
-All under your control.
+All in parallel. All reviewable. All isolated.
 
 ---
 
-## ⚡ Zero-Friction Bootstrapping
+## ⚡ Bootstrapping & Configuration
+
+Yggdrasil automatically prepares each worktree.
 
-Every worktree can auto-configure itself.
+Resolution order:
 
-Yggdrasil reads your project’s setup file and prepares the realm immediately:
+1. `yggtree-worktree.json` inside the worktree
+2. `yggtree-worktree.json` in the repo root
+3. `.cursor/worktrees.json`
+4. Fallback: `npm install` + submodules
+
+### Example configuration
 
 ```json
 {
   "setup-worktree": [
     "npm install",
     "git submodule sync --recursive",
-    "git submodule update --init --recursive"
+    "git submodule update --init --recursive",
+    "echo \"🌳 Realm ready\""
   ]
 }
 ```
 
-That means:
+---
+
+## 🛠️ 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.
 
-* No manual installs
-* No forgotten submodules
-* No “works on main but not here” surprises
+Columns:
 
-You enter a worktree and it’s ready to work.
+* 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.
 
 ---
 
@@ -172,74 +306,136 @@ You enter a worktree and it’s ready to work.
 Yggdrasil is ideal when:
 
 * You work on multiple tasks in parallel
-* You use AI agents for exploration or execution
+* You use AI agents for exploration
 * You want isolation without duplication
-* You value repeatable, scripted setup
-* You’re tired of fighting your own repo
+* You value scripted, repeatable setups
+* `git checkout` no longer scales
 
-If your workflow has outgrown `git checkout`, Yggdrasil is the missing layer.
+---
+
+## 📝 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>
 ---
 
-## 🌍 Philosophy
+<details>
+<summary>Create a worktree without bootstrap and without entering</summary>
 
-Branches are ideas.
-Worktrees are realities.
+**Command:**
+
+```
+yggtree wt create feat/cleanup-api --no-bootstrap --no-enter
+```
 
-Yggdrasil helps you keep each idea grounded in its own world — until you decide which ones deserve to merge.
+**When to use:**
 
+* You just want the folder ready
+* You’ll enter it later
+* You don’t want installs running automatically
 
+</details>
 ---
 
-## ⚙️ Configuration
+<details>
+<summary>Create a worktree and open it in your IDE</summary>
 
-Yggdrasil looks for setup instructions in your project root:
+**Command:**
 
-```json
-{
-  "setup-worktree": [
-    "npm install",
-    "git submodule sync --recursive",
-    "git submodule update --init --recursive",
-    "npm run build",
-    "echo '🌳 The realm is ready!'"
-  ]
-}
+```
+yggtree wt create feat/ui-refactor --exec "cursor ."
 ```
 
+Works with:
+
+* `cursor .`
+* `code .`
+* `codex`
+* Any custom command available in your shell
+
+</details>
 ---
 
-## 🛠️ Commands Reference
+<details>
+<summary>Execute a command inside an existing worktree (no shell)</summary>
+
+**Command:**
 
-| 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. |
+```
+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>
 ---
 
-## 🛠️ Development
+<details>
+<summary>Enter a worktree and run a command before entering</summary>
 
-If you'd like to contribute or run the latest development version:
+**Command:**
 
-```bash
-# Clone the repository
-git clone https://github.com/leoreisdias/yggdrasil-cli.git
-cd yggdrasil-cli
+```
+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>
+---
 
-# Install dependencies and build
-npm install
-npm run build
+<details>
+<summary>Get the path to a worktree</summary>
+
+**Command:**
+
+```
+yggtree wt path test
+```
+
+**Output:**
 
-# Link the CLI locally
-npm link
 ```
+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.
+
+Yggdrasil helps you grow many worlds and decide later which ones deserve to merge.
+
+---
 
 ## 📄 License
 

package/dist/commands/wt/bootstrap.js

@@ -38,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, getRepoName, verifyRef, fetchAll, getCurrentBranch } from '../../lib/git.js';
+import { getRepoRoot, getRepoName, verifyRef, fetchAll, getCurrentBranch, ensureCorrectUpstream } 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,33 +41,40 @@ 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, '-');
@@ -103,18 +110,56 @@ export async function createCommandNew(options) {
             else {
                 await execa('git', ['worktree', 'add', '-b', branchName, wtPath, baseRef]);
             }
-            spinner.succeed('Worktree created.');
         }
         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
+        try {
+            // Strong Safety Mode: Ensure upstream is origin/<branchName> and publish
+            spinner.text = 'Safely publishing branch...';
+            await ensureCorrectUpstream(wtPath, branchName);
+            spinner.succeed('Worktree created and branch published.');
+        }
+        catch (e) {
+            spinner.fail('Worktree created, but branch publication failed.');
+            log.actionableError(e.message, 'git push -u origin HEAD', wtPath, [
+                `cd ${wtPath}`,
+                'Attempt to push manually: git push -u origin HEAD',
+                'Check if the remote branch already exists or if you have push permissions'
+            ]);
+            // We don't return here because the worktree IS created, we just failed to publish
+        }
         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)}...`);
@@ -133,7 +178,7 @@ export async function createCommandNew(options) {
         }
     }
     catch (error) {
-        log.error(error.message);
+        log.actionableError(error.message, 'yggtree wt create');
         process.exit(1);
     }
 }