@dfosco/storyboard-core 4.2.7 → 4.2.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dfosco/storyboard-core",
-  "version": "4.2.7",
+  "version": "4.2.8",
   "type": "module",
   "license": "MIT",
   "bin": {

package/scaffold/skills/worktree/SKILL.md

@@ -20,12 +20,15 @@ If the branch already exists locally or on the remote:
 git worktree add worktrees/<branch-name> <branch-name>
 ```
 
-If the branch does NOT exist yet, create it from the current HEAD:
+If the branch does NOT exist yet, create it **from the current branch** (NOT from main):
 
 ```bash
-git worktree add worktrees/<branch-name> -b <branch-name>
+CURRENT_BRANCH=$(git branch --show-current)
+git worktree add worktrees/<branch-name> -b <branch-name> "$CURRENT_BRANCH"
 ```
 
+> **⚠️ CRITICAL:** Always pass the current branch as the start-point. Without it, git defaults to HEAD of the main worktree, which may be a completely different branch.
+
 ### Step 2: Register a dev-server port
 
 Assign a unique port for this worktree so multiple dev servers can run simultaneously.

package/src/cli/branch.js

@@ -2,18 +2,24 @@
  * storyboard branch — Interactive guide to switch to a branch worktree.
  *
  * Deterministic flow (no AI):
- *   1. Ask which branch to work on
- *   2. Stash uncommitted work (named stash for safety)
- *   3. Create worktree if needed (git worktree add + npm install)
- *   4. Pull --rebase from origin
- *   5. Apply stash into the new worktree
- *   6. Confirm to user
+ *   1. Ask which branch to work on (or accept --worktree flag)
+ *   2. If existing worktree:
+ *      a. Stash uncommitted work in source (named stash)
+ *      b. Ensure target is on the correct branch
+ *      c. Apply source stash in target
+ *   3. If new worktree:
+ *      a. Stash uncommitted work in source
+ *      b. Create worktree (git worktree add + npm install)
+ *      c. Pull --rebase from origin
+ *      d. Apply source stash in target
+ *   4. Confirm to user
  *
  * Also available as post-setup prompt in setup.js.
  *
  * Usage:
- *   npx storyboard branch
- *   npx storyboard branch <name>   # skip the prompt
+ *   npx storyboard branch                    # interactive
+ *   npx storyboard branch <name>             # positional, skip prompt
+ *   npx storyboard branch --worktree=<name>  # non-interactive flag
  */
 
 import * as p from '@clack/prompts'
@@ -22,8 +28,14 @@ import { existsSync } from 'fs'
 import { resolve } from 'path'
 import { repoRoot, worktreeDir, listWorktrees, getPort, detectWorktreeName } from '../worktree/port.js'
 import { hasUncommittedChanges, localBranchExists } from './dev-helpers.js'
+import { parseFlags } from './flags.js'
 import { dim, green, bold, cyan } from './intro.js'
 
+const flagSchema = {
+  worktree: { type: 'string', description: 'Target worktree/branch name (non-interactive)' },
+  cd: { type: 'boolean', default: false, description: 'Output shell-evaluable cd command (for eval)' },
+}
+
 /** Check if a remote branch exists on origin. */
 function remoteBranchExists(name, cwd) {
   try {
@@ -34,7 +46,7 @@ function remoteBranchExists(name, cwd) {
   }
 }
 
-/** Get the current branch name. */
+/** Get the current branch name in a given directory. */
 function currentBranch(cwd) {
   try {
     return execFileSync('git', ['branch', '--show-current'], { cwd, encoding: 'utf8' }).trim()
@@ -55,96 +67,151 @@ function isValidBranchName(name) {
   return undefined
 }
 
-export async function runBranchGuide(branchArg) {
-  const root = repoRoot()
-  const existing = listWorktrees()
-  const fromBranch = currentBranch(root)
-  const fromWorktree = detectWorktreeName()
+/** Build a timestamped stash message. */
+function stashMessage(from, to) {
+  const ts = new Date().toISOString().replace(/[:.]/g, '-')
+  return `from-${from}-to-${to}-${ts}`
+}
 
-  // 1. Get branch name
-  let targetBranch = branchArg?.trim()
+/**
+ * Stash uncommitted changes (including untracked files) and return the stash ref SHA.
+ * Returns null if nothing was stashed.
+ */
+function stashChanges(cwd, message) {
+  if (!hasUncommittedChanges(cwd)) return null
 
-  if (!targetBranch) {
-    if (existing.length > 0) {
-      // Render as columns that fit the terminal width
-      const maxLen = Math.max(...existing.map(w => w.length))
-      const colWidth = maxLen + 2
-      const termWidth = process.stdout.columns || 80
-      const cols = Math.max(1, Math.floor(termWidth / colWidth))
-      const rows = Math.ceil(existing.length / cols)
-      const lines = []
-      for (let r = 0; r < rows; r++) {
-        const parts = []
-        for (let c = 0; c < cols; c++) {
-          const idx = c * rows + r
-          if (idx < existing.length) {
-            parts.push(cyan(existing[idx].padEnd(colWidth)))
-          }
-        }
-        lines.push(`  ${parts.join('')}`)
+  p.log.step('Stashing uncommitted work…')
+  try {
+    execFileSync('git', ['stash', 'push', '-u', '-m', message], { cwd, stdio: 'pipe' })
+    // Capture the exact stash SHA so we can apply it by ref later
+    const sha = execFileSync('git', ['stash', 'list', '--format=%H', '-1'], { cwd, encoding: 'utf8' }).trim()
+    p.log.success(`Work stashed: ${dim(message)}`)
+    return sha
+  } catch {
+    p.log.warning('Could not stash changes — proceeding anyway')
+    return null
+  }
+}
+
+/**
+ * Apply a specific stash by SHA in the given directory.
+ * Uses apply (not pop) so the backup remains in the stash list.
+ */
+function applyStash(cwd, stashSha) {
+  try {
+    execFileSync('git', ['stash', 'apply', stashSha], { cwd, stdio: 'pipe' })
+    p.log.success('Previous work applied to this branch')
+    return true
+  } catch {
+    p.log.warning('Stash apply had conflicts — resolve them manually')
+    p.log.info(`  Your work is safe in ${dim('git stash list')}`)
+    return false
+  }
+}
+
+/**
+ * Core logic for switching to an EXISTING worktree.
+ *
+ * 1. Stash source changes (if any)
+ * 2. Ensure target worktree is on the expected branch
+ * 3. Apply source stash in target
+ */
+function switchToExistingWorktree(targetBranch, { sourceDir, fromBranch }) {
+  const targetDir = worktreeDir(targetBranch)
+
+  // 1. Stash source changes
+  const sourceStashSha = stashChanges(sourceDir, stashMessage(fromBranch, targetBranch))
+
+  // 2. Ensure target is on the correct branch
+  const targetCurrentBranch = currentBranch(targetDir)
+
+  if (targetCurrentBranch !== targetBranch) {
+    // Target worktree is on a different branch — check if it's clean
+    if (hasUncommittedChanges(targetDir)) {
+      p.log.error(
+        `Worktree ${bold(targetBranch)} is on branch ${bold(targetCurrentBranch)} with uncommitted changes.`
+      )
+      p.log.info(`  Clean up the worktree first:`)
+      p.log.info(`    ${green('cd')} ${dim(`worktrees/${targetBranch}`)}`)
+      p.log.info(`    ${dim('git stash')} ${dim('or')} ${dim('git commit')}`)
+      p.log.info(`    ${dim(`git checkout ${targetBranch}`)}`)
+      if (sourceStashSha) {
+        p.log.info(`\n  Your source stash is safe — apply it later with:`)
+        p.log.info(`    ${dim(`git stash apply ${sourceStashSha.slice(0, 8)}`)}`)
       }
-      p.log.info(`${dim('Existing worktrees:')}\n${lines.join('\n')}`)
+      p.outro('')
+      process.exit(1)
     }
 
-    const result = await p.text({
-      message: 'Which branch do you want to work on? Select one from above or type a new one',
-      placeholder: 'e.g. 4.3.0--my-feature',
-      validate: isValidBranchName,
-    })
+    // Clean worktree on wrong branch — switch it
+    p.log.step(`Switching worktree from ${bold(targetCurrentBranch)} to ${bold(targetBranch)}…`)
+    try {
+      execFileSync('git', ['checkout', targetBranch], { cwd: targetDir, stdio: 'pipe' })
+      p.log.success(`Now on branch ${bold(targetBranch)}`)
+    } catch (err) {
+      p.log.error(`Could not switch branch: ${err.message || 'git checkout failed'}`)
+      if (sourceStashSha) {
+        p.log.info(`  Your source stash is safe: ${dim(`git stash apply ${sourceStashSha.slice(0, 8)}`)}`)
+      }
+      p.outro('')
+      process.exit(1)
+    }
+  } else {
+    p.log.success(`Worktree ${bold(targetBranch)} is on the correct branch`)
+  }
 
-    if (p.isCancel(result)) {
-      p.cancel('Cancelled')
-      process.exit(0)
+  // 3. Apply source stash in target
+  if (sourceStashSha) {
+    if (hasUncommittedChanges(targetDir)) {
+      p.log.warning(`Target worktree has uncommitted changes — skipping stash apply`)
+      p.log.info(`  Apply your stash manually: ${dim(`git stash apply ${sourceStashSha.slice(0, 8)}`)}`)
+    } else {
+      applyStash(targetDir, sourceStashSha)
     }
-    targetBranch = result.trim()
   }
 
-  // 2. Check if worktree already exists
-  const wtDir = worktreeDir(targetBranch)
-  if (existsSync(resolve(wtDir, '.git'))) {
-    p.log.success(`Worktree ${bold(targetBranch)} already exists`)
-    p.note(
-      [
-        `  ${green('cd')} ${dim(`worktrees/${targetBranch}`)}`,
-        `  ${green('npx storyboard dev')}  ${dim('to start developing')}`,
-      ].join('\n'),
-      'Ready to go'
-    )
-    p.outro('')
-    return
-  }
-
-  // 3. Stash uncommitted work
-  let didStash = false
-  const sourceDir = fromWorktree === 'main' ? root : worktreeDir(fromWorktree)
+  // 4. Summary
+  const lines = [
+    `  Worktree ready: ${green(`worktrees/${targetBranch}`)}`,
+  ]
+  if (sourceStashSha) {
+    lines.push(`  Your uncommitted work has been safely moved`)
+  }
+  lines.push('')
+  lines.push(`  ${green('cd')} ${dim(`worktrees/${targetBranch}`)}`)
+  lines.push(`  ${green('npx storyboard dev')}  ${dim('to start developing')}`)
+  lines.push('')
+  lines.push(`  ${dim('Tip: auto-cd with')} ${green('eval "$(npx sb branch --cd)"')}`)
 
-  if (hasUncommittedChanges(sourceDir)) {
-    const timestamp = new Date().toISOString().replace(/[:.]/g, '-')
-    const stashName = `${fromBranch}→${targetBranch}@${timestamp}`
+  p.note(lines.join('\n'), `Branch ${bold(targetBranch)} is ready`)
+  p.outro('')
+  return targetDir
+}
 
-    p.log.step('Stashing uncommitted work…')
-    try {
-      execFileSync('git', ['stash', 'push', '-m', stashName], { cwd: sourceDir, stdio: 'pipe' })
-      didStash = true
-      p.log.success(`Work stashed: ${dim(stashName)}`)
-    } catch {
-      p.log.warning('Could not stash changes — proceeding anyway')
-    }
-  }
+/**
+ * Core logic for creating a NEW worktree.
+ *
+ * 1. Stash source changes
+ * 2. Resolve branch (local/remote/new)
+ * 3. Create worktree + npm install
+ * 4. Pull --rebase
+ * 5. Apply source stash
+ */
+function createNewWorktree(targetBranch, { sourceDir, fromBranch, root }) {
+  // 1. Stash source changes
+  const sourceStashSha = stashChanges(sourceDir, stashMessage(fromBranch, targetBranch))
 
-  // 4. Resolve branch and create worktree
+  // 2. Resolve branch
   const hasLocal = localBranchExists(targetBranch, root)
   const hasRemote = !hasLocal && remoteBranchExists(targetBranch, root)
   const isNew = !hasLocal && !hasRemote
 
   if (isNew) {
-    p.log.step(`Creating new branch ${bold(targetBranch)} from HEAD`)
+    p.log.step(`Creating new branch ${bold(targetBranch)} from ${bold(fromBranch)}`)
   } else if (hasRemote) {
-    // Fetch the remote branch so git worktree add can use it
     p.log.step(`Fetching ${bold(targetBranch)} from origin…`)
     try {
       execFileSync('git', ['fetch', 'origin', targetBranch], { cwd: root, stdio: 'pipe' })
-      // Create a local tracking branch
       try {
         execFileSync('git', ['branch', targetBranch, `origin/${targetBranch}`], { cwd: root, stdio: 'pipe' })
       } catch { /* may already exist after fetch */ }
@@ -155,13 +222,14 @@ export async function runBranchGuide(branchArg) {
     p.log.step(`Using existing branch ${bold(targetBranch)}`)
   }
 
-  // Create the worktree
+  // 3. Create the worktree
   const targetDir = resolve(root, 'worktrees', targetBranch)
   const spin = p.spinner()
 
   try {
+    // For new branches, use current branch as start-point (not main's HEAD)
     const gitArgs = isNew
-      ? ['worktree', 'add', targetDir, '-b', targetBranch]
+      ? ['worktree', 'add', targetDir, '-b', targetBranch, fromBranch]
       : ['worktree', 'add', targetDir, targetBranch]
 
     spin.start(`Creating worktree worktrees/${targetBranch}`)
@@ -186,7 +254,7 @@ export async function runBranchGuide(branchArg) {
   // Assign a dev server port
   getPort(targetBranch)
 
-  // 5. Pull --rebase from origin
+  // 4. Pull --rebase from origin
   if (!isNew) {
     try {
       spin.start('Pulling latest changes…')
@@ -197,36 +265,122 @@ export async function runBranchGuide(branchArg) {
     }
   }
 
-  // 6. Apply stash (if we stashed earlier)
-  if (didStash) {
-    try {
-      // Apply (not pop) — keeps the backup in stash list
-      execFileSync('git', ['stash', 'apply'], { cwd: targetDir, stdio: 'pipe' })
-      p.log.success('Previous work applied to this branch')
-    } catch {
-      p.log.warning('Stash apply had conflicts — resolve them manually')
-      p.log.info(`  Your work is safe in ${dim('git stash list')}`)
-    }
+  // 5. Apply source stash
+  if (sourceStashSha) {
+    applyStash(targetDir, sourceStashSha)
   }
 
-  // 7. Summary
+  // 6. Summary
   const lines = [
     `  Your branch is set up as a worktree in ${green(`worktrees/${targetBranch}`)}`,
   ]
-  if (didStash) {
+  if (sourceStashSha) {
     lines.push(`  Your uncommitted work has been safely moved`)
   }
   lines.push('')
   lines.push(`  ${green('cd')} ${dim(`worktrees/${targetBranch}`)}`)
   lines.push(`  ${green('npx storyboard dev')}  ${dim('to start developing')}`)
   lines.push('')
-  lines.push(`  ${dim('Tip: ask your AI agent about worktrees — they\'re great!')}`)
+  lines.push(`  ${dim('Tip: auto-cd with')} ${green('eval "$(npx sb branch --cd)"')}`)
 
   p.note(lines.join('\n'), `Branch ${bold(targetBranch)} is ready`)
   p.outro('')
+  return targetDir
+}
+
+// ─── Main ───
+
+export async function runBranchGuide(branchArg) {
+  const root = repoRoot()
+  const existing = listWorktrees()
+  const fromWorktree = detectWorktreeName()
+  const sourceDir = fromWorktree === 'main' ? root : worktreeDir(fromWorktree)
+  const fromBranch = currentBranch(sourceDir)
+
+  // 1. Get branch name — select from existing or type a new one
+  let targetBranch = branchArg?.trim()
+
+  if (!targetBranch) {
+    if (existing.length > 0) {
+      // Build select options from existing worktrees + "new branch" option
+      const NEW_BRANCH = Symbol('new')
+      const options = [
+        ...existing.map(name => ({ value: name, label: name })),
+        { value: NEW_BRANCH, label: dim('Create a new branch…') },
+      ]
+
+      const selected = await p.select({
+        message: 'Which branch do you want to work on?',
+        options,
+      })
+
+      if (p.isCancel(selected)) {
+        p.cancel('Cancelled')
+        process.exit(0)
+      }
+
+      if (selected === NEW_BRANCH) {
+        const newName = await p.text({
+          message: 'New branch name:',
+          placeholder: 'e.g. 4.3.0--my-feature',
+          validate: isValidBranchName,
+        })
+        if (p.isCancel(newName)) {
+          p.cancel('Cancelled')
+          process.exit(0)
+        }
+        targetBranch = newName.trim()
+      } else {
+        targetBranch = selected
+      }
+    } else {
+      // No existing worktrees — just ask for a name
+      const result = await p.text({
+        message: 'Branch name for new worktree:',
+        placeholder: 'e.g. 4.3.0--my-feature',
+        validate: isValidBranchName,
+      })
+
+      if (p.isCancel(result)) {
+        p.cancel('Cancelled')
+        process.exit(0)
+      }
+      targetBranch = result.trim()
+    }
+  }
+
+  // 2. Show equivalent non-interactive command (when user used TUI to select)
+  if (!branchArg) {
+    p.log.info(`${dim('Non-interactive:')} ${green(`npx sb branch --worktree=${targetBranch}`)}`)
+  }
+
+  // 3. Route to existing or new worktree flow
+  const wtDir = worktreeDir(targetBranch)
+  if (existsSync(resolve(wtDir, '.git'))) {
+    return switchToExistingWorktree(targetBranch, { sourceDir, fromBranch })
+  } else {
+    return createNewWorktree(targetBranch, { sourceDir, fromBranch, root })
+  }
+}
+
+// ─── Direct invocation ───
+
+const { flags, positional } = parseFlags(process.argv.slice(3), flagSchema)
+const branchArg = flags.worktree || positional[0] || undefined
+
+// When --cd is set, redirect all TUI output (Clack) to stderr so that
+// stdout contains only the shell-evaluable `cd <path>` command.
+// Usage: eval "$(npx sb branch --worktree=<name> --cd)"
+const realStdoutWrite = process.stdout.write.bind(process.stdout)
+if (flags.cd) {
+  process.stdout.write = (chunk, encoding, callback) =>
+    process.stderr.write(chunk, encoding, callback)
 }
 
-// Direct invocation
-const branchArg = process.argv[3] || undefined
 p.intro('storyboard branch')
-runBranchGuide(branchArg)
+runBranchGuide(branchArg).then((targetDir) => {
+  if (flags.cd && targetDir) {
+    process.stdout.write = realStdoutWrite
+    realStdoutWrite(`cd ${JSON.stringify(targetDir)}\n`)
+  }
+})

package/src/cli/index.js

@@ -93,8 +93,11 @@ function helpScreen(version) {
     '',
     `  ${bold(cyan('Setup'))}`,
     cmd('setup', 'Install deps, Caddy proxy, start proxy'),
+    cmd('setup --skip-branch', 'Non-interactive setup (skip branch prompt)'),
+    cmd('setup --branch=<name>', 'Setup + switch to a branch'),
     cmd('branch', 'Switch to a branch (interactive worktree guide)'),
     cmd('branch <name>', 'Switch to a specific branch directly'),
+    cmd('branch --worktree=<name>', 'Non-interactive branch switch'),
     cmd('proxy start', 'Start or reload Caddy proxy'),
     cmd('proxy close', 'Stop Caddy proxy'),
     '',

package/src/cli/setup.js

@@ -2,6 +2,11 @@
  * storyboard setup — One-time setup for the Storyboard dev environment.
  *
  * Idempotent: safe to run multiple times, only does what's needed.
+ *
+ * Usage:
+ *   npx storyboard setup                          # interactive
+ *   npx storyboard setup --skip-branch             # non-interactive, skip branch prompt
+ *   npx storyboard setup --branch=<name>           # non-interactive, switch to branch after setup
  */
 
 import * as p from '@clack/prompts'
@@ -9,7 +14,15 @@ import { existsSync, writeFileSync, readFileSync, mkdirSync, readdirSync, symlin
 import path from 'path'
 import { execSync } from 'child_process'
 import { generateCaddyfile, isCaddyInstalled, isCaddyRunning, startCaddy, reloadCaddy } from './proxy.js'
-import { gettingStartedLines, dim, magenta, bold, yellow } from './intro.js'
+import { gettingStartedLines, dim, magenta, bold, yellow, green } from './intro.js'
+import { parseFlags } from './flags.js'
+
+const flagSchema = {
+  'skip-branch': { type: 'boolean', default: false, description: 'Skip the branch prompt at the end' },
+  branch: { type: 'string', description: 'Switch to a branch after setup (non-interactive)' },
+}
+
+const { flags } = parseFlags(process.argv.slice(3), flagSchema)
 
 /**
  * Run a potentially slow task with a spinner that only appears after 500ms.
@@ -330,11 +343,16 @@ if (isCaddyInstalled()) {
     p.log.info(dim('Skipping npm install — dev server is running (would cause restart)'))
     p.log.info(dim('Run `npm install` manually after stopping the dev server if needed'))
   } else {
-    await withSpin(
-      'Installing dependencies...',
-      'Dependencies installed',
-      () => { run('npm install', { stdio: 'ignore' }) }
-    )
+    try {
+      await withSpin(
+        'Installing dependencies...',
+        'Dependencies installed',
+        () => { run('npm install', { stdio: 'ignore' }) }
+      )
+    } catch {
+      p.log.warning('npm install failed — run it manually to see details')
+      p.log.info(`  ${dim('npm install')}`)
+    }
   }
 }
 
@@ -349,26 +367,38 @@ p.note(
 
 // Offer branch guide
 {
-  let currentBranchName = 'main'
-  try {
-    currentBranchName = execSync('git branch --show-current', { encoding: 'utf8' }).trim() || 'main'
-  } catch { /* empty */ }
-
-  const wantBranch = await p.select({
-    message: 'Want to work from a different branch?',
-    options: [
-      { value: true, label: 'Yes (help me create it)' },
-      { value: false, label: `No (stay on current branch ${bold(currentBranchName)})` },
-    ],
-    initialValue: false,
-  })
-
-  if (!p.isCancel(wantBranch) && wantBranch) {
+  // Non-interactive: --branch=<name> or --skip-branch
+  if (flags.branch) {
     const { runBranchGuide } = await import('./branch.js')
-    await runBranchGuide()
-  } else {
+    await runBranchGuide(flags.branch)
+  } else if (flags['skip-branch']) {
     console.log()
     console.log(mascot())
     p.outro('')
+  } else {
+    // Interactive: ask the user
+    let currentBranchName = 'main'
+    try {
+      currentBranchName = execSync('git branch --show-current', { encoding: 'utf8' }).trim() || 'main'
+    } catch { /* empty */ }
+
+    const wantBranch = await p.select({
+      message: 'Want to work from a different branch?',
+      options: [
+        { value: true, label: 'Yes (help me create it)' },
+        { value: false, label: `No (stay on current branch ${bold(currentBranchName)})` },
+      ],
+      initialValue: false,
+    })
+
+    if (!p.isCancel(wantBranch) && wantBranch) {
+      const { runBranchGuide } = await import('./branch.js')
+      await runBranchGuide()
+    } else {
+      console.log()
+      console.log(mascot())
+      p.log.info(`${dim('Non-interactive:')} ${green('npx sb setup --skip-branch')}`)
+      p.outro('')
+    }
   }
 }