@dfosco/storyboard 0.7.0 → 0.8.1

package/src/core/workleaf/delete.js

@@ -0,0 +1,101 @@
+/**
+ * Delete a workleaf without merging.
+ *
+ * Identical to `workleaf merge` minus the squash + commit steps. Used
+ * to abandon a workleaf entirely — useful when an experiment didn't
+ * pan out or when you want to free a port without preserving the work.
+ *
+ * Prompts for confirmation unless --yes is passed.
+ */
+
+import * as p from '@clack/prompts'
+import { existsSync } from 'node:fs'
+import { resolve } from 'node:path'
+import { repoRoot } from '../worktree/port.js'
+import { detectWorkleafContext, workleafDir, listWorkleafs, parentOfWorkleaf } from './paths.js'
+import { cleanupWorkleaf, hasDirtyWorkingTree } from './cleanup.js'
+import { dim, bold, green, yellow } from '../cli/intro.js'
+import { parseFlags } from '../cli/flags.js'
+
+const flagSchema = {
+  yes: { type: 'boolean', default: false, description: 'Skip interactive confirmation' },
+  force: { type: 'boolean', default: false, description: 'Delete even if the workleaf has uncommitted changes' },
+}
+
+function resolveTarget(positionalName, root) {
+  if (positionalName) {
+    const branchInfo = parentOfWorkleaf(positionalName)
+    if (branchInfo) {
+      const dir = workleafDir(branchInfo.parent, branchInfo.slug, root)
+      return { parent: branchInfo.parent, slug: branchInfo.slug, branch: positionalName, dir, root }
+    }
+    const matches = listWorkleafs(root).filter((w) => w.slug === positionalName)
+    if (matches.length === 0) {
+      p.log.error(`No workleaf named "${positionalName}" found.`)
+      process.exit(1)
+    }
+    if (matches.length > 1) {
+      p.log.error(`Multiple workleafs match "${positionalName}":`)
+      for (const m of matches) console.log(`  ${m.branch}`)
+      process.exit(1)
+    }
+    const m = matches[0]
+    return { parent: m.parent, slug: m.slug, branch: m.branch, dir: m.dir, root }
+  }
+  const ctx = detectWorkleafContext()
+  if (!ctx.inWorkleaf) {
+    p.log.error('Not inside a workleaf — pass a name or cd into one.')
+    p.log.info(`Usage: ${green('npx storyboard workleaf delete <name>')}`)
+    process.exit(1)
+  }
+  return { parent: ctx.parent, slug: ctx.slug, branch: ctx.branch, dir: ctx.dir, root }
+}
+
+export async function runDelete(argv = process.argv.slice(4)) {
+  const { flags, positional } = parseFlags(argv, flagSchema)
+  const root = repoRoot()
+  const target = resolveTarget(positional[0], root)
+  const { branch, dir } = target
+
+  p.intro('storyboard workleaf delete')
+  p.log.info(`${dim('workleaf:')} ${bold(branch)}`)
+
+  if (!existsSync(resolve(dir, '.git'))) {
+    p.log.warn(`Workleaf directory missing: ${dim(dir)} — cleaning up registry anyway.`)
+  } else if (hasDirtyWorkingTree(dir) && !flags.force) {
+    p.log.error(`Workleaf has uncommitted changes — pass ${green('--force')} to discard them.`)
+    process.exit(1)
+  }
+
+  if (!flags.yes) {
+    const confirm = await p.confirm({
+      message: `Permanently delete ${yellow(branch)}? This discards any unmerged commits.`,
+      initialValue: false,
+    })
+    if (p.isCancel(confirm) || !confirm) {
+      p.cancel('Cancelled')
+      process.exit(0)
+    }
+  }
+
+  // chdir out of the workleaf BEFORE cleanup so helpers that call
+  // realpathSync(cwd) don't ENOENT when the dir is gone.
+  try {
+    const safeParent = target.parent === 'main' ? root : resolve(root, 'worktrees', target.parent)
+    if (existsSync(safeParent)) process.chdir(safeParent)
+    else process.chdir(root)
+  } catch { /* cwd will stay where it is */ }
+
+  p.log.step('Cleaning up workleaf')
+  const { stopped } = cleanupWorkleaf({ branch, dir, root })
+
+  p.note(
+    [
+      `  ${green('✓')} stopped ${stopped} dev server${stopped === 1 ? '' : 's'}`,
+      `  ${green('✓')} removed ${dim(dir.replace(root + '/', ''))}`,
+      `  ${green('✓')} deleted branch ${dim(branch)}`,
+    ].join('\n'),
+    `${bold(branch)} deleted`
+  )
+  p.outro('')
+}

package/src/core/workleaf/list.js

@@ -0,0 +1,57 @@
+/**
+ * List workleafs across the repo, grouped by parent, with live server info.
+ *
+ * Output shape:
+ *
+ *   storyboard workleaf list
+ *
+ *   main
+ *     ● workleaf--quick-fix    :1235   http://localhost:1235/storyboard/   (pid 12345)
+ *     ○ workleaf--archive       (no server)
+ *
+ *   4.3.0
+ *     ● workleaf--bench         :1236   http://localhost:1236/storyboard/   (pid 23456)
+ *
+ * `●` = live server, `○` = no live server.
+ */
+
+import * as p from '@clack/prompts'
+import { listWorkleafs } from './paths.js'
+import { findByWorktree } from '../worktree/serverRegistry.js'
+import { dim, bold, green } from '../cli/intro.js'
+
+export function runList() {
+  const all = listWorkleafs()
+
+  if (all.length === 0) {
+    p.log.info('No workleafs yet.')
+    p.log.info(dim('Create one with: npx storyboard workleaf create <name>'))
+    return
+  }
+
+  // Group by parent, preserving insertion order from listWorkleafs (already
+  // grouped by readdir order which is parent-first).
+  const byParent = new Map()
+  for (const w of all) {
+    if (!byParent.has(w.parent)) byParent.set(w.parent, [])
+    byParent.get(w.parent).push(w)
+  }
+
+  console.log()
+  for (const [parent, leaves] of byParent) {
+    console.log(`  ${bold(parent)}`)
+    for (const w of leaves) {
+      const servers = findByWorktree(w.branch)
+      if (servers.length > 0) {
+        const s = servers[0]
+        const url = `http://localhost:${s.port}/storyboard/`
+        console.log(`    ${green('●')} workleaf--${w.slug.padEnd(28)} :${String(s.port).padEnd(5)}  ${green(url)}  ${dim(`(pid ${s.pid})`)}`)
+      } else {
+        console.log(`    ${dim('○')} workleaf--${w.slug.padEnd(28)} ${dim('(no server)')}`)
+      }
+    }
+    console.log()
+  }
+
+  p.log.info(dim('Tip: storyboard workleaf merge <name>  squashes & cleans up'))
+}

package/src/core/workleaf/merge.js

@@ -0,0 +1,238 @@
+/**
+ * Merge a workleaf into its parent (squash) and clean it up.
+ *
+ * Lifecycle:
+ *   1. Resolve the target workleaf — explicit name positional OR auto-detect
+ *      from cwd via detectWorkleafContext.
+ *   2. Refuse if the workleaf has uncommitted changes.
+ *   3. Verify the parent worktree still exists.
+ *   4. Preflight a squash-merge probe in the parent (and bail cleanly
+ *      on conflict — never leave the parent in MERGING state).
+ *   5. Real `git merge --squash <branch>` in the parent.
+ *   6. Commit with a generated message + Copilot co-author trailer.
+ *   7. Cleanup: stop dev server, remove worktree, delete branch, release port.
+ *
+ * If we're inside the workleaf being merged, we move cwd to the parent
+ * directory after merge so the user isn't left in a deleted directory.
+ */
+
+import * as p from '@clack/prompts'
+import { execFileSync } from 'node:child_process'
+import { existsSync } from 'node:fs'
+import { resolve } from 'node:path'
+import { repoRoot, worktreeDir } from '../worktree/port.js'
+import {
+  detectWorkleafContext,
+  workleafBranchName,
+  workleafDir,
+  listWorkleafs,
+  parentOfWorkleaf,
+} from './paths.js'
+import { cleanupWorkleaf, currentBranch, hasDirtyWorkingTree } from './cleanup.js'
+import { dim, bold, green } from '../cli/intro.js'
+import { parseFlags } from '../cli/flags.js'
+
+const flagSchema = {
+  message: { type: 'string', description: 'Override the squash commit message' },
+  'no-commit': { type: 'boolean', default: false, description: 'Stage the squash but do not commit (caller commits)' },
+  yes: { type: 'boolean', default: false, description: 'Skip interactive confirmation' },
+}
+
+const COAUTHOR_TRAILER = 'Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>'
+
+/**
+ * Locate the target workleaf by name (positional) OR by inspecting cwd.
+ * Returns { parent, slug, branch, dir, root } or exits with an error.
+ */
+function resolveTarget(positionalName, root) {
+  // Explicit positional wins
+  if (positionalName) {
+    // The user can pass either a slug OR a full branch name. Disambiguate.
+    const branchInfo = parentOfWorkleaf(positionalName)
+    if (branchInfo) {
+      const dir = workleafDir(branchInfo.parent, branchInfo.slug, root)
+      return {
+        parent: branchInfo.parent,
+        slug: branchInfo.slug,
+        branch: positionalName,
+        dir,
+        root,
+      }
+    }
+    // Treat as slug — find a matching workleaf, prefer one parented by
+    // the current worktree if multiple match.
+    const matches = listWorkleafs(root).filter((w) => w.slug === positionalName)
+    if (matches.length === 0) {
+      p.log.error(`No workleaf named "${positionalName}" found.`)
+      p.log.info(`List workleafs with: ${green('npx storyboard workleaf list')}`)
+      process.exit(1)
+    }
+    if (matches.length > 1) {
+      p.log.error(`Multiple workleafs match "${positionalName}":`)
+      for (const m of matches) console.log(`  ${m.branch}  ${dim(m.dir)}`)
+      p.log.info(`Pass the full branch name: ${green('npx storyboard workleaf merge <parent>--workleaf--<slug>')}`)
+      process.exit(1)
+    }
+    const m = matches[0]
+    return { parent: m.parent, slug: m.slug, branch: m.branch, dir: m.dir, root }
+  }
+
+  // Auto-detect from cwd
+  const ctx = detectWorkleafContext()
+  if (!ctx.inWorkleaf) {
+    p.log.error('Not inside a workleaf — pass a name or cd into one.')
+    p.log.info(`Usage: ${green('npx storyboard workleaf merge <name>')}`)
+    process.exit(1)
+  }
+  return { parent: ctx.parent, slug: ctx.slug, branch: ctx.branch, dir: ctx.dir, root }
+}
+
+/**
+ * Preflight: probe whether `git merge --squash <branch>` in the parent
+ * would succeed. We do the probe by running the actual merge command,
+ * checking the result, and aborting the merge state if anything was
+ * staged (i.e. we always leave the parent in its pre-probe state).
+ *
+ * Returns { ok: true } on clean merge OR { ok: false, conflicts: [...] }
+ * on conflict. The parent is reset either way.
+ */
+function preflightSquash(parentDir, branch) {
+  try {
+    // --squash leaves the changes staged but does NOT create a merge commit
+    // and does NOT set MERGE_HEAD, so on success we just need to reset.
+    execFileSync('git', ['merge', '--squash', '--no-commit', branch], {
+      cwd: parentDir,
+      stdio: 'pipe',
+    })
+    // Reset the staged changes so the probe is non-destructive.
+    execFileSync('git', ['reset', '--hard', 'HEAD'], { cwd: parentDir, stdio: 'pipe' })
+    return { ok: true }
+  } catch (err) {
+    // Capture conflict markers, then reset state.
+    let conflicts = []
+    try {
+      const out = execFileSync('git', ['diff', '--name-only', '--diff-filter=U'], {
+        cwd: parentDir,
+        encoding: 'utf8',
+      }).trim()
+      conflicts = out ? out.split('\n') : []
+    } catch { /* ignore */ }
+    // Always reset to leave the parent clean.
+    try { execFileSync('git', ['reset', '--hard', 'HEAD'], { cwd: parentDir, stdio: 'pipe' }) } catch { /* ignore */ }
+    return { ok: false, conflicts, error: err.message }
+  }
+}
+
+export async function runMerge(argv = process.argv.slice(4)) {
+  const { flags, positional } = parseFlags(argv, flagSchema)
+  const root = repoRoot()
+  const target = resolveTarget(positional[0], root)
+  const { parent, slug, branch, dir } = target
+
+  p.intro('storyboard workleaf merge')
+  p.log.info(`${dim('workleaf:')} ${bold(branch)}`)
+
+  // Verify workleaf exists on disk
+  if (!existsSync(resolve(dir, '.git'))) {
+    p.log.error(`Workleaf directory missing: ${dim(dir)}`)
+    process.exit(1)
+  }
+
+  // Refuse on dirty workleaf
+  if (hasDirtyWorkingTree(dir)) {
+    p.log.error(`Workleaf has uncommitted changes — commit or stash them first.`)
+    p.log.info(`  ${dim(`cd ${dir}`)}`)
+    p.log.info(`  ${green('git status')}`)
+    process.exit(1)
+  }
+
+  // Verify parent worktree
+  const parentDir = parent === 'main' ? root : worktreeDir(parent, root)
+  if (!existsSync(resolve(parentDir, '.git'))) {
+    p.log.error(`Parent worktree "${parent}" is gone.`)
+    p.log.info(`Recreate it (${green('npx storyboard branch ' + parent)}) and re-run, or abandon with`)
+    p.log.info(`  ${green(`npx storyboard workleaf delete ${slug}`)}`)
+    process.exit(1)
+  }
+  // Refuse if parent is on a different branch than expected — that
+  // means the user is intentionally on a wildcard branch and probably
+  // doesn't want a squash here.
+  const parentBranch = currentBranch(parentDir)
+  if (!parentBranch) {
+    p.log.error(`Could not determine current branch of parent worktree at ${dim(parentDir)}`)
+    process.exit(1)
+  }
+  if (hasDirtyWorkingTree(parentDir)) {
+    p.log.error(`Parent worktree "${parent}" has uncommitted changes — commit or stash them first.`)
+    p.log.info(`  ${dim(`cd ${parentDir}`)}`)
+    p.log.info(`  ${green('git status')}`)
+    process.exit(1)
+  }
+
+  // Preflight squash
+  p.log.step('Checking that the squash will apply cleanly…')
+  const probe = preflightSquash(parentDir, branch)
+  if (!probe.ok) {
+    p.log.error('Squash would conflict with the parent.')
+    if (probe.conflicts && probe.conflicts.length > 0) {
+      for (const c of probe.conflicts) console.log(`  - ${c}`)
+    }
+    p.log.info(`Resolve manually with:`)
+    p.log.info(`  ${dim(`cd ${parentDir} && git merge --squash ${branch}`)}`)
+    process.exit(1)
+  }
+
+  // Real merge
+  p.log.step(`Squash-merging into ${bold(parentBranch)}`)
+  try {
+    execFileSync('git', ['merge', '--squash', branch], { cwd: parentDir, stdio: 'pipe' })
+  } catch (err) {
+    p.log.error(`Real squash failed (this shouldn't happen after a clean preflight): ${err.message}`)
+    process.exit(1)
+  }
+
+  // Commit (or stage-only)
+  let sha = null
+  if (flags['no-commit']) {
+    p.log.success(`Squash staged in ${bold(parentBranch)} — commit it yourself`)
+  } else {
+    const message = flags.message || `feat: ${slug} (workleaf squash)`
+    try {
+      execFileSync('git', ['commit', '-m', `${message}\n\n${COAUTHOR_TRAILER}`], {
+        cwd: parentDir,
+        stdio: 'pipe',
+      })
+      sha = execFileSync('git', ['rev-parse', '--short', 'HEAD'], { cwd: parentDir, encoding: 'utf8' }).trim()
+      p.log.success(`Committed as ${green(sha)}: ${dim(message)}`)
+    } catch (err) {
+      p.log.error(`Commit failed: ${err.message}`)
+      p.log.warn(`Squash is staged in ${parentDir} but uncommitted. Resolve manually before re-running.`)
+      process.exit(1)
+    }
+  }
+
+  // CRITICAL: chdir to the parent BEFORE cleanup so cwd is not inside
+  // the directory we're about to delete. Without this, every subsequent
+  // call into helpers that touch cwd (releasePort -> portsFilePath ->
+  // realpathSync) hits ENOENT.
+  try { process.chdir(parentDir) } catch { /* parent may also be gone */ }
+
+  p.log.step('Cleaning up workleaf')
+  const { stopped } = cleanupWorkleaf({ branch, dir, root })
+
+  p.note(
+    [
+      `  ${green('✓')} squashed into ${bold(parentBranch)}${sha ? ` as ${green(sha)}` : ''}`,
+      `  ${green('✓')} stopped ${stopped} dev server${stopped === 1 ? '' : 's'}`,
+      `  ${green('✓')} removed ${dim(dir.replace(root + '/', ''))}`,
+      `  ${green('✓')} deleted branch ${dim(branch)}`,
+      '',
+      `  cd to the parent: ${green(`cd ${parentDir.replace(root + '/', '') || '.'}`)}`,
+    ].join('\n'),
+    `${bold(branch)} merged`
+  )
+  p.outro('')
+}
+
+// Re-export the branch-name helper for symmetry
+export { workleafBranchName }

package/src/core/workleaf/paths.js

@@ -0,0 +1,146 @@
+/**
+ * Workleaf path helpers.
+ *
+ * A workleaf is an ephemeral sub-worktree owned by a parent worktree (or
+ * main). It lives at:
+ *
+ *   <repo-root>/workleafs/<parent>/workleaf--<slug>/
+ *
+ * The parent name is encoded in the path — no metadata file is needed.
+ * Workleaves cannot be nested: spawning a workleaf from inside another
+ * workleaf is refused at the CLI layer using `detectWorkleafContext`.
+ *
+ * Branch naming convention is `<parent>--workleaf--<slug>` so the branch
+ * is self-describing in `git branch` output even without spatial context.
+ *
+ * This module is intentionally pure and side-effect-free so it can be
+ * unit-tested without touching the filesystem (apart from the listing
+ * helper, which obviously must read disk).
+ */
+
+import { existsSync, readdirSync, realpathSync } from 'fs'
+import { join } from 'path'
+import { repoRoot, slugify } from '../worktree/port.js'
+
+/** Literal prefix every workleaf directory and branch slug carries. */
+export const WORKLEAF_PREFIX = 'workleaf--'
+
+/** Branch convention: `<parent>--workleaf--<slug>`. */
+export const WORKLEAF_BRANCH_SEPARATOR = '--workleaf--'
+
+/**
+ * Build the absolute on-disk path for a workleaf.
+ *
+ * @param {string} parent — parent worktree name (e.g. 'main' or '4.3.0')
+ * @param {string} name — user-supplied workleaf name (will be slugified)
+ * @param {string} [cwd] — for tests; falls back to process.cwd()
+ * @returns {string} absolute path
+ */
+export function workleafDir(parent, name, cwd) {
+  const root = repoRoot(cwd)
+  const slug = slugify(name)
+  return join(root, 'workleafs', parent, WORKLEAF_PREFIX + slug)
+}
+
+/**
+ * Compose the git branch name for a workleaf.
+ *
+ * @param {string} parent
+ * @param {string} name
+ * @returns {string} e.g. '4.3.0--workleaf--quick-fix'
+ */
+export function workleafBranchName(parent, name) {
+  const slug = slugify(name)
+  return `${parent}${WORKLEAF_BRANCH_SEPARATOR}${slug}`
+}
+
+/**
+ * Inverse of {@link workleafBranchName}. Splits `parent--workleaf--slug`
+ * into its parts. Uses the LAST occurrence of `--workleaf--` so the
+ * function survives parent names that contain `--workleaf--` literally
+ * (unlikely, but cheap to handle).
+ *
+ * Returns null if the input is not a workleaf branch.
+ */
+export function parentOfWorkleaf(branchName) {
+  if (typeof branchName !== 'string') return null
+  const idx = branchName.lastIndexOf(WORKLEAF_BRANCH_SEPARATOR)
+  if (idx <= 0) return null
+  const parent = branchName.slice(0, idx)
+  const slug = branchName.slice(idx + WORKLEAF_BRANCH_SEPARATOR.length)
+  if (!parent || !slug) return null
+  return { parent, slug }
+}
+
+/**
+ * Detect whether the given cwd is inside a workleaf, and if so, which
+ * parent and slug it belongs to.
+ *
+ * Returns:
+ *   { inWorkleaf: true,  parent, slug, branch, dir, root } when inside
+ *   { inWorkleaf: false }                                  when outside
+ *
+ * Uses realpathSync to resolve symlinks before pattern-matching — same
+ * convention as `worktree/port.js`. Falls back to the raw cwd if the
+ * path does not exist on disk yet (e.g. during dry-run tests).
+ */
+export function detectWorkleafContext(cwd = process.cwd()) {
+  let realCwd
+  try {
+    realCwd = realpathSync(cwd)
+  } catch {
+    realCwd = cwd
+  }
+
+  // Match <root>/workleafs/<parent>/workleaf--<slug> (anywhere within it).
+  // Capture groups: 1=root, 2=parent, 3=slug.
+  const re = new RegExp(`^(.+)[/\\\\]workleafs[/\\\\]([^/\\\\]+)[/\\\\]${WORKLEAF_PREFIX}([^/\\\\]+)`)
+  const m = realCwd.match(re)
+  if (!m) return { inWorkleaf: false }
+
+  const [, root, parent, slug] = m
+  return {
+    inWorkleaf: true,
+    parent,
+    slug,
+    branch: workleafBranchName(parent, slug),
+    dir: join(root, 'workleafs', parent, WORKLEAF_PREFIX + slug),
+    root,
+  }
+}
+
+/**
+ * Enumerate every workleaf on disk under <repoRoot>/workleafs/, grouped
+ * by parent. Skips entries that don't look like real git worktrees
+ * (must contain a `.git` file at the workleaf root).
+ *
+ * @param {string} [cwd]
+ * @returns {Array<{ parent: string, slug: string, branch: string, dir: string }>}
+ */
+export function listWorkleafs(cwd) {
+  const root = repoRoot(cwd)
+  const base = join(root, 'workleafs')
+  if (!existsSync(base)) return []
+
+  const out = []
+  for (const parentEntry of readdirSync(base, { withFileTypes: true })) {
+    if (!parentEntry.isDirectory()) continue
+    const parent = parentEntry.name
+    const parentDir = join(base, parent)
+    for (const child of readdirSync(parentDir, { withFileTypes: true })) {
+      if (!child.isDirectory()) continue
+      if (!child.name.startsWith(WORKLEAF_PREFIX)) continue
+      const dir = join(parentDir, child.name)
+      // A worktree-managed directory has a `.git` file (not dir) inside.
+      if (!existsSync(join(dir, '.git'))) continue
+      const slug = child.name.slice(WORKLEAF_PREFIX.length)
+      out.push({
+        parent,
+        slug,
+        branch: workleafBranchName(parent, slug),
+        dir,
+      })
+    }
+  }
+  return out
+}