@dfosco/storyboard-core 4.0.0-beta.3 → 4.0.0-beta.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dfosco/storyboard-core",
-  "version": "4.0.0-beta.3",
+  "version": "4.0.0-beta.5",
   "type": "module",
   "license": "MIT",
   "bin": {

package/src/autosync/server.js

@@ -81,7 +81,7 @@ function hasScopedStagedChanges(root, files) {
 function listChangedFiles(root) {
   const tracked = git(['diff', '--name-only'], root)
   const untracked = git(['ls-files', '--others', '--exclude-standard'], root)
-  return [...tracked, ...untracked]
+  return [tracked, untracked]
     .flatMap((raw) => raw.split('\n'))
     .map((file) => file.trim())
     .filter(Boolean)

package/src/cli/dev.js

@@ -1,20 +1,164 @@
 /**
- * storyboard dev — Start Vite with correct base path for the current worktree.
+ * storyboard dev [branch] — Start Vite with correct base path.
+ *
+ * Usage:
+ *   storyboard dev                 # detect worktree from cwd
+ *   storyboard dev main            # start dev for repo root
+ *   storyboard dev <worktree>      # start dev for existing worktree
+ *   storyboard dev <branch>        # auto-create worktree + start dev
  *
  * Main:   http://<devDomain>.localhost/
  * Branch: http://<devDomain>.localhost/branch--<name>/
  */
 
 import * as p from '@clack/prompts'
-import { spawn } from 'child_process'
+import { spawn, execFileSync } from 'child_process'
 import { existsSync } from 'fs'
 import { resolve } from 'path'
-import { detectWorktreeName, getPort } from '../worktree/port.js'
+import { detectWorktreeName, getPort, repoRoot, worktreeDir, listWorktrees } from '../worktree/port.js'
 import { generateCaddyfile, generateRouteConfig, upsertCaddyRoute, isCaddyRunning, reloadCaddy, readDevDomain } from './proxy.js'
 import { startRenameWatcher } from '../rename-watcher/watcher.js'
+import { parseFlags } from './flags.js'
+
+const flagSchema = {
+  port: { type: 'number', description: 'Override dev server port' },
+  create: { type: 'boolean', default: true, description: 'Allow creating worktrees/branches (disable with --no-create)' },
+}
+
+/**
+ * Check if a local branch exists.
+ * @param {string} name
+ * @param {string} cwd
+ * @returns {boolean}
+ */
+function localBranchExists(name, cwd) {
+  try {
+    execFileSync('git', ['show-ref', '--verify', `refs/heads/${name}`], { cwd, stdio: 'ignore' })
+    return true
+  } catch {
+    return false
+  }
+}
+
+/**
+ * Check if a remote branch exists on origin.
+ * @param {string} name
+ * @param {string} cwd
+ * @returns {boolean}
+ */
+function remoteBranchExists(name, cwd) {
+  try {
+    const result = execFileSync('git', ['ls-remote', '--exit-code', '--heads', 'origin', name], { cwd, encoding: 'utf8' })
+    return result.trim().length > 0
+  } catch {
+    return false
+  }
+}
+
+/**
+ * Create a git worktree and install dependencies.
+ * @param {string} name — worktree/branch name
+ * @param {string} root — repo root path
+ * @param {object} opts
+ * @param {boolean} opts.newBranch — create a new branch from HEAD
+ * @returns {string} path to the new worktree directory
+ */
+function createWorktree(name, root, { newBranch = false } = {}) {
+  const targetDir = resolve(root, '.worktrees', name)
+
+  const gitArgs = newBranch
+    ? ['worktree', 'add', targetDir, '-b', name]
+    : ['worktree', 'add', targetDir, name]
+
+  p.log.step(`Creating worktree: .worktrees/${name}`)
+  execFileSync('git', gitArgs, { cwd: root, stdio: 'inherit' })
+
+  p.log.step('Installing dependencies…')
+  const npmBin = process.platform === 'win32' ? 'npm.cmd' : 'npm'
+  execFileSync(npmBin, ['install'], { cwd: targetDir, stdio: 'inherit' })
+
+  getPort(name)
+  return targetDir
+}
+
+/**
+ * Resolve the target worktree for `storyboard dev [branch]`.
+ *
+ * @param {string|undefined} branchArg — positional branch argument
+ * @param {object} opts
+ * @param {boolean} opts.allowCreate — whether creation is allowed
+ * @returns {Promise<{ worktreeName: string, targetCwd: string, created: boolean }>}
+ */
+async function resolveDevTarget(branchArg, { allowCreate = true } = {}) {
+  // No argument — detect from cwd (current behavior)
+  if (!branchArg) {
+    return { worktreeName: detectWorktreeName(), targetCwd: process.cwd(), created: false }
+  }
+
+  const root = repoRoot()
+
+  // "main" → repo root
+  if (branchArg === 'main') {
+    return { worktreeName: 'main', targetCwd: root, created: false }
+  }
+
+  // Existing worktree directory
+  const existingDir = worktreeDir(branchArg)
+  if (existsSync(resolve(existingDir, '.git'))) {
+    return { worktreeName: branchArg, targetCwd: existingDir, created: false }
+  }
+
+  // From here on we need to create — check if allowed
+  if (!allowCreate) {
+    p.log.error(`Worktree "${branchArg}" does not exist. Use without --no-create to auto-create.`)
+    process.exit(1)
+  }
+
+  // Branch exists (local or remote) — create worktree from it
+  const hasLocal = localBranchExists(branchArg, root)
+  const hasRemote = !hasLocal && remoteBranchExists(branchArg, root)
+
+  if (hasLocal || hasRemote) {
+    const targetDir = createWorktree(branchArg, root, { newBranch: false })
+    return { worktreeName: branchArg, targetCwd: targetDir, created: true }
+  }
+
+  // Branch doesn't exist — interactive TTY gets a prompt, non-interactive auto-creates
+  const isTTY = process.stdin.isTTY
+
+  if (isTTY) {
+    const confirmed = await p.confirm({
+      message: `Branch "${branchArg}" doesn't exist. Create it from HEAD?`,
+    })
+    if (p.isCancel(confirmed) || !confirmed) {
+      p.cancel('Cancelled.')
+      process.exit(0)
+    }
+  } else {
+    p.log.step(`Branch "${branchArg}" not found — creating from HEAD`)
+  }
+
+  const targetDir = createWorktree(branchArg, root, { newBranch: true })
+  return { worktreeName: branchArg, targetCwd: targetDir, created: true }
+}
 
 async function main() {
-  const worktreeName = detectWorktreeName()
+  const { flags, positional } = parseFlags(process.argv.slice(3), flagSchema)
+
+  const branchArg = positional[0] || undefined
+  const overridePort = flags.port || null
+  const allowCreate = flags.create
+
+  p.intro('storyboard dev')
+
+  const { worktreeName, targetCwd, created } = await resolveDevTarget(branchArg, { allowCreate })
+
+  if (created) {
+    p.log.success(`Worktree ready: .worktrees/${worktreeName}`)
+  } else if (branchArg) {
+    p.log.info(`Using ${worktreeName === 'main' ? 'main repo' : `.worktrees/${worktreeName}`}`)
+  }
+
   const port = getPort(worktreeName)
   const isMain = worktreeName === 'main'
 
@@ -22,42 +166,31 @@ async function main() {
     ? '/'
     : `/branch--${worktreeName}/`
 
-  const domain = readDevDomain()
+  const domain = readDevDomain(targetCwd)
   const proxyUrl = `http://${domain}${basePath}`
   const directUrl = `http://localhost:${port}${basePath}`
 
-  p.intro('storyboard dev')
-
-  // Parse --port override from argv (skip 'dev' subcommand)
-  const args = process.argv.slice(3)
-  const portFlagIdx = args.indexOf('--port')
-  const overridePort = portFlagIdx >= 0 ? Number(args[portFlagIdx + 1]) : null
-
-  const extraArgs = args.filter((arg, i, arr) => {
-    if (arg === '--port') return false
-    if (i > 0 && arr[i - 1] === '--port') return false
-    return true
-  })
-
-  // Resolve Vite binary directly to skip npx overhead (~5s)
-  const localVite = resolve(process.cwd(), 'node_modules', '.bin', 'vite')
+  // Resolve Vite binary relative to target worktree
+  const localVite = resolve(targetCwd, 'node_modules', '.bin', 'vite')
   const useLocalVite = existsSync(localVite)
 
   // Start Vite — let it find a free port if assigned one is busy.
   // Capture stdout to detect actual port and update Caddy.
-  const viteArgs = ['--port', String(overridePort || port), ...extraArgs]
+  const viteArgs = ['--port', String(overridePort || port)]
   const child = useLocalVite
     ? spawn(localVite, viteArgs, {
+        cwd: targetCwd,
         env: { ...process.env, VITE_BASE_PATH: basePath },
         stdio: ['inherit', 'pipe', 'pipe'],
       })
     : spawn('npx', ['vite', ...viteArgs], {
+        cwd: targetCwd,
         env: { ...process.env, VITE_BASE_PATH: basePath },
         stdio: ['inherit', 'pipe', 'pipe'],
       })
 
-  // Start rename watcher after Vite spawn (no need to block startup)
-  const renameWatcher = startRenameWatcher(process.cwd())
+  // Start rename watcher in target directory
+  const renameWatcher = startRenameWatcher(targetCwd)
 
   let caddyUpdated = false
   let ready = false

package/src/cli/index.js

@@ -70,6 +70,7 @@ function helpScreen(version) {
     '',
     `  ${bold(cyan('Development'))}`,
     cmd('dev', 'Start Vite dev server + update proxy'),
+    cmd('dev [branch]', 'Start dev for a specific worktree/branch'),
     cmd('exit', 'Stop all dev servers and proxy'),
     '',
     `  ${bold(cyan('Create'))}`,

package/src/cli/proxy.js

@@ -14,9 +14,9 @@ import { execSync } from 'child_process'
 import { dirname, resolve } from 'path'
 import { portsFilePath } from '../worktree/port.js'
 
-export function readDevDomain() {
+export function readDevDomain(cwd) {
   try {
-    const configPath = resolve(process.cwd(), 'storyboard.config.json')
+    const configPath = resolve(cwd || process.cwd(), 'storyboard.config.json')
     const config = JSON.parse(readFileSync(configPath, 'utf8'))
     return `${config.devDomain || 'storyboard'}.localhost`
   } catch {

package/src/cli/updateVersion.js

@@ -79,18 +79,28 @@ try {
   p.log.warn('Scaffold sync failed — run `npx storyboard-scaffold` manually')
 }
 
-// Auto-commit the version update
+// Auto-commit the version update (only if package.json or lock file changed)
 try {
   // Read the installed version from the core package
   const corePkg = JSON.parse(readFileSync(resolve(process.cwd(), 'node_modules', '@dfosco', 'storyboard-core', 'package.json'), 'utf8'))
   const installedVersion = corePkg.version || suffix.slice(1)
   const commitMsg = `[storyboard-update] Update storyboard to ${installedVersion}`
 
-  execSync('git add -A', { cwd: process.cwd(), stdio: 'pipe' })
+  // Only stage update-related files (package.json, lock files, scaffold outputs)
+  const filesToStage = [
+    'package.json',
+    'package-lock.json',
+    'yarn.lock',
+    'pnpm-lock.yaml',
+    '.github/skills',
+    'scripts',
+  ]
+  execSync(`git add ${filesToStage.join(' ')} 2>/dev/null || true`, { cwd: process.cwd(), stdio: 'pipe' })
+
   // Only commit if there are staged changes
   try {
     execSync('git diff --cached --quiet', { cwd: process.cwd(), stdio: 'pipe' })
-    p.log.message('No changes to commit')
+    p.log.message('No changes to commit — already up to date')
   } catch {
     execSync(`git commit -m "${commitMsg}"`, { cwd: process.cwd(), stdio: 'pipe' })
     p.log.success(`Committed: ${commitMsg}`)

package/src/worktree/port.js

@@ -11,7 +11,7 @@
  *   import { getPort, detectWorktreeName, resolvePort } from '@dfosco/storyboard-core/worktree/port'
  */
 
-import { readFileSync, writeFileSync, existsSync, mkdirSync, realpathSync } from 'fs'
+import { readFileSync, writeFileSync, existsSync, mkdirSync, readdirSync, realpathSync } from 'fs'
 import { join, dirname, basename } from 'path'
 import { execSync } from 'child_process'
 
@@ -60,6 +60,10 @@ export function detectWorktreeName() {
     const worktreeMatch = realCwd.match(/\.worktrees[/\\]([^/\\]+)/)
     if (worktreeMatch) return worktreeMatch[1]
 
+    // Not a worktree — check the current branch name
+    const branch = execSync('git rev-parse --abbrev-ref HEAD', { encoding: 'utf8' }).trim()
+    if (branch && branch !== 'main' && branch !== 'master') return branch
+
     return 'main'
   } catch {
     return 'main'
@@ -138,3 +142,55 @@ export function slugify(name) {
     .map((s) => s.replace(/^-+|-+$/g, ''))
     .join('/')
 }
+
+/**
+ * Resolve the repo root — the directory that contains `.worktrees/`.
+ *
+ * Works whether cwd is the repo root itself or inside `.worktrees/<name>/`.
+ *
+ * @param {string} [cwd]
+ * @returns {string} absolute path to repo root
+ */
+export function repoRoot(cwd = process.cwd()) {
+  const realCwd = realpathSync(cwd)
+
+  const worktreeMatch = realCwd.match(/^(.+)[/\\]\.worktrees[/\\][^/\\]+/)
+  if (worktreeMatch) return worktreeMatch[1]
+
+  return realCwd
+}
+
+/**
+ * Resolve the full path to a worktree directory.
+ *
+ * Returns repo root for 'main', `.worktrees/<name>` otherwise.
+ *
+ * @param {string} name — worktree name
+ * @param {string} [cwd]
+ * @returns {string} absolute path
+ */
+export function worktreeDir(name, cwd) {
+  const root = repoRoot(cwd)
+  if (name === 'main') return root
+  return join(root, '.worktrees', name)
+}
+
+/**
+ * List existing worktree directory names from `.worktrees/`.
+ *
+ * Only returns directories that look like real worktrees (contain a `.git` file).
+ * Does not include 'main'.
+ *
+ * @param {string} [cwd]
+ * @returns {string[]}
+ */
+export function listWorktrees(cwd) {
+  const root = repoRoot(cwd)
+  const worktreesDir = join(root, '.worktrees')
+
+  if (!existsSync(worktreesDir)) return []
+
+  return readdirSync(worktreesDir, { withFileTypes: true })
+    .filter((d) => d.isDirectory() && existsSync(join(worktreesDir, d.name, '.git')))
+    .map((d) => d.name)
+}

package/src/worktree/port.test.js

@@ -4,7 +4,7 @@ import { join } from 'path'
 import { tmpdir } from 'os'
 
 // We test the pure functions by importing and overriding cwd
-import { portsFilePath, getPort, resolvePort, slugify } from './port.js'
+import { portsFilePath, getPort, resolvePort, slugify, repoRoot, worktreeDir, listWorktrees } from './port.js'
 
 describe('slugify', () => {
   it('lowercases and replaces dots with hyphens', () => {
@@ -130,3 +130,93 @@ describe('getPort / resolvePort', () => {
     expect(port).toBe(1235)
   })
 })
+
+describe('repoRoot', () => {
+  let tempRoot
+
+  beforeEach(() => {
+    tempRoot = realpathSync(mkdtempSync(join(tmpdir(), 'sb-root-test-')))
+    mkdirSync(join(tempRoot, '.worktrees', 'my-branch'), { recursive: true })
+  })
+
+  afterEach(() => {
+    rmSync(tempRoot, { recursive: true, force: true })
+  })
+
+  it('returns cwd when at repo root', () => {
+    expect(repoRoot(tempRoot)).toBe(tempRoot)
+  })
+
+  it('returns parent of .worktrees when inside a worktree', () => {
+    const wt = join(tempRoot, '.worktrees', 'my-branch')
+    expect(repoRoot(wt)).toBe(tempRoot)
+  })
+})
+
+describe('worktreeDir', () => {
+  let tempRoot
+
+  beforeEach(() => {
+    tempRoot = realpathSync(mkdtempSync(join(tmpdir(), 'sb-wtdir-test-')))
+    mkdirSync(join(tempRoot, '.worktrees'), { recursive: true })
+  })
+
+  afterEach(() => {
+    rmSync(tempRoot, { recursive: true, force: true })
+  })
+
+  it('returns repo root for main', () => {
+    expect(worktreeDir('main', tempRoot)).toBe(tempRoot)
+  })
+
+  it('returns .worktrees/<name> for branches', () => {
+    expect(worktreeDir('my-feature', tempRoot)).toBe(join(tempRoot, '.worktrees', 'my-feature'))
+  })
+})
+
+describe('listWorktrees', () => {
+  let tempRoot
+
+  beforeEach(() => {
+    tempRoot = realpathSync(mkdtempSync(join(tmpdir(), 'sb-list-test-')))
+  })
+
+  afterEach(() => {
+    rmSync(tempRoot, { recursive: true, force: true })
+  })
+
+  it('returns empty array when .worktrees does not exist', () => {
+    expect(listWorktrees(tempRoot)).toEqual([])
+  })
+
+  it('returns only directories with a .git file', () => {
+    const wtDir = join(tempRoot, '.worktrees')
+    mkdirSync(wtDir)
+
+    // Valid worktree — has .git file
+    mkdirSync(join(wtDir, 'valid'))
+    writeFileSync(join(wtDir, 'valid', '.git'), 'gitdir: /some/path')
+
+    // Not a worktree — no .git file
+    mkdirSync(join(wtDir, 'no-git'))
+
+    // Not a directory — file
+    writeFileSync(join(wtDir, 'ports.json'), '{}')
+
+    const result = listWorktrees(tempRoot)
+    expect(result).toEqual(['valid'])
+  })
+
+  it('returns multiple worktrees', () => {
+    const wtDir = join(tempRoot, '.worktrees')
+    mkdirSync(wtDir)
+
+    for (const name of ['alpha', 'beta', 'gamma']) {
+      mkdirSync(join(wtDir, name))
+      writeFileSync(join(wtDir, name, '.git'), 'gitdir: /some/path')
+    }
+
+    const result = listWorktrees(tempRoot)
+    expect(result.sort()).toEqual(['alpha', 'beta', 'gamma'])
+  })
+})

package/widgets.config.json

@@ -495,12 +495,11 @@
             {
               "action": "copy-as-png",
               "label": "$label:copy-png",
-              "icon": "copy"
-            },
-            {
-              "action": "copy-file-path",
-              "label": "$label:copy-path",
-              "icon": "link"
+              "icon": "copy",
+              "alt": {
+                "label": "$label:copy-path",
+                "action": "copy-file-path"
+              }
             }
           ]
         },