@dfosco/storyboard-core 4.0.0-beta.2 → 4.0.0-beta.21

package/src/cli/dev.js

@@ -1,17 +1,219 @@
 /**
- * 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 { detectWorktreeName, getPort } from '../worktree/port.js'
-import { generateCaddyfile, isCaddyRunning, reloadCaddy, readDevDomain } from './proxy.js'
+import { spawn, execFileSync } from 'child_process'
+import { existsSync } from 'fs'
+import { resolve } from 'path'
+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'
+import { hasUncommittedChanges, localBranchExists, resolveDefaultBranch } from './dev-helpers.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 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]`.
+ *
+ * When no argument is given and the repo root is on a non-main branch,
+ * prompts the user to convert it to a proper worktree.
+ *
+ * @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
+  if (!branchArg) {
+    const detectedName = detectWorktreeName()
+
+    // Already in a worktree or on main — use cwd as-is
+    const root = repoRoot()
+    const realCwd = resolve(process.cwd())
+    const isAtRoot = realCwd === resolve(root)
+    if (detectedName === 'main' || !isAtRoot) {
+      return { worktreeName: detectedName, targetCwd: process.cwd(), created: false }
+    }
+
+    // Root is on a non-main branch — check for existing worktree first
+    const branch = detectedName
+    const existingDir = worktreeDir(branch)
+    if (existsSync(resolve(existingDir, '.git'))) {
+      p.log.info(`Root is on branch "${branch}" — using existing worktree`)
+      return { worktreeName: branch, targetCwd: existingDir, created: false }
+    }
+
+    // No worktree exists — prompt the user to convert
+    p.log.warning(`Root is on branch "${branch}" instead of main.`)
+    const shouldConvert = await p.confirm({
+      message: `Convert "${branch}" to a worktree? (moves branch to .worktrees/${branch}/)`,
+      initialValue: true,
+    })
+
+    if (p.isCancel(shouldConvert) || !shouldConvert) {
+      // User declined — proceed with root as-is (legacy behavior)
+      return { worktreeName: detectedName, targetCwd: process.cwd(), created: false }
+    }
+
+    // User accepted — validate and convert
+    if (!allowCreate) {
+      p.log.error('Cannot convert — --no-create flag is set.')
+      process.exit(1)
+    }
+
+    if (hasUncommittedChanges(root)) {
+      p.log.error('Cannot convert — uncommitted changes in working tree.')
+      p.log.info('Commit or stash your changes first, then run `sb dev` again.')
+      process.exit(1)
+    }
+
+    const defaultBranch = resolveDefaultBranch(root)
+    if (!defaultBranch) {
+      p.log.error('Cannot determine default branch (main/master). Switch root manually.')
+      process.exit(1)
+    }
+
+    p.log.step(`Switching root to "${defaultBranch}"`)
+    execFileSync('git', ['checkout', defaultBranch], { cwd: root, stdio: 'inherit' })
+
+    const targetDir = createWorktree(branch, root, { newBranch: false })
+
+    // Offer to open the new worktree in VS Code
+    const shouldOpen = await p.confirm({
+      message: 'Open this worktree in VS Code?',
+      initialValue: true,
+    })
+    if (shouldOpen && !p.isCancel(shouldOpen)) {
+      try {
+        execFileSync('code', [targetDir], { stdio: 'inherit' })
+      } catch {
+        p.log.warning(`Could not open VS Code. Run: code ${targetDir}`)
+      }
+    }
+
+    return { worktreeName: branch, targetCwd: targetDir, created: true }
+  }
+
+  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'
 
@@ -19,32 +221,40 @@ 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 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 child = spawn('npx', ['vite', '--port', String(overridePort || port), ...extraArgs], {
-    env: { ...process.env, VITE_BASE_PATH: basePath },
-    stdio: ['inherit', 'pipe', 'pipe'],
-  })
+  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 in target directory
+  const renameWatcher = startRenameWatcher(targetCwd)
 
   let caddyUpdated = false
   let ready = false
+  let caddyRunning = null // cached result of isCaddyRunning()
+
+  function getCaddyRunning() {
+    if (caddyRunning === null) caddyRunning = isCaddyRunning()
+    return caddyRunning
+  }
 
   child.stdout.on('data', (data) => {
     const text = data.toString()
@@ -55,9 +265,17 @@ async function main() {
       const actualPort = Number(portMatch[1])
       caddyUpdated = true
       try {
-        const caddyfilePath = generateCaddyfile({ [worktreeName]: actualPort })
-        if (isCaddyRunning()) {
-          reloadCaddy(caddyfilePath)
+        // Try admin API first (additive, doesn't wipe other repos' routes)
+        const routeConfig = generateRouteConfig({ [worktreeName]: actualPort })
+        if (getCaddyRunning() && upsertCaddyRoute(routeConfig)) {
+          // Also write Caddyfile for future cold starts
+          generateCaddyfile({ [worktreeName]: actualPort })
+        } else {
+          // Fall back to full Caddyfile reload
+          const caddyfilePath = generateCaddyfile({ [worktreeName]: actualPort })
+          if (getCaddyRunning()) {
+            reloadCaddy(caddyfilePath)
+          }
         }
       } catch {
         // Caddy not available
@@ -76,7 +294,7 @@ async function main() {
       const timeMatch = text.match(/ready in (\d+)/i)
       const ms = timeMatch ? timeMatch[1] : ''
 
-      if (isCaddyRunning()) {
+      if (getCaddyRunning()) {
         p.log.success(proxyUrl)
       } else {
         p.log.success(directUrl)
@@ -105,6 +323,7 @@ async function main() {
   })
 
   child.on('exit', (code) => {
+    renameWatcher.close()
     if (code && code !== 0 && !ready) {
       p.log.error(`Vite exited with code ${code}`)
     }

package/src/cli/flags.js

@@ -0,0 +1,174 @@
+/**
+ * Shared CLI flag parser — converts argv into a validated flags object.
+ *
+ * Supports:
+ *   --key value       string/number value
+ *   --key=value       equals-separated
+ *   --bool            boolean true
+ *   --no-bool         boolean false (negation prefix)
+ *   --key a --key b   repeated flags → array
+ *
+ * Usage:
+ *   const { flags, missing, errors } = parseFlags(process.argv.slice(3), schema)
+ */
+
+/**
+ * @typedef {Object} FlagDef
+ * @property {'string'|'boolean'|'number'|'array'} type
+ * @property {boolean} [required]
+ * @property {*} [default]
+ * @property {string} [description]
+ * @property {string[]} [aliases] - short or alternate names (without --)
+ */
+
+/**
+ * @typedef {Object<string, FlagDef>} FlagSchema
+ */
+
+/**
+ * Parse argv tokens against a schema.
+ *
+ * @param {string[]} argv - process.argv tokens (after command words are stripped)
+ * @param {FlagSchema} schema
+ * @returns {{ flags: Object, positional: string[], missing: string[], errors: string[] }}
+ */
+export function parseFlags(argv, schema) {
+  const flags = {}
+  const positional = []
+  const errors = []
+
+  // Build alias → canonical name map
+  const aliasMap = {}
+  for (const [name, def] of Object.entries(schema)) {
+    aliasMap[name] = name
+    if (def.aliases) {
+      for (const alias of def.aliases) {
+        aliasMap[alias] = name
+      }
+    }
+  }
+
+  // Seed defaults
+  for (const [name, def] of Object.entries(schema)) {
+    if (def.default !== undefined) {
+      flags[name] = def.default
+    }
+  }
+
+  let i = 0
+  while (i < argv.length) {
+    const token = argv[i]
+
+    if (!token.startsWith('-')) {
+      positional.push(token)
+      i++
+      continue
+    }
+
+    // Strip leading dashes
+    let raw = token.replace(/^--?/, '')
+    let value
+
+    // Handle --key=value
+    const eqIdx = raw.indexOf('=')
+    if (eqIdx !== -1) {
+      value = raw.slice(eqIdx + 1)
+      raw = raw.slice(0, eqIdx)
+    }
+
+    // Handle --no-<key> negation
+    let negated = false
+    if (raw.startsWith('no-') && !aliasMap[raw]) {
+      const candidate = raw.slice(3)
+      if (aliasMap[candidate]) {
+        raw = candidate
+        negated = true
+      }
+    }
+
+    const canonical = aliasMap[raw]
+    if (!canonical) {
+      errors.push(`Unknown flag: --${raw}`)
+      i++
+      continue
+    }
+
+    const def = schema[canonical]
+
+    if (def.type === 'boolean') {
+      if (value !== undefined) {
+        // Handle --flag=true / --flag=false
+        const lower = value.toLowerCase()
+        if (lower === 'true' || lower === '1') flags[canonical] = !negated
+        else if (lower === 'false' || lower === '0') flags[canonical] = negated
+        else errors.push(`Flag --${raw} is boolean; use --${raw}, --no-${raw}, or --${raw}=true|false`)
+      } else {
+        flags[canonical] = !negated
+      }
+      i++
+      continue
+    }
+
+    // Consume next token as value if we didn't get one from `=`
+    if (value === undefined) {
+      i++
+      if (i >= argv.length) {
+        errors.push(`Flag --${raw} requires a value`)
+        continue
+      }
+      value = argv[i]
+    }
+
+    if (def.type === 'number') {
+      const num = Number(value)
+      if (Number.isNaN(num)) {
+        errors.push(`Flag --${raw} must be a number, got "${value}"`)
+      } else {
+        flags[canonical] = num
+      }
+    } else if (def.type === 'array') {
+      if (!Array.isArray(flags[canonical])) flags[canonical] = []
+      flags[canonical].push(value)
+    } else {
+      // string (or JSON for object-typed flags)
+      flags[canonical] = value
+    }
+
+    i++
+  }
+
+  // Check required
+  const missing = []
+  for (const [name, def] of Object.entries(schema)) {
+    if (def.required && (flags[name] === undefined || flags[name] === '')) {
+      missing.push(name)
+    }
+  }
+
+  return { flags, positional, missing, errors }
+}
+
+/**
+ * Check if any flags were provided (beyond defaults).
+ * Useful to decide interactive vs non-interactive mode.
+ */
+export function hasFlags(argv) {
+  return argv.some((t) => t.startsWith('-'))
+}
+
+/**
+ * Format a schema into help text lines.
+ *
+ * @param {FlagSchema} schema
+ * @returns {string}
+ */
+export function formatFlagHelp(schema) {
+  const lines = []
+  for (const [name, def] of Object.entries(schema)) {
+    const aliases = def.aliases ? def.aliases.map((a) => `-${a}`).join(', ') + ', ' : ''
+    const req = def.required ? ' (required)' : ''
+    const defVal = def.default !== undefined ? ` [default: ${def.default}]` : ''
+    lines.push(`  ${aliases}--${name.padEnd(16)} ${def.description || ''}${req}${defVal}`)
+  }
+  return lines.join('\n')
+}

package/src/cli/flags.test.js

@@ -0,0 +1,155 @@
+import { describe, it, expect } from 'vitest'
+import { parseFlags, hasFlags, formatFlagHelp } from './flags.js'
+
+const testSchema = {
+  name: { type: 'string', required: true, description: 'Name', aliases: ['n'] },
+  title: { type: 'string', description: 'Title', aliases: ['t'] },
+  count: { type: 'number', description: 'Count', default: 0 },
+  verbose: { type: 'boolean', description: 'Verbose', default: false },
+  tags: { type: 'array', description: 'Tags', aliases: ['g'] },
+}
+
+describe('parseFlags', () => {
+  it('parses --key value pairs', () => {
+    const { flags } = parseFlags(['--name', 'hello', '--title', 'world'], testSchema)
+    expect(flags.name).toBe('hello')
+    expect(flags.title).toBe('world')
+  })
+
+  it('parses --key=value syntax', () => {
+    const { flags } = parseFlags(['--name=hello'], testSchema)
+    expect(flags.name).toBe('hello')
+  })
+
+  it('parses short aliases', () => {
+    const { flags } = parseFlags(['-n', 'hello', '-t', 'world'], testSchema)
+    expect(flags.name).toBe('hello')
+    expect(flags.title).toBe('world')
+  })
+
+  it('parses boolean flags', () => {
+    const { flags } = parseFlags(['--verbose', '--name', 'x'], testSchema)
+    expect(flags.verbose).toBe(true)
+  })
+
+  it('parses --no- negation for booleans', () => {
+    const { flags } = parseFlags(['--no-verbose', '--name', 'x'], testSchema)
+    expect(flags.verbose).toBe(false)
+  })
+
+  it('parses --flag=false for booleans', () => {
+    const { flags } = parseFlags(['--verbose=false', '--name', 'x'], testSchema)
+    expect(flags.verbose).toBe(false)
+  })
+
+  it('parses --flag=true for booleans', () => {
+    const { flags } = parseFlags(['--verbose=true', '--name', 'x'], testSchema)
+    expect(flags.verbose).toBe(true)
+  })
+
+  it('parses --no-flag=false as double negation (true)', () => {
+    const { flags } = parseFlags(['--no-verbose=false', '--name', 'x'], testSchema)
+    expect(flags.verbose).toBe(true)
+  })
+
+  it('reports error for invalid boolean value', () => {
+    const { errors } = parseFlags(['--verbose=maybe', '--name', 'x'], testSchema)
+    expect(errors).toHaveLength(1)
+    expect(errors[0]).toContain('boolean')
+  })
+
+  it('parses number flags', () => {
+    const { flags } = parseFlags(['--name', 'x', '--count', '42'], testSchema)
+    expect(flags.count).toBe(42)
+  })
+
+  it('reports error for non-numeric number flag', () => {
+    const { errors } = parseFlags(['--name', 'x', '--count', 'abc'], testSchema)
+    expect(errors).toHaveLength(1)
+    expect(errors[0]).toContain('must be a number')
+  })
+
+  it('collects repeated flags into arrays', () => {
+    const { flags } = parseFlags(['--name', 'x', '-g', 'a', '-g', 'b'], testSchema)
+    expect(flags.tags).toEqual(['a', 'b'])
+  })
+
+  it('collects positional arguments', () => {
+    const { positional } = parseFlags(['sticky-note', '--name', 'x'], testSchema)
+    expect(positional).toEqual(['sticky-note'])
+  })
+
+  it('reports missing required flags', () => {
+    const { missing } = parseFlags(['--title', 'hello'], testSchema)
+    expect(missing).toContain('name')
+  })
+
+  it('does not report missing when required flag is provided', () => {
+    const { missing } = parseFlags(['--name', 'hello'], testSchema)
+    expect(missing).not.toContain('name')
+  })
+
+  it('reports unknown flags', () => {
+    const { errors } = parseFlags(['--name', 'x', '--unknown', 'y'], testSchema)
+    expect(errors).toHaveLength(1)
+    expect(errors[0]).toContain('Unknown flag')
+  })
+
+  it('applies defaults', () => {
+    const { flags } = parseFlags(['--name', 'x'], testSchema)
+    expect(flags.count).toBe(0)
+    expect(flags.verbose).toBe(false)
+  })
+
+  it('reports error when value flag has no value', () => {
+    const { errors } = parseFlags(['--name'], testSchema)
+    expect(errors).toHaveLength(1)
+    expect(errors[0]).toContain('requires a value')
+  })
+
+  it('returns empty results for empty argv', () => {
+    const { flags, positional, missing, errors } = parseFlags([], testSchema)
+    expect(positional).toEqual([])
+    expect(errors).toEqual([])
+    expect(missing).toContain('name')
+    expect(flags.count).toBe(0)
+  })
+})
+
+describe('hasFlags', () => {
+  it('returns true when argv has flags', () => {
+    expect(hasFlags(['--name', 'x'])).toBe(true)
+  })
+
+  it('returns true for short flags', () => {
+    expect(hasFlags(['-n', 'x'])).toBe(true)
+  })
+
+  it('returns false when no flags', () => {
+    expect(hasFlags(['positional'])).toBe(false)
+  })
+
+  it('returns false for empty argv', () => {
+    expect(hasFlags([])).toBe(false)
+  })
+})
+
+describe('formatFlagHelp', () => {
+  it('includes flag names and descriptions', () => {
+    const output = formatFlagHelp(testSchema)
+    expect(output).toContain('--name')
+    expect(output).toContain('Name')
+    expect(output).toContain('(required)')
+  })
+
+  it('includes aliases', () => {
+    const output = formatFlagHelp(testSchema)
+    expect(output).toContain('-n')
+  })
+
+  it('includes defaults', () => {
+    const output = formatFlagHelp(testSchema)
+    expect(output).toContain('[default: 0]')
+    expect(output).toContain('[default: false]')
+  })
+})