yggtree 1.2.1 → 1.4.0

package/README.md

@@ -118,8 +118,8 @@ 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 feat/city-selection
+yggtree wt create fix/validation
 yggtree wt create chore/cleanup-api
 ```
 
@@ -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)
 
 ---
 
@@ -373,11 +477,12 @@ yggtree wt create feat/login-flow
 
 **What happens:**
 
-* Creates a new branch if it doesn’t exist
+* Creates a new branch if it doesn’t exist (without inheriting base tracking), then publishes it to `origin` when possible
 * Creates a dedicated worktree
 * Runs bootstrap if enabled
 * Drops you into a sub-shell inside the worktree
 
+
 </details>
 ---
 
@@ -487,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/wt/apply.js

@@ -4,7 +4,7 @@ import path from 'path';
 import fs from 'fs-extra';
 import { execa } from 'execa';
 import { log, ui, createSpinner } from '../../lib/ui.js';
-import { findSandboxRoot, readSandboxMeta, writeSandboxMeta, SANDBOX_META_FILE } from '../../lib/sandbox.js';
+import { findSandboxRoot, readSandboxMeta, writeSandboxMeta, YGGTREE_DIR } from '../../lib/sandbox.js';
 export async function applyCommand() {
     try {
         const cwd = process.cwd();
@@ -35,8 +35,12 @@ export async function applyCommand() {
                 ...stagedFiles.split('\n').filter(Boolean),
                 ...untrackedFiles.split('\n').filter(Boolean)
             ]);
-            // Exclude internal sandbox metadata file
-            allChanges.delete(SANDBOX_META_FILE);
+            // Exclude internal .yggtree/ directory (config, sandbox metadata, etc.)
+            for (const file of allChanges) {
+                if (file.startsWith(`${YGGTREE_DIR}/`)) {
+                    allChanges.delete(file);
+                }
+            }
             changedFiles = [...allChanges];
         }
         catch (e) {

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

@@ -1,10 +1,11 @@
 import chalk from 'chalk';
 import inquirer from 'inquirer';
 import path from 'path';
-import { getRepoRoot, getRepoName, verifyRef, fetchAll, getCurrentBranch, ensureCorrectUpstream } from '../../lib/git.js';
+import { getRepoRoot, getRepoName, verifyRef, fetchAll, getCurrentBranch, ensureCorrectUpstream, publishBranch } 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 { buildAgentExecCommand, detectInstalledOpenTools, isAgentTool, launchOpenTool, promptOpenToolSelection, } from './open.js';
 import { execa } from 'execa';
 import { spawn } from 'child_process';
 import fs from 'fs-extra';
@@ -58,25 +59,35 @@ 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}`;
         }
         // Convert branch name to slug (friendly folder name)
-        // e.g. feat/eng-2222-new-button -> feat-eng-2222-new-button
+        // e.g. feat/new-button -> feat-new-button
         const slug = branchName.replace(/[\/\\]/g, '-').replace(/\s+/g, '-');
         const repoName = await getRepoName();
         const wtPath = path.join(WORKTREES_ROOT, repoName, slug);
@@ -98,24 +109,23 @@ export async function createCommandNew(options) {
         spinner.text = `Creating worktree at ${ui.path(wtPath)}...`;
         // Check if target branch already exists
         const targetBranchExists = await verifyRef(branchName);
-        // If branch doesn't exist, we create it from base
-        // If it does exist, we just check it out
-        const createBranchFlag = targetBranchExists ? '' : `-b ${branchName}`;
         try {
             await fs.ensureDir(path.dirname(wtPath));
-            // slightly different logic for creating new branch vs existing
             if (targetBranchExists) {
+                // Branch exists — just attach the worktree
                 await execa('git', ['worktree', 'add', wtPath, branchName]);
             }
             else {
-                await execa('git', ['worktree', 'add', '-b', branchName, wtPath, baseRef]);
+                // Create branch WITHOUT tracking the base, then attach worktree
+                await execa('git', ['branch', '--no-track', branchName, baseRef]);
+                await execa('git', ['worktree', 'add', wtPath, branchName]);
             }
         }
         catch (e) {
             spinner.fail('Failed to create worktree.');
             const cmd = targetBranchExists
                 ? `git worktree add ${wtPath} ${branchName}`
-                : `git worktree add -b ${branchName} ${wtPath} ${baseRef}`;
+                : `git branch --no-track ${branchName} ${baseRef} && git worktree add ${wtPath} ${branchName}`;
             log.actionableError(e.message, cmd, wtPath, [
                 'Check if the folder already exists: ls ' + wtPath,
                 'Check if the branch is already used: git worktree list',
@@ -124,20 +134,21 @@ export async function createCommandNew(options) {
             ]);
             return;
         }
+        // Safety net: ensure no incorrect upstream was inherited
+        spinner.text = 'Verifying upstream safety...';
+        await ensureCorrectUpstream(wtPath, branchName);
+        // Auto-publish: push to origin and set correct tracking
         try {
-            // Strong Safety Mode: Ensure upstream is origin/<branchName> and publish
-            spinner.text = 'Safely publishing branch...';
-            await ensureCorrectUpstream(wtPath, branchName);
+            spinner.text = 'Publishing branch...';
+            await publishBranch(wtPath, branchName);
             spinner.succeed('Worktree created and branch published.');
         }
         catch (e) {
-            spinner.fail('Worktree created, but branch publication failed.');
+            spinner.succeed('Worktree created (publish failed — push manually later).');
             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);
@@ -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-multi.js

@@ -1,7 +1,7 @@
 import chalk from 'chalk';
 import inquirer from 'inquirer';
 import path from 'path';
-import { getRepoRoot, getRepoName, verifyRef, fetchAll, getCurrentBranch, ensureCorrectUpstream } from '../../lib/git.js';
+import { getRepoRoot, getRepoName, verifyRef, fetchAll, getCurrentBranch, ensureCorrectUpstream, publishBranch } 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';
@@ -82,14 +82,16 @@ export async function createCommandMulti(options) {
                     await execa('git', ['worktree', 'add', wtPath, branchName]);
                 }
                 else {
-                    await execa('git', ['worktree', 'add', '-b', branchName, wtPath, baseRef]);
+                    // Create branch WITHOUT tracking the base, then attach worktree
+                    await execa('git', ['branch', '--no-track', branchName, baseRef]);
+                    await execa('git', ['worktree', 'add', wtPath, branchName]);
                 }
             }
             catch (error) {
                 wtSpinner.fail(`Failed to create worktree for ${branchName}.`);
                 const cmd = targetBranchExists
                     ? `git worktree add ${wtPath} ${branchName}`
-                    : `git worktree add -b ${branchName} ${wtPath} ${baseRef}`;
+                    : `git branch --no-track ${branchName} ${baseRef} && git worktree add ${wtPath} ${branchName}`;
                 log.actionableError(error.message, cmd, wtPath, [
                     'Check if the folder already exists: ls ' + wtPath,
                     'Check if the branch is already used: git worktree list',
@@ -98,22 +100,23 @@ export async function createCommandMulti(options) {
                 ]);
                 continue;
             }
+            // Safety net: ensure no incorrect upstream was inherited
+            wtSpinner.text = `Verifying upstream safety for ${branchName}...`;
+            await ensureCorrectUpstream(wtPath, branchName);
+            // Auto-publish: push to origin and set correct tracking
             try {
-                // Strong Safety Mode: Ensure upstream is origin/<branchName> and publish
-                wtSpinner.text = `Safely publishing branch ${branchName}...`;
-                await ensureCorrectUpstream(wtPath, branchName);
+                wtSpinner.text = `Publishing branch ${branchName}...`;
+                await publishBranch(wtPath, branchName);
                 wtSpinner.succeed(`Worktree for ${chalk.cyan(branchName)} created and published.`);
-                createdWorktrees.push(wtPath);
             }
             catch (error) {
-                wtSpinner.fail(`Worktree for ${branchName} created, but publication failed.`);
+                wtSpinner.succeed(`Worktree for ${chalk.cyan(branchName)} created (publish failed — push manually later).`);
                 log.actionableError(error.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'
                 ]);
-                createdWorktrees.push(wtPath); // Still added to list since wt exists
             }
+            createdWorktrees.push(wtPath);
             // 4. Bootstrap
             if (shouldBootstrap) {
                 await runBootstrap(wtPath, repoRoot);

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.`);