@dfosco/storyboard-core 4.2.6 → 4.2.7

package/package.json

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

package/scaffold/AGENTS.md

@@ -66,7 +66,7 @@ The default location is in `.agents/plans`, but the user may ask for a specific
 
 - **create** (`.agents/skills/create/SKILL.md`) — Walks through creating Storyboard assets: prototype, external prototype, flow, page, canvas, object, or record.
 
-- **worktree** (`.agents/skills/worktree/SKILL.md`) — Creates a git worktree in `.worktrees/<branch-name>` and switches into it.
+- **worktree** (`.agents/skills/worktree/SKILL.md`) — Creates a git worktree in `worktrees/<branch-name>` and switches into it.
 
 - **tools** (`.agents/skills/tools/SKILL.md`) — Reference for creating toolbar tools: config schema, handlers, surfaces, and render types.
 

package/scaffold/skills/ship/SKILL.md

@@ -34,7 +34,7 @@ Invoke the **worktree** skill to create a git worktree for the feature branch.
 - If the user provided an explicit branch name, use that instead.
 - Use `ask_user` to confirm the branch name before creating the worktree.
 
-After the worktree is created, all subsequent work happens inside `.worktrees/<branch-name>` **at the repository root** (use `git rev-parse --show-toplevel` to find the root). Never create worktrees nested inside other worktrees.
+After the worktree is created, all subsequent work happens inside `worktrees/<branch-name>` **at the repository root** (use `git rev-parse --show-toplevel` to find the root). Never create worktrees nested inside other worktrees.
 
 ### Step 2: Plan the feature
 

package/scaffold/skills/worktree/SKILL.md

@@ -4,7 +4,7 @@
 
 ## What This Does
 
-Creates a git worktree for a given branch name inside `.worktrees/` and switches into it.
+Creates a git worktree for a given branch name inside `worktrees/` and switches into it.
 
 ---
 
@@ -12,35 +12,18 @@ Creates a git worktree for a given branch name inside `.worktrees/` and switches
 
 When the user asks for a worktree named `<branch-name>`:
 
-### Step 0: Slugify the branch name
-
-Sanitize the branch name to avoid filesystem and subdomain issues:
-
-1. Convert to lowercase.
-2. Replace dots (`.`), spaces, underscores, and other non-alphanumeric characters (except `-` and `/`) with hyphens.
-3. Collapse consecutive hyphens into one.
-4. Trim leading/trailing hyphens from each segment.
-
-**Examples:**
-- `feature.v2` → `feature-v2`
-- `v3.11.0` → `v3-11-0`
-- `my_cool.feature` → `my-cool-feature`
-- `UPPER.Case` → `upper-case`
-
-Use the slugified name for both the **branch name** and **worktree directory** throughout the rest of the workflow.
-
 ### Step 1: Create the worktree
 
 If the branch already exists locally or on the remote:
 
 ```bash
-git worktree add .worktrees/<branch-name> <branch-name>
+git worktree add worktrees/<branch-name> <branch-name>
 ```
 
 If the branch does NOT exist yet, create it from the current HEAD:
 
 ```bash
-git worktree add .worktrees/<branch-name> -b <branch-name>
+git worktree add worktrees/<branch-name> -b <branch-name>
 ```
 
 ### Step 2: Register a dev-server port
@@ -59,12 +42,12 @@ Or if the project has `scripts/worktree-port.js`:
 node scripts/worktree-port.js <branch-name>
 ```
 
-This writes to `.worktrees/ports.json` (gitignored). The dev server (`npx storyboard-dev`) reads from this file automatically.
+This writes to `worktrees/ports.json` (gitignored). The dev server (`npx storyboard-dev`) reads from this file automatically.
 
 ### Step 3: Change into the worktree directory
 
 ```bash
-cd .worktrees/<branch-name>
+cd worktrees/<branch-name>
 ```
 
 All subsequent commands in the session should run from this directory.
@@ -99,9 +82,9 @@ The dev server automatically uses the port assigned in Step 2.
 
 ## Notes
 
-- Worktrees live in `.worktrees/` at the repo root — this directory is already gitignored.
+- Worktrees live in `worktrees/` at the repo root — this directory is already gitignored.
 - The branch name comes from the user's request (e.g., "create worktree comments-redo" → branch is `comments-redo`).
 - **Always slugify** the branch name (Step 0) before creating the worktree. Dots cause issues with subdomain routing and are replaced with hyphens.
 - If the worktree already exists, inform the user and `cd` into it instead of recreating it.
 - Port assignments are stable — once a worktree gets a port, it keeps it across restarts.
-- To see all assigned ports, check `.worktrees/ports.json`.
+- To see all assigned ports, check `worktrees/ports.json`.

package/src/canvas/terminal-config.js

@@ -42,9 +42,9 @@ function readDevDomain() {
 /** Detect worktree name */
 function getWorktreeName() {
   try {
-    // Check if we're in a .worktrees/ directory
+    // Check if we're in a worktrees/ directory
     const cwd = rootDir
-    const match = cwd.match(/\.worktrees\/([^/]+)/)
+    const match = cwd.match(/worktrees\/([^/]+)/)
     return match ? match[1] : 'main'
   } catch { return 'main' }
 }

package/src/cli/branch.js

@@ -105,7 +105,7 @@ export async function runBranchGuide(branchArg) {
     p.log.success(`Worktree ${bold(targetBranch)} already exists`)
     p.note(
       [
-        `  ${green('cd')} ${dim(`.worktrees/${targetBranch}`)}`,
+        `  ${green('cd')} ${dim(`worktrees/${targetBranch}`)}`,
         `  ${green('npx storyboard dev')}  ${dim('to start developing')}`,
       ].join('\n'),
       'Ready to go'
@@ -156,7 +156,7 @@ export async function runBranchGuide(branchArg) {
   }
 
   // Create the worktree
-  const targetDir = resolve(root, '.worktrees', targetBranch)
+  const targetDir = resolve(root, 'worktrees', targetBranch)
   const spin = p.spinner()
 
   try {
@@ -164,9 +164,9 @@ export async function runBranchGuide(branchArg) {
       ? ['worktree', 'add', targetDir, '-b', targetBranch]
       : ['worktree', 'add', targetDir, targetBranch]
 
-    spin.start(`Creating worktree .worktrees/${targetBranch}`)
+    spin.start(`Creating worktree worktrees/${targetBranch}`)
     execFileSync('git', gitArgs, { cwd: root, stdio: 'pipe' })
-    spin.stop(`Worktree created: .worktrees/${targetBranch}`)
+    spin.stop(`Worktree created: worktrees/${targetBranch}`)
   } catch (err) {
     spin.stop('Failed to create worktree')
     p.log.error(err.message || 'git worktree add failed')
@@ -211,13 +211,13 @@ export async function runBranchGuide(branchArg) {
 
   // 7. Summary
   const lines = [
-    `  Your branch is set up as a worktree in ${green(`.worktrees/${targetBranch}`)}`,
+    `  Your branch is set up as a worktree in ${green(`worktrees/${targetBranch}`)}`,
   ]
   if (didStash) {
     lines.push(`  Your uncommitted work has been safely moved`)
   }
   lines.push('')
-  lines.push(`  ${green('cd')} ${dim(`.worktrees/${targetBranch}`)}`)
+  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!')}`)

package/src/cli/code.js

@@ -4,7 +4,7 @@
  * Usage:
  *   storyboard code              # open current worktree or repo root
  *   storyboard code main         # open repo root
- *   storyboard code <branch>     # open .worktrees/<branch>/
+ *   storyboard code <branch>     # open worktrees/<branch>/
  */
 
 import * as p from '@clack/prompts'
@@ -33,7 +33,7 @@ if (!branch) {
   const name = detectWorktreeName()
   const dir = name === 'main' ? root : worktreeDir(name)
   if (openInCode(dir)) {
-    p.outro(`Opened ${name === 'main' ? 'repo root' : `.worktrees/${name}/`}`)
+    p.outro(`Opened ${name === 'main' ? 'repo root' : `worktrees/${name}/`}`)
   } else {
     p.log.error('Could not open VS Code. Is the `code` CLI installed?')
     p.log.info('Run `npx storyboard setup` to install it, or open VS Code and run:')
@@ -59,7 +59,7 @@ if (!branch) {
     process.exit(1)
   }
   if (openInCode(dir)) {
-    p.outro(`Opened .worktrees/${branch}/`)
+    p.outro(`Opened worktrees/${branch}/`)
   } else {
     p.log.error('Could not open VS Code.')
     process.exit(1)

package/src/cli/dev.js

@@ -60,13 +60,13 @@ function remoteBranchExists(name, cwd) {
  * @returns {string} path to the new worktree directory
  */
 function createWorktree(name, root, { newBranch = false } = {}) {
-  const targetDir = resolve(root, '.worktrees', name)
+  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}`)
+  p.log.step(`Creating worktree: worktrees/${name}`)
   execFileSync('git', gitArgs, { cwd: root, stdio: 'inherit' })
 
   p.log.step('Installing dependencies…')
@@ -112,7 +112,7 @@ async function resolveDevTarget(branchArg, { allowCreate = true } = {}) {
     // 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}/)`,
+      message: `Convert "${branch}" to a worktree? (moves branch to worktrees/${branch}/)`,
       initialValue: true,
     })
 
@@ -403,9 +403,9 @@ async function main() {
   const { worktreeName, targetCwd, created } = await resolveDevTarget(branchArg, { allowCreate })
 
   if (created) {
-    p.log.success(`Worktree ready: .worktrees/${worktreeName}`)
+    p.log.success(`Worktree ready: worktrees/${worktreeName}`)
   } else if (branchArg) {
-    p.log.info(`Using ${worktreeName === 'main' ? 'main repo' : `.worktrees/${worktreeName}`}`)
+    p.log.info(`Using ${worktreeName === 'main' ? 'main repo' : `worktrees/${worktreeName}`}`)
   }
 
   const domain = readDevDomain(targetCwd)

package/src/server/index.js

@@ -89,7 +89,7 @@ async function parseBody(req) {
 function resolveWorktreeCwd(branch) {
   const root = repoRoot()
   if (branch === 'main') return root
-  const wtDir = join(root, '.worktrees', branch)
+  const wtDir = join(root, 'worktrees', branch)
   if (existsSync(wtDir)) return wtDir
   return null
 }

package/src/worktree/port.js

@@ -1,7 +1,7 @@
 /**
  * Worktree Port Registry
  *
- * Manages a JSON registry (.worktrees/ports.json) that maps worktree names
+ * Manages a JSON registry (worktrees/ports.json) that maps worktree names
  * to unique dev-server ports. Main always gets 1234; worktrees get 1235+.
  *
  * This module is published as part of @dfosco/storyboard-core so client
@@ -19,10 +19,10 @@ import { findByWorktree } from './serverRegistry.js'
 const BASE_PORT = 1234
 
 /**
- * Resolve the path to .worktrees/ports.json.
+ * Resolve the path to worktrees/ports.json.
  *
  * Derives the repo root from directory structure so it works whether
- * running from the repo root or from inside .worktrees/<name>/ — even
+ * running from the repo root or from inside worktrees/<name>/ — even
  * when ports.json does not exist yet.
  *
  * @param {string} [cwd] — override working directory
@@ -31,34 +31,34 @@ const BASE_PORT = 1234
 export function portsFilePath(cwd = process.cwd()) {
   const realCwd = realpathSync(cwd)
 
-  // Check if we're inside .worktrees/<name>/
-  const worktreeMatch = realCwd.match(/^(.+)[/\\]\.worktrees[/\\][^/\\]+/)
+  // Check if we're inside worktrees/<name>/
+  const worktreeMatch = realCwd.match(/^(.+)[/\\]worktrees[/\\][^/\\]+/)
   if (worktreeMatch) {
-    return join(worktreeMatch[1], '.worktrees', 'ports.json')
+    return join(worktreeMatch[1], 'worktrees', 'ports.json')
   }
 
   // We're at the repo root (or somewhere else) — default location
-  return join(realCwd, '.worktrees', 'ports.json')
+  return join(realCwd, 'worktrees', 'ports.json')
 }
 
 /**
  * Detect the worktree name from the current git context.
  *
- * Returns 'main' when not inside a .worktrees/<name>/ directory.
+ * Returns 'main' when not inside a worktrees/<name>/ directory.
  */
 export function detectWorktreeName() {
   try {
     const topLevel = execSync('git rev-parse --show-toplevel', { encoding: 'utf8' }).trim()
     const realTop = realpathSync(topLevel)
 
-    // Check if we're inside a .worktrees/<name> directory
-    if (realTop.includes('.worktrees/') || realTop.includes('.worktrees\\')) {
+    // Check if we're inside a worktrees/<name> directory
+    if (realTop.includes('worktrees/') || realTop.includes('worktrees\\')) {
       return basename(realTop)
     }
 
     // Also check the cwd pattern
     const realCwd = realpathSync(process.cwd())
-    const worktreeMatch = realCwd.match(/\.worktrees[/\\]([^/\\]+)/)
+    const worktreeMatch = realCwd.match(/worktrees[/\\]([^/\\]+)/)
     if (worktreeMatch) return worktreeMatch[1]
 
     // Not a worktree — check the current branch name
@@ -90,7 +90,7 @@ function isPortInUse(port) {
 /**
  * Get or assign a port for the given worktree name.
  *
- * Creates .worktrees/ports.json if it doesn't exist. Assigns ports
+ * Creates worktrees/ports.json if it doesn't exist. Assigns ports
  * starting at BASE_PORT+1 (1235) for non-main worktrees.
  * If the previously assigned port was stolen by another process,
  * reassigns to the next available port.
@@ -179,7 +179,7 @@ export function resolveRunningPort(worktreeName) {
 }
 
 /**
- * Resolve the port for a worktree from .worktrees/ports.json
+ * Resolve the port for a worktree from worktrees/ports.json
  * without assigning a new one if missing.
  *
  * @param {string} worktreeName
@@ -216,9 +216,9 @@ export function slugify(name) {
 }
 
 /**
- * Resolve the repo root — the directory that contains `.worktrees/`.
+ * Resolve the repo root — the directory that contains `worktrees/`.
  *
- * Works whether cwd is the repo root itself or inside `.worktrees/<name>/`.
+ * Works whether cwd is the repo root itself or inside `worktrees/<name>/`.
  *
  * @param {string} [cwd]
  * @returns {string} absolute path to repo root
@@ -226,7 +226,7 @@ export function slugify(name) {
 export function repoRoot(cwd = process.cwd()) {
   const realCwd = realpathSync(cwd)
 
-  const worktreeMatch = realCwd.match(/^(.+)[/\\]\.worktrees[/\\][^/\\]+/)
+  const worktreeMatch = realCwd.match(/^(.+)[/\\]worktrees[/\\][^/\\]+/)
   if (worktreeMatch) return worktreeMatch[1]
 
   return realCwd
@@ -235,7 +235,7 @@ export function repoRoot(cwd = process.cwd()) {
 /**
  * Resolve the full path to a worktree directory.
  *
- * Returns repo root for 'main', `.worktrees/<name>` otherwise.
+ * Returns repo root for 'main', `worktrees/<name>` otherwise.
  *
  * @param {string} name — worktree name
  * @param {string} [cwd]
@@ -244,11 +244,11 @@ export function repoRoot(cwd = process.cwd()) {
 export function worktreeDir(name, cwd) {
   const root = repoRoot(cwd)
   if (name === 'main') return root
-  return join(root, '.worktrees', name)
+  return join(root, 'worktrees', name)
 }
 
 /**
- * List existing worktree directory names from `.worktrees/`.
+ * List existing worktree directory names from `worktrees/`.
  *
  * Only returns directories that look like real worktrees (contain a `.git` file).
  * Does not include 'main'.
@@ -258,7 +258,7 @@ export function worktreeDir(name, cwd) {
  */
 export function listWorktrees(cwd) {
   const root = repoRoot(cwd)
-  const worktreesDir = join(root, '.worktrees')
+  const worktreesDir = join(root, 'worktrees')
 
   if (!existsSync(worktreesDir)) return []
 

package/src/worktree/port.test.js

@@ -43,27 +43,27 @@ describe('portsFilePath', () => {
     rmSync(tempRoot, { recursive: true, force: true })
   })
 
-  it('returns root .worktrees/ports.json from repo root', () => {
+  it('returns root worktrees/ports.json from repo root', () => {
     const result = portsFilePath(tempRoot)
-    expect(result).toBe(join(tempRoot, '.worktrees', 'ports.json'))
+    expect(result).toBe(join(tempRoot, 'worktrees', 'ports.json'))
   })
 
   it('returns shared ports.json from inside a worktree dir', () => {
-    // Simulate .worktrees/my-branch/
-    const worktreeDir = join(tempRoot, '.worktrees', 'my-branch')
+    // Simulate worktrees/my-branch/
+    const worktreeDir = join(tempRoot, 'worktrees', 'my-branch')
     mkdirSync(worktreeDir, { recursive: true })
     const result = portsFilePath(worktreeDir)
-    expect(result).toBe(join(tempRoot, '.worktrees', 'ports.json'))
+    expect(result).toBe(join(tempRoot, 'worktrees', 'ports.json'))
   })
 
   it('returns shared ports.json from worktree even when ports.json does not exist', () => {
     // This is the key bug fix — first run from a worktree with no ports.json
-    const worktreeDir = join(tempRoot, '.worktrees', 'first-run')
+    const worktreeDir = join(tempRoot, 'worktrees', 'first-run')
     mkdirSync(worktreeDir, { recursive: true })
     const result = portsFilePath(worktreeDir)
-    // Must point to root, NOT to .worktrees/first-run/.worktrees/ports.json
-    expect(result).toBe(join(tempRoot, '.worktrees', 'ports.json'))
-    expect(result).not.toContain('first-run/.worktrees')
+    // Must point to root, NOT to worktrees/first-run/worktrees/ports.json
+    expect(result).toBe(join(tempRoot, 'worktrees', 'ports.json'))
+    expect(result).not.toContain('first-run/worktrees')
   })
 })
 
@@ -73,7 +73,7 @@ describe('getPort / resolvePort', () => {
 
   beforeEach(() => {
     tempRoot = realpathSync(mkdtempSync(join(tmpdir(), 'sb-port-test-')))
-    mkdirSync(join(tempRoot, '.worktrees'), { recursive: true })
+    mkdirSync(join(tempRoot, 'worktrees'), { recursive: true })
     originalCwd = process.cwd()
     process.chdir(tempRoot)
   })
@@ -106,7 +106,7 @@ describe('getPort / resolvePort', () => {
 
   it('persists to ports.json', () => {
     getPort('persisted')
-    const portsFile = join(tempRoot, '.worktrees', 'ports.json')
+    const portsFile = join(tempRoot, 'worktrees', 'ports.json')
     expect(existsSync(portsFile)).toBe(true)
     const data = JSON.parse(readFileSync(portsFile, 'utf8'))
     expect(data.persisted).toBe(1235)
@@ -123,7 +123,7 @@ describe('getPort / resolvePort', () => {
   })
 
   it('handles corrupted ports.json gracefully', () => {
-    const portsFile = join(tempRoot, '.worktrees', 'ports.json')
+    const portsFile = join(tempRoot, 'worktrees', 'ports.json')
     writeFileSync(portsFile, 'not valid json')
     // Should not throw — starts fresh
     const port = getPort('recovery')
@@ -136,7 +136,7 @@ describe('repoRoot', () => {
 
   beforeEach(() => {
     tempRoot = realpathSync(mkdtempSync(join(tmpdir(), 'sb-root-test-')))
-    mkdirSync(join(tempRoot, '.worktrees', 'my-branch'), { recursive: true })
+    mkdirSync(join(tempRoot, 'worktrees', 'my-branch'), { recursive: true })
   })
 
   afterEach(() => {
@@ -147,8 +147,8 @@ describe('repoRoot', () => {
     expect(repoRoot(tempRoot)).toBe(tempRoot)
   })
 
-  it('returns parent of .worktrees when inside a worktree', () => {
-    const wt = join(tempRoot, '.worktrees', 'my-branch')
+  it('returns parent of worktrees when inside a worktree', () => {
+    const wt = join(tempRoot, 'worktrees', 'my-branch')
     expect(repoRoot(wt)).toBe(tempRoot)
   })
 })
@@ -158,7 +158,7 @@ describe('worktreeDir', () => {
 
   beforeEach(() => {
     tempRoot = realpathSync(mkdtempSync(join(tmpdir(), 'sb-wtdir-test-')))
-    mkdirSync(join(tempRoot, '.worktrees'), { recursive: true })
+    mkdirSync(join(tempRoot, 'worktrees'), { recursive: true })
   })
 
   afterEach(() => {
@@ -169,8 +169,8 @@ describe('worktreeDir', () => {
     expect(worktreeDir('main', tempRoot)).toBe(tempRoot)
   })
 
-  it('returns .worktrees/<name> for branches', () => {
-    expect(worktreeDir('my-feature', tempRoot)).toBe(join(tempRoot, '.worktrees', 'my-feature'))
+  it('returns worktrees/<name> for branches', () => {
+    expect(worktreeDir('my-feature', tempRoot)).toBe(join(tempRoot, 'worktrees', 'my-feature'))
   })
 })
 
@@ -185,12 +185,12 @@ describe('listWorktrees', () => {
     rmSync(tempRoot, { recursive: true, force: true })
   })
 
-  it('returns empty array when .worktrees does not exist', () => {
+  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')
+    const wtDir = join(tempRoot, 'worktrees')
     mkdirSync(wtDir)
 
     // Valid worktree — has .git file
@@ -208,7 +208,7 @@ describe('listWorktrees', () => {
   })
 
   it('returns multiple worktrees', () => {
-    const wtDir = join(tempRoot, '.worktrees')
+    const wtDir = join(tempRoot, 'worktrees')
     mkdirSync(wtDir)
 
     for (const name of ['alpha', 'beta', 'gamma']) {