yggtree 1.0.0 → 1.0.1

package/README.md

@@ -1,5 +1,8 @@
 # 🌳 Yggdrasil Worktree (yggtree)
 
+[![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.
 
 ---
@@ -8,17 +11,16 @@
 
 ### Installation
 
+You can run it directly 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 it globally for convenience:
 
-# Link the CLI globally
-npm link
+```bash
+npm install -g yggtree
 ```
 
 ### Usage
@@ -53,6 +55,140 @@ Need to spin up multiple features? Provide branch names separated by spaces, and
 ### 🚀 Custom Bootstrapping
 Configure your environment automatically using an `anvil-worktree.json` (also compatible with `.cursor/worktrees.json`) file in your project root.
 
+---
+
+## 🤔 Why Yggdrasil Worktree?
+
+Git worktrees are incredibly powerful, but they are also **painfully manual** once you go beyond a single task.
+
+Modern development isn’t sequential anymore. You’re constantly switching contexts, juggling experiments, fixes, reviews, and now **AI agents running in parallel**.
+
+Yggdrasil exists to solve three modern problems at once:
+
+1. **Parallel work without context collision**
+2. **Fast environment setup per task**
+3. **Agent-friendly isolation for AI workflows**
+
+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.
+
+---
+
+## 🧠 Parallel Development, Done Right
+
+Traditional branching assumes *sequential* work.
+
+Reality looks more like this:
+
+* You’re fixing a bug
+* Reviewing a PR
+* Prototyping a feature
+* Letting an AI agent explore refactors
+* Letting another agent generate tests
+
+All at the same time.
+
+Yggdrasil lets each task live in its **own isolated worktree** — a separate realm where ideas can evolve without colliding.
+
+```bash
+yggtree wt create feat/eng-2581-state-selection
+yggtree wt create fix/eng-2610-validation
+yggtree wt create chore/cleanup-api
+```
+
+Each command spins up:
+
+* A clean folder
+* A dedicated branch
+* A fully bootstrapped environment
+
+No context bleeding.
+No stash juggling.
+No “what branch am I on?” moments.
+
+---
+
+## 🤖 Built for AI-Assisted Workflows
+
+Yggdrasil shines when combined with AI agents.
+
+Instead of running agents against the same working directory, you can:
+
+* Assign one worktree per agent
+* Let each agent explore independently
+* Compare results safely
+* Merge only what makes sense
+
+Example workflow:
+
+```bash
+# Prepare isolated worktrees
+yggtree wt create feat/ai-refactor-a
+yggtree wt create feat/ai-refactor-b
+```
+
+Each agent operates in its own realm, free to experiment without side effects.
+
+This enables patterns like:
+
+* Model A refactors architecture
+* Model B focuses on tests
+* Model C explores performance improvements
+
+All in parallel.
+All reviewable.
+All under your control.
+
+---
+
+## ⚡ Zero-Friction Bootstrapping
+
+Every worktree can auto-configure itself.
+
+Yggdrasil reads your project’s setup file and prepares the realm immediately:
+
+```json
+{
+  "setup-worktree": [
+    "npm install",
+    "git submodule sync --recursive",
+    "git submodule update --init --recursive"
+  ]
+}
+```
+
+That means:
+
+* No manual installs
+* No forgotten submodules
+* No “works on main but not here” surprises
+
+You enter a worktree and it’s ready to work.
+
+---
+
+## 🌱 When Should You Use Yggdrasil?
+
+Yggdrasil is ideal when:
+
+* You work on multiple tasks in parallel
+* You use AI agents for exploration or execution
+* You want isolation without duplication
+* You value repeatable, scripted setup
+* You’re tired of fighting your own repo
+
+If your workflow has outgrown `git checkout`, Yggdrasil is the missing layer.
+
+---
+
+## 🌍 Philosophy
+
+Branches are ideas.
+Worktrees are realities.
+
+Yggdrasil helps you keep each idea grounded in its own world — until you decide which ones deserve to merge.
+
+
 ---
 
 ## ⚙️ Configuration
@@ -88,6 +224,23 @@ Yggdrasil looks for setup instructions in your project root:
 
 ---
 
+## 🛠️ Development
+
+If you'd like to contribute or run the latest development version:
+
+```bash
+# Clone the repository
+git clone https://github.com/leoreisdias/yggdrasil-cli.git
+cd yggdrasil-cli
+
+# Install dependencies and build
+npm install
+npm run build
+
+# Link the CLI locally
+npm link
+```
+
 ## 📄 License
 
 MIT License.

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',

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';
@@ -71,7 +71,8 @@ export async function createCommandNew(options) {
         // 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');

package/dist/commands/wt/create-multi.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';
@@ -66,9 +66,10 @@ export async function createCommandMulti(options) {
         spinner.succeed(`Base ref ${chalk.cyan(baseRef)} verified.`);
         const createdWorktrees = [];
         // 3. Execution for each branch
+        const repoName = await getRepoName();
         for (const branchName of branchNames) {
             const slug = branchName.replace(/[\/\\]/g, '-').replace(/\s+/g, '-');
-            const wtPath = path.join(WORKTREES_ROOT, slug);
+            const wtPath = path.join(WORKTREES_ROOT, repoName, slug);
             log.header(`Processing: ${branchName}`);
             const wtSpinner = createSpinner(`Creating worktree at ${ui.path(wtPath)}...`).start();
             try {

package/dist/commands/wt/create.js

@@ -1,7 +1,7 @@
 import chalk from 'chalk';
 import inquirer from 'inquirer';
 import path from 'path';
-import { getRepoRoot, verifyRef, createWorktree, fetchAll, getCurrentBranch } from '../../lib/git.js';
+import { getRepoRoot, getRepoName, verifyRef, createWorktree, 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';
@@ -68,7 +68,8 @@ export async function createCommand(options) {
         }
         const shouldBootstrap = options.bootstrap === false ? false : answers.bootstrap;
         const slug = name.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');

package/dist/commands/wt/delete.js

@@ -14,10 +14,13 @@ export async function deleteCommand() {
             log.info('No managed worktrees found to delete.');
             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',
@@ -26,7 +29,7 @@ export async function deleteCommand() {
                 choices: choices,
             },
         ]);
-        const worktreeName = path.basename(selectedPath);
+        const worktreeName = path.relative(WORKTREES_ROOT, selectedPath);
         const { confirm } = await inquirer.prompt([
             {
                 type: 'input',

package/dist/commands/wt/list.js

@@ -1,4 +1,5 @@
 import chalk from 'chalk';
+import path from 'path';
 import { listWorktrees, getRepoRoot } from '../../lib/git.js';
 import { WORKTREES_ROOT } from '../../lib/paths.js';
 import { log } from '../../lib/ui.js';
@@ -19,7 +20,10 @@ export async function listCommand() {
             const isMain = !isManaged; // Simplification: assume main repo is not in managed dir
             const type = isManaged ? chalk.green('MANAGED') : chalk.blue('MAIN   ');
             const branchName = wt.branch || wt.HEAD || 'detached';
-            const displayPath = wt.path.replace(process.env.HOME || '', '~');
+            let displayPath = wt.path.replace(process.env.HOME || '', '~');
+            if (isManaged) {
+                displayPath = path.relative(WORKTREES_ROOT, wt.path);
+            }
             const colorPath = isManaged ? chalk.cyan(displayPath) : chalk.dim(displayPath);
             console.log(`  ${type}  ${chalk.yellow(branchName.padEnd(18))} ${colorPath}`);
         }

package/dist/lib/git.js

@@ -10,6 +10,10 @@ export async function getRepoRoot() {
         throw new Error('Not a git repository');
     }
 }
+export async function getRepoName() {
+    const root = await getRepoRoot();
+    return path.basename(root);
+}
 export async function getCurrentBranch() {
     try {
         const { stdout } = await execa('git', ['rev-parse', '--abbrev-ref', 'HEAD']);

package/dist/lib/paths.js

@@ -1,4 +1,4 @@
 import os from 'os';
 import path from 'path';
-export const ANVIL_ROOT = path.join(os.homedir(), '.yggdrasil');
-export const WORKTREES_ROOT = path.join(ANVIL_ROOT, 'worktrees');
+export const YGG_ROOT = path.join(os.homedir(), '.yggtree');
+export const WORKTREES_ROOT = YGG_ROOT;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "yggtree",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "Interactive CLI for managing git worktrees and configs",
   "main": "dist/index.js",
   "type": "module",