yggtree 1.3.0 → 1.4.1

package/README.md

@@ -162,7 +162,7 @@ Sometimes you don't want to "commit to a branch" yet. You just want to try somet
 
 **Sandboxes** are temporary, local-only worktrees designed for this:
 
-1.  **Create**: `yggtree wt create-sandbox` (creates `branch_qes2`).
+1.  **Create**: `yggtree wt create-sandbox` (creates something like `sandbox-a3f2_feature-branch`).
 2.  **Experiment**: Change files, run tests, try that risky refactor.
 3.  **Apply**: `yggtree wt apply` to "push" those file changes back to your origin directory.
 4.  **Unapply**: Don't like it? `yggtree wt unapply` restores your origin to exactly how it was before.
@@ -177,10 +177,13 @@ 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
+1. `.yggtree/worktree-setup.json` in the repo root
+2. `yggtree-worktree.json` in the repo root (legacy fallback)
+3. `.cursor/worktrees.json` in the repo root (legacy fallback)
+4. `.yggtree/worktree-setup.json` inside the worktree (per-worktree fallback)
+5. `yggtree-worktree.json` inside the worktree (legacy fallback)
+6. `.cursor/worktrees.json` inside the worktree (legacy fallback)
+7. Fallback: `npm install` + submodules
 
 ### Example configuration
 
@@ -211,12 +214,18 @@ Create a worktree from a branch.
 
 Options:
 
+* `-b, --branch <name>`
 * `--base <ref>`
 * `--source local|remote`
 * `--no-bootstrap`
 * `--enter / --no-enter`
 * `--exec "<command>"`
 
+Interactive flow:
+
+* Instead of asking for a free-form `exec` command, yggtree now asks if you want to open a tool after creation (IDE or agent CLI).
+* `--exec` remains available as an advanced explicit override.
+
 <details>
 <summary>Example</summary>
 
@@ -228,17 +237,59 @@ yggtree wt create feat/new-ui --base main --exec "cursor ."
 
 ---
 
+### `yggtree wt worktree-checkout [name] [ref]`
+
+Create a checkout-style worktree from an existing branch.
+
+Behavior:
+
+* Prompts a searchable branch picker (type to filter in real time).
+* Attaches the new worktree directly to the selected branch (checkout-style).
+* If you select a remote-only branch (`origin/*`), yggtree creates the local branch in the new worktree automatically.
+* If that branch already has an active yggtree-managed worktree, yggtree falls back to entering that worktree instead of creating a duplicate.
+
+Options:
+
+* `-n, --name <slug>`
+* `-r, --ref <ref>`: skip picker and use a specific branch (`feature/x` or `origin/feature/x`)
+* `--no-bootstrap`
+* `--enter / --no-enter`
+* `--exec "<command>"`
+
+Interactive flow:
+
+* Instead of asking for a free-form `exec` command, yggtree now asks if you want to open a tool after creation (IDE or agent CLI).
+* `--exec` remains available as an advanced explicit override.
+
+<details>
+<summary>Example</summary>
+
+```bash
+yggtree wt worktree-checkout -n hotfix-auth -r main --no-enter
+```
+
+</details>
+
+---
+
 ### `yggtree wt create-sandbox`
 
 Create a temporary sandbox from your current local branch.
 
 Options:
 
+*   `-n, --name <name>`: Optional sandbox name (auto-generated if omitted).
 *   `--carry / --no-carry`: Bring uncommitted changes (staged/unstaged/untracked) with you.
 *   `--no-bootstrap`
 *   `--enter / --no-enter`
 *   `--exec "<command>"`
 
+Interactive flow:
+
+* Prompts for an optional sandbox name (leave empty to auto-generate one from current branch).
+* Instead of asking for a free-form `exec` command, yggtree now asks if you want to open a tool after creation (IDE or agent CLI).
+* `--exec` remains available as an advanced explicit override.
+
 ---
 
 ### `yggtree wt apply`
@@ -261,6 +312,12 @@ Undo a previous `apply` operation.
 
 Create multiple worktrees at once.
 
+Options:
+
+* `--base <ref>`
+* `--source local|remote`
+* `--no-bootstrap`
+
 <details>
 <summary>Example</summary>
 
@@ -274,14 +331,21 @@ yggtree wt create-multi --base main
 
 ### `yggtree wt list`
 
-List all worktrees with state.
+List all repo-linked worktrees with state.
 
 Columns:
 
-* TYPE (MAIN / MANAGED)
+* TYPE (`MAIN`, `MANAGED`, `LINKED`, `SANDBOX`)
 * STATE (clean / dirty)
+* LAST ACTIVE
 * BRANCH
-* PATH
+
+Notes:
+
+* Entries are grouped by `TYPE`.
+* `SANDBOX` and `MANAGED` are worktrees inside `~/.yggtree`.
+* External worktrees are labeled `LINKED`.
+* Use `--open` to switch this flow into "pick and open in tool" mode.
 
 ---
 
@@ -307,6 +371,35 @@ yggtree wt enter feat/new-ui --exec "npm test"
 
 ---
 
+### `yggtree wt open [worktree]`
+
+Open a worktree in an IDE or agent CLI.
+
+Behavior:
+
+* If `[worktree]` is omitted, you can pick from the worktree list with type-to-filter search.
+* Detects available tool commands in your `PATH` (for example: IDEs like `cursor`, `code`, `zed`; agents like `claude`, `codex`, `gemini`, `opencode`).
+* Lets you choose one interactively, or pass `--tool`.
+* If an agent CLI is selected, yggtree opens a sub-shell and launches it there.
+
+Options:
+
+* `--tool <command>`
+
+<details>
+<summary>Examples</summary>
+
+```bash
+yggtree wt open
+yggtree wt open feat/new-ui --tool cursor
+yggtree wt open feat/new-ui --tool claude
+yggtree wt list --open
+```
+
+</details>
+
+---
+
 ### `yggtree wt exec [worktree] -- <command>`
 
 Run a command inside a worktree **without entering**.
@@ -338,7 +431,18 @@ Re‑run bootstrap commands for a worktree.
 
 ### `yggtree wt delete`
 
-Interactively delete managed worktrees.
+Interactively delete worktrees.
+
+Behavior:
+
+* Default flow targets managed worktrees.
+* In interactive mode, yggtree asks whether to include external linked worktrees.
+* In direct CLI usage, `--all` includes external linked worktrees (main/current are still excluded for safety).
+* The delete selector shows 6 items per page.
+
+Optional:
+
+* `--all` includes linked worktrees outside `~/.yggtree` (main/current worktree is excluded for safety)
 
 ---
 
@@ -488,7 +592,7 @@ yggtree wt create-sandbox --carry
 **Scenario:**
 
 1.  You have 5 files changed in your main repo but aren't sure about the direction.
-2.  Run `create-sandbox --carry` to move those changes into an isolated `current-branch_a1b2` folder.
+2.  Run `create-sandbox --carry` to move those changes into an isolated `sandbox-a3f2_feature-branch` folder.
 3.  Experiment freely.
 4.  If it works: `yggtree wt apply`.
 5.  If it fails: Just delete the sandbox or `unapply`.

package/dist/commands/bifrost.js

@@ -0,0 +1,187 @@
+import chalk from 'chalk';
+import gradient from 'gradient-string';
+import figlet from 'figlet';
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+export async function bifrostCommand() {
+    console.clear();
+    process.stdout.write('\x1b[?25l'); // Hide cursor
+    // Animated clouds blowing across the sky
+    const cloudArt = '         ☁️         ☁️                 ☁️     ';
+    const skyWidth = 40;
+    console.log(chalk.dim('\n  The sky darkens...\n'));
+    // Print a placeholder for the animated line so we can cursor-up over it
+    console.log('');
+    for (let i = 0; i < 20; i++) {
+        // Shift the clouds by slicing from an ever-changing offset of a repeated string
+        const offset = i % cloudArt.length;
+        const visibleClouds = (cloudArt.repeat(3)).substring(offset, offset + skyWidth);
+        process.stdout.write('\x1b[1A'); // Move cursor up 1 line
+        process.stdout.write('\r  ' + chalk.gray(visibleClouds) + '\n');
+        await sleep(100);
+    }
+    console.clear();
+    // 6-Frame Cutscene: The Bifrost Opening (Bigger & Stronger)
+    const bifrostFrames = [
+        // Frame 1: Empty sky
+        chalk.gray(`
+               ☁️                               ☁️     
+                                                       
+                                                       
+                                                       
+                                                       
+                                                       
+                                                       
+                                                       
+                                                       
+                                                       
+                                                       
+        `),
+        // Frame 2: Small beam of light
+        chalk.cyan(`
+               ☁️               |               ☁️     
+                                |                      
+                                |                      
+                                |                      
+                                |                      
+                                |                      
+                                |                      
+                                |                      
+                                |                      
+                                |                      
+                                v                      
+        `),
+        // Frame 3: Wider beam reaching the ground
+        gradient.rainbow(`
+               ☁️              |||              ☁️     
+                               |||                     
+                               |||                     
+                               |||                     
+                               |||                     
+                               |||                     
+                               |||                     
+                               |||                     
+                               |||                     
+                               |||                     
+                            ---------                  
+        `),
+        // Frame 4: Giant beam hitting the ground
+        gradient.rainbow(`
+               ☁️          |||||||||||          ☁️     
+                           |||||||||||                 
+                           |||||||||||                 
+                           |||||||||||                 
+                           |||||||||||                 
+                           |||||||||||                 
+                           |||||||||||                 
+                           |||||||||||                 
+                           |||||||||||                 
+                           |||||||||||                 
+                        -----------------              
+        `),
+        // Frame 5: MASSIVE beam
+        gradient.rainbow(`
+               ☁️     |||||||||||||||||||||     ☁️     
+                      |||||||||||||||||||||            
+                      |||||||||||||||||||||            
+                      |||||||||||||||||||||            
+                      |||||||||||||||||||||            
+                      |||||||||||||||||||||            
+                      |||||||||||||||||||||            
+                      |||||||||||||||||||||            
+                      |||||||||||||||||||||            
+                      |||||||||||||||||||||            
+                   ---------------------------         
+        `),
+        // Frame 6: Silhouette of Thor in the massive beam
+        gradient.rainbow(`
+               ☁️     |||||||||||||||||||||     ☁️     
+                      |||||||||||||||||||||            
+                      |||||||||||||||||||||            
+                      |||||||||||||||||||||            
+                      |||||||||||||||||||||            
+                      |||||||||||||||||||||            
+                      |||||||||||||||||||||            
+                      |||||||||||||||||||||            
+                      |||||||||||||||||||||            
+                      ||||||||| 𖨆 |||||||||            
+                   ---------------------------         
+        `)
+    ];
+    // Give the user more time to digest each step of the expanding Bifrost
+    const frameDelays = [400, 300, 300, 300, 400, 1000];
+    for (let i = 0; i < bifrostFrames.length; i++) {
+        console.clear();
+        console.log(chalk.bold.italic('\n  Opening the Bifrost...\n'));
+        console.log(bifrostFrames[i]);
+        await sleep(frameDelays[i]); // Custom timing per frame for better impact
+    }
+    await sleep(200);
+    // Lightning Flash
+    // We use standard ANSI terminal invert colors to simulate lightning
+    process.stdout.write('\x1b[?5h'); // Inverse Video On
+    console.log(chalk.yellow.bold('\n\n                ⚡  \n          ⚡        ⚡\n                ⚡\n\n'));
+    await sleep(150);
+    process.stdout.write('\x1b[?5l'); // Inverse Video Off
+    console.clear();
+    const frames = [
+        chalk.gray.bold(`
+            ___________
+           |           |
+           |  MJÖLNIR  |
+           |___________|
+                | |
+                | |
+               _|_|_
+        `),
+        chalk.gray.bold(`
+     
+             _____________
+      ======|   MJÖLNIR   |
+             -------------
+     
+        `),
+        chalk.gray.bold(`
+               _|_|_
+                | |
+                | |
+            ___________
+           |           |
+           |  MJÖLNIR  |
+           |___________|
+        `),
+        chalk.gray.bold(`
+     
+             _____________
+            |   MJÖLNIR   |======
+             -------------
+     
+        `)
+    ];
+    // Let the hammer fall down and spin from right to left
+    const animationSteps = 15;
+    for (let i = 0; i < animationSteps; i++) {
+        console.clear();
+        console.log('\x1b[?25l'); // Hide cursor
+        const yPadding = '\n'.repeat(i);
+        const xPaddingLength = Math.max(0, (animationSteps - i) * 6);
+        const xPadding = ' '.repeat(xPaddingLength);
+        const frame = frames[i % frames.length];
+        const paddedFrame = frame.split('\n').map(line => xPadding + line).join('\n');
+        console.log(yPadding + paddedFrame);
+        await sleep(70);
+    }
+    // Final pose upright!
+    console.clear();
+    const finalYPadding = '\n'.repeat(animationSteps);
+    console.log(finalYPadding + frames[0]);
+    await sleep(200);
+    // THOOM text
+    const thoomArt = figlet.textSync('THOOM!', {
+        font: 'Standard',
+        horizontalLayout: 'default',
+        verticalLayout: 'default',
+    });
+    console.log(gradient.fruit(thoomArt));
+    console.log(chalk.yellow.bold('\n  ⚡ The son of Odin has entered the realm ⚡ \n'));
+    console.log('\x1b[?25h'); // Show cursor
+}

package/dist/commands/thor.js

@@ -0,0 +1,39 @@
+import chalk from 'chalk';
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+// A collection of legendary quotes (mix of Poetic Edda and developer humor)
+const quotes = [
+    "I say thee NAY to unhandled promises!",
+    "Even the All-Father tests in production sometimes.",
+    "A wise developer commits early, and commits often.",
+    "Bugs are just frost giants hiding in your codebase.",
+    "May your builds be as swift as Mjölnir's flight.",
+    "Do not trust a tree without deep roots, nor code without tests.",
+    "Yggdrasil connects all realms; git connects all branches.",
+    "A clean working tree is acceptable to the gods.",
+    "The Bifrost is open, but did you remember to push?",
+    "Verily, thou shalt not force push to main."
+];
+export async function thorCommand() {
+    console.clear();
+    const randomQuote = quotes[Math.floor(Math.random() * quotes.length)];
+    // Static Thor ASCII art
+    const thorArt = `
+      / \\
+     /___\\
+     (o_o)   "Hello from Asgard!"
+    /|||||\\ 
+   | |   | |
+    \\=====//
+      | |
+      | |
+     _|_|_
+    `;
+    console.log(chalk.gray.bold(thorArt));
+    // Typewriter effect for the quote
+    process.stdout.write(chalk.cyan('Thor says: '));
+    for (let i = 0; i < randomQuote.length; i++) {
+        process.stdout.write(chalk.bold.yellow(randomQuote.charAt(i)));
+        await sleep(30); // Typing speed
+    }
+    console.log('\n');
+}

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

@@ -5,6 +5,7 @@ import { getRepoRoot, getRepoName, verifyRef, fetchAll, getCurrentBranch, ensure
 import { runBootstrap } from '../../lib/config.js';
 import { WORKTREES_ROOT } from '../../lib/paths.js';
 import { log, ui, createSpinner } from '../../lib/ui.js';
+import { buildAgentExecCommand, detectInstalledOpenTools, isAgentTool, launchOpenTool, promptOpenToolSelection, } from './open.js';
 import { execa } from 'execa';
 import { spawn } from 'child_process';
 import fs from 'fs-extra';
@@ -58,19 +59,29 @@ export async function createCommandNew(options) {
                 when: options.enter === undefined,
             },
             {
-                type: 'input',
-                name: 'exec',
-                message: 'Command to run after creation (optional):',
-                default: options.exec,
+                type: 'confirm',
+                name: 'shouldOpenTool',
+                message: 'Open a tool after creation? (IDE or agent CLI)',
+                default: false,
                 when: options.exec === undefined,
-            }
+            },
         ]);
         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;
+        let selectedTool;
+        if (options.exec === undefined && answers.shouldOpenTool) {
+            const installedTools = await detectInstalledOpenTools();
+            if (installedTools.length === 0) {
+                log.warning('No IDE/agent tool detected in PATH. Skipping open step.');
+            }
+            else {
+                selectedTool = await promptOpenToolSelection(installedTools, 'Select tool to open:');
+            }
+        }
+        const execCommandStr = options.exec || (selectedTool && isAgentTool(selectedTool) ? buildAgentExecCommand(selectedTool) : undefined);
         // Append origin/ if remote is selected and not already present
         if (!options.base && source === 'remote' && !baseRef.startsWith('origin/')) {
             baseRef = `origin/${baseRef}`;
@@ -159,6 +170,15 @@ export async function createCommandNew(options) {
                 ]);
             }
         }
+        if (selectedTool && !isAgentTool(selectedTool)) {
+            try {
+                log.info(`Opening ${ui.path(wtPath)} in ${chalk.cyan(selectedTool.name)}...`);
+                await launchOpenTool(selectedTool, wtPath);
+            }
+            catch (error) {
+                log.warning(`Could not open ${selectedTool.name}: ${error.message}`);
+            }
+        }
         // 6. Final Output
         log.success('Worktree ready!');
         if (shouldEnter) {

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

@@ -5,7 +5,8 @@ import { getRepoRoot, getRepoName, 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';
-import { generateSandboxName, writeSandboxMeta } from '../../lib/sandbox.js';
+import { generateSandboxName, normalizeSandboxName, writeSandboxMeta } from '../../lib/sandbox.js';
+import { buildAgentExecCommand, detectInstalledOpenTools, isAgentTool, launchOpenTool, promptOpenToolSelection, } from './open.js';
 import { execa } from 'execa';
 import { spawn } from 'child_process';
 import fs from 'fs-extra';
@@ -20,11 +21,32 @@ export async function createSandboxCommand(options = {}) {
             return;
         }
         log.info(`Current branch: ${chalk.cyan(currentBranch)}`);
-        // 2. Generate random sandbox name
-        const sandboxName = generateSandboxName(currentBranch);
-        log.info(`Sandbox name: ${chalk.yellow(sandboxName)}`);
+        // 2. Build default + optional custom name validation
+        const generatedSandboxName = generateSandboxName(currentBranch);
+        const validateSandboxName = async (input) => {
+            if (!input.trim())
+                return true;
+            const normalized = normalizeSandboxName(input);
+            if (!normalized) {
+                return 'Please provide at least one valid character.';
+            }
+            try {
+                await execa('git', ['check-ref-format', '--branch', normalized], { cwd: repoRoot });
+                return true;
+            }
+            catch {
+                return 'Sandbox name is not a valid git branch name.';
+            }
+        };
         // 3. Gather remaining inputs
         const answers = await inquirer.prompt([
+            {
+                type: 'input',
+                name: 'name',
+                message: `Sandbox name (optional, leave empty for auto: ${generatedSandboxName}):`,
+                when: options.name === undefined,
+                validate: validateSandboxName,
+            },
             {
                 type: 'confirm',
                 name: 'carry',
@@ -47,17 +69,39 @@ export async function createSandboxCommand(options = {}) {
                 when: options.enter === undefined,
             },
             {
-                type: 'input',
-                name: 'exec',
-                message: 'Command to run after creation (optional):',
-                default: options.exec,
+                type: 'confirm',
+                name: 'shouldOpenTool',
+                message: 'Open a tool after creation? (IDE or agent CLI)',
+                default: false,
                 when: options.exec === undefined,
-            }
+            },
         ]);
+        const requestedSandboxName = options.name !== undefined ? options.name : answers.name || '';
+        const nameValidation = await validateSandboxName(requestedSandboxName);
+        if (nameValidation !== true) {
+            log.error(nameValidation);
+            return;
+        }
+        const normalizedCustomName = normalizeSandboxName(requestedSandboxName);
+        const sandboxName = normalizedCustomName || generatedSandboxName;
+        if (requestedSandboxName.trim() && normalizedCustomName !== requestedSandboxName.trim()) {
+            log.dim(`Normalized sandbox name: ${chalk.yellow(sandboxName)}`);
+        }
+        log.info(`Sandbox name: ${chalk.yellow(sandboxName)}`);
         const shouldCarry = options.carry !== undefined ? options.carry : answers.carry;
         const shouldEnter = options.enter !== undefined ? options.enter : answers.shouldEnter;
         const shouldBootstrap = options.bootstrap !== undefined ? options.bootstrap : answers.bootstrap;
-        const execCommandStr = options.exec || answers.exec;
+        let selectedTool;
+        if (options.exec === undefined && answers.shouldOpenTool) {
+            const installedTools = await detectInstalledOpenTools();
+            if (installedTools.length === 0) {
+                log.warning('No IDE/agent tool detected in PATH. Skipping open step.');
+            }
+            else {
+                selectedTool = await promptOpenToolSelection(installedTools, 'Select tool to open:');
+            }
+        }
+        const execCommandStr = options.exec || (selectedTool && isAgentTool(selectedTool) ? buildAgentExecCommand(selectedTool) : undefined);
         // 4. Detect uncommitted changes before creating worktree
         let changedFiles = [];
         let submodulePaths = [];
@@ -159,6 +203,15 @@ export async function createSandboxCommand(options = {}) {
                 ]);
             }
         }
+        if (selectedTool && !isAgentTool(selectedTool)) {
+            try {
+                log.info(`Opening ${ui.path(wtPath)} in ${chalk.cyan(selectedTool.name)}...`);
+                await launchOpenTool(selectedTool, wtPath);
+            }
+            catch (error) {
+                log.warning(`Could not open ${selectedTool.name}: ${error.message}`);
+            }
+        }
         // 10. Final output
         log.success('Sandbox ready!');
         log.info(`Use ${chalk.cyan('yggtree wt apply')} to apply changes to origin.`);