@dfosco/storyboard 0.5.0-alpha.0

package/scaffold/skills/vitest/references/features-mocking.md

@@ -0,0 +1,265 @@
+---
+name: mocking
+description: Mock functions, modules, timers, and dates with vi utilities
+---
+
+# Mocking
+
+## Mock Functions
+
+```ts
+import { expect, vi } from 'vitest'
+
+// Create mock function
+const fn = vi.fn()
+fn('hello')
+
+expect(fn).toHaveBeenCalled()
+expect(fn).toHaveBeenCalledWith('hello')
+
+// With implementation
+const add = vi.fn((a, b) => a + b)
+expect(add(1, 2)).toBe(3)
+
+// Mock return values
+fn.mockReturnValue(42)
+fn.mockReturnValueOnce(1).mockReturnValueOnce(2)
+fn.mockResolvedValue({ data: true })
+fn.mockRejectedValue(new Error('fail'))
+
+// Mock implementation
+fn.mockImplementation((x) => x * 2)
+fn.mockImplementationOnce(() => 'first call')
+```
+
+## Spying on Objects
+
+```ts
+const cart = {
+  getTotal: () => 100,
+}
+
+const spy = vi.spyOn(cart, 'getTotal')
+cart.getTotal()
+
+expect(spy).toHaveBeenCalled()
+
+// Mock implementation
+spy.mockReturnValue(200)
+expect(cart.getTotal()).toBe(200)
+
+// Restore original
+spy.mockRestore()
+```
+
+## Module Mocking
+
+```ts
+// vi.mock is hoisted to top of file
+vi.mock('./api', () => ({
+  fetchUser: vi.fn(() => ({ id: 1, name: 'Mock' })),
+}))
+
+import { fetchUser } from './api'
+
+test('mocked module', () => {
+  expect(fetchUser()).toEqual({ id: 1, name: 'Mock' })
+})
+```
+
+### Partial Mock
+
+```ts
+vi.mock('./utils', async (importOriginal) => {
+  const actual = await importOriginal()
+  return {
+    ...actual,
+    specificFunction: vi.fn(),
+  }
+})
+```
+
+### Auto-mock with Spy
+
+```ts
+// Keep implementation but spy on calls
+vi.mock('./calculator', { spy: true })
+
+import { add } from './calculator'
+
+test('spy on module', () => {
+  const result = add(1, 2) // Real implementation
+  expect(result).toBe(3)
+  expect(add).toHaveBeenCalledWith(1, 2)
+})
+```
+
+### Manual Mocks (__mocks__)
+
+```
+src/
+  __mocks__/
+    axios.ts      # Mocks 'axios'
+  api/
+    __mocks__/
+      client.ts   # Mocks './client'
+    client.ts
+```
+
+```ts
+// Just call vi.mock with no factory
+vi.mock('axios')
+vi.mock('./api/client')
+```
+
+## Dynamic Mocking (vi.doMock)
+
+Not hoisted - use for dynamic imports:
+
+```ts
+test('dynamic mock', async () => {
+  vi.doMock('./config', () => ({
+    apiUrl: 'http://test.local',
+  }))
+  
+  const { apiUrl } = await import('./config')
+  expect(apiUrl).toBe('http://test.local')
+  
+  vi.doUnmock('./config')
+})
+```
+
+## Mock Timers
+
+```ts
+import { afterEach, beforeEach, vi } from 'vitest'
+
+beforeEach(() => {
+  vi.useFakeTimers()
+})
+
+afterEach(() => {
+  vi.useRealTimers()
+})
+
+test('timers', () => {
+  const fn = vi.fn()
+  setTimeout(fn, 1000)
+  
+  expect(fn).not.toHaveBeenCalled()
+  
+  vi.advanceTimersByTime(1000)
+  expect(fn).toHaveBeenCalled()
+})
+
+// Other timer methods
+vi.runAllTimers()           // Run all pending timers
+vi.runOnlyPendingTimers()   // Run only currently pending
+vi.advanceTimersToNextTimer() // Advance to next timer
+```
+
+### Async Timer Methods
+
+```ts
+test('async timers', async () => {
+  vi.useFakeTimers()
+  
+  let resolved = false
+  setTimeout(() => Promise.resolve().then(() => { resolved = true }), 100)
+  
+  await vi.advanceTimersByTimeAsync(100)
+  expect(resolved).toBe(true)
+})
+```
+
+## Mock Dates
+
+```ts
+vi.setSystemTime(new Date('2024-01-01'))
+expect(new Date().getFullYear()).toBe(2024)
+
+vi.useRealTimers() // Restore
+```
+
+## Mock Globals
+
+```ts
+vi.stubGlobal('fetch', vi.fn(() => 
+  Promise.resolve({ json: () => ({ data: 'mock' }) })
+))
+
+// Restore
+vi.unstubAllGlobals()
+```
+
+## Mock Environment Variables
+
+```ts
+vi.stubEnv('API_KEY', 'test-key')
+expect(import.meta.env.API_KEY).toBe('test-key')
+
+// Restore
+vi.unstubAllEnvs()
+```
+
+## Clearing Mocks
+
+```ts
+const fn = vi.fn()
+fn()
+
+fn.mockClear()       // Clear call history
+fn.mockReset()       // Clear history + implementation
+fn.mockRestore()     // Restore original (for spies)
+
+// Global
+vi.clearAllMocks()
+vi.resetAllMocks()
+vi.restoreAllMocks()
+```
+
+## Config Auto-Reset
+
+```ts
+// vitest.config.ts
+defineConfig({
+  test: {
+    clearMocks: true,    // Clear before each test
+    mockReset: true,     // Reset before each test
+    restoreMocks: true,  // Restore after each test
+    unstubEnvs: true,    // Restore env vars
+    unstubGlobals: true, // Restore globals
+  },
+})
+```
+
+## Hoisted Variables for Mocks
+
+```ts
+const mockFn = vi.hoisted(() => vi.fn())
+
+vi.mock('./module', () => ({
+  getData: mockFn,
+}))
+
+import { getData } from './module'
+
+test('hoisted mock', () => {
+  mockFn.mockReturnValue('test')
+  expect(getData()).toBe('test')
+})
+```
+
+## Key Points
+
+- `vi.mock` is hoisted - called before imports
+- Use `vi.doMock` for dynamic, non-hoisted mocking
+- Always restore mocks to avoid test pollution
+- Use `{ spy: true }` to keep implementation but track calls
+- `vi.hoisted` lets you reference variables in mock factories
+
+<!-- 
+Source references:
+- https://vitest.dev/guide/mocking.html
+- https://vitest.dev/api/vi.html
+-->

package/scaffold/skills/vitest/references/features-snapshots.md

@@ -0,0 +1,207 @@
+---
+name: snapshot-testing
+description: Snapshot testing with file, inline, and file snapshots
+---
+
+# Snapshot Testing
+
+Snapshot tests capture output and compare against stored references.
+
+## Basic Snapshot
+
+```ts
+import { expect, test } from 'vitest'
+
+test('snapshot', () => {
+  const result = generateOutput()
+  expect(result).toMatchSnapshot()
+})
+```
+
+First run creates `.snap` file:
+
+```js
+// __snapshots__/test.spec.ts.snap
+exports['snapshot 1'] = `
+{
+  "id": 1,
+  "name": "test"
+}
+`
+```
+
+## Inline Snapshots
+
+Stored directly in test file:
+
+```ts
+test('inline snapshot', () => {
+  const data = { foo: 'bar' }
+  expect(data).toMatchInlineSnapshot()
+})
+```
+
+Vitest updates the test file:
+
+```ts
+test('inline snapshot', () => {
+  const data = { foo: 'bar' }
+  expect(data).toMatchInlineSnapshot(`
+    {
+      "foo": "bar",
+    }
+  `)
+})
+```
+
+## File Snapshots
+
+Compare against explicit file:
+
+```ts
+test('render html', async () => {
+  const html = renderComponent()
+  await expect(html).toMatchFileSnapshot('./expected/component.html')
+})
+```
+
+## Snapshot Hints
+
+Add descriptive hints:
+
+```ts
+test('multiple snapshots', () => {
+  expect(header).toMatchSnapshot('header')
+  expect(body).toMatchSnapshot('body content')
+  expect(footer).toMatchSnapshot('footer')
+})
+```
+
+## Object Shape Matching
+
+Match partial structure:
+
+```ts
+test('shape snapshot', () => {
+  const data = { 
+    id: Math.random(), 
+    created: new Date(),
+    name: 'test' 
+  }
+  
+  expect(data).toMatchSnapshot({
+    id: expect.any(Number),
+    created: expect.any(Date),
+  })
+})
+```
+
+## Error Snapshots
+
+```ts
+test('error message', () => {
+  expect(() => {
+    throw new Error('Something went wrong')
+  }).toThrowErrorMatchingSnapshot()
+})
+
+test('inline error', () => {
+  expect(() => {
+    throw new Error('Bad input')
+  }).toThrowErrorMatchingInlineSnapshot(`[Error: Bad input]`)
+})
+```
+
+## Updating Snapshots
+
+```bash
+# Update all snapshots
+vitest -u
+vitest --update
+
+# In watch mode, press 'u' to update failed snapshots
+```
+
+## Custom Serializers
+
+Add custom snapshot formatting:
+
+```ts
+expect.addSnapshotSerializer({
+  test(val) {
+    return val && typeof val.toJSON === 'function'
+  },
+  serialize(val, config, indentation, depth, refs, printer) {
+    return printer(val.toJSON(), config, indentation, depth, refs)
+  },
+})
+```
+
+Or via config:
+
+```ts
+// vitest.config.ts
+defineConfig({
+  test: {
+    snapshotSerializers: ['./my-serializer.ts'],
+  },
+})
+```
+
+## Snapshot Format Options
+
+```ts
+defineConfig({
+  test: {
+    snapshotFormat: {
+      printBasicPrototype: false, // Don't print Array/Object prototypes
+      escapeString: false,
+    },
+  },
+})
+```
+
+## Concurrent Test Snapshots
+
+Use context's expect:
+
+```ts
+test.concurrent('concurrent 1', async ({ expect }) => {
+  expect(await getData()).toMatchSnapshot()
+})
+
+test.concurrent('concurrent 2', async ({ expect }) => {
+  expect(await getOther()).toMatchSnapshot()
+})
+```
+
+## Snapshot File Location
+
+Default: `__snapshots__/<test-file>.snap`
+
+Customize:
+
+```ts
+defineConfig({
+  test: {
+    resolveSnapshotPath: (testPath, snapExtension) => {
+      return testPath.replace('__tests__', '__snapshots__') + snapExtension
+    },
+  },
+})
+```
+
+## Key Points
+
+- Commit snapshot files to version control
+- Review snapshot changes in code review
+- Use hints for multiple snapshots in one test
+- Use `toMatchFileSnapshot` for large outputs (HTML, JSON)
+- Inline snapshots auto-update in test file
+- Use context's `expect` for concurrent tests
+
+<!-- 
+Source references:
+- https://vitest.dev/guide/snapshot.html
+- https://vitest.dev/api/expect.html#tomatchsnapshot
+-->

package/scaffold/skills/worktree/SKILL.md

@@ -0,0 +1,93 @@
+# Worktree Skill
+
+> Triggered by: "create worktree", "new worktree", "worktree for", "worktree"
+
+## What This Does
+
+Creates a git worktree for a given branch name inside `worktrees/` and switches into it.
+
+---
+
+## How to Execute
+
+When the user asks for a worktree named `<branch-name>`:
+
+### Step 1: Create the worktree
+
+If the branch already exists locally or on the remote:
+
+```bash
+git worktree add worktrees/<branch-name> <branch-name>
+```
+
+If the branch does NOT exist yet, create it **from the current branch** (NOT from main):
+
+```bash
+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.
+
+If using `@dfosco/storyboard-core`:
+
+```bash
+node -e "import('@dfosco/storyboard-core/worktree/port').then(m => console.log(m.getPort('<branch-name>')))"
+```
+
+Or if the project has `scripts/worktree-port.js`:
+
+```bash
+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.
+
+### Step 3: Change into the worktree directory
+
+```bash
+cd worktrees/<branch-name>
+```
+
+All subsequent commands in the session should run from this directory.
+
+### Step 4: Confirm
+
+Print the current working directory, branch, and assigned port to confirm:
+
+```bash
+pwd && git branch --show-current
+```
+
+### Step 5: Start dev server
+
+Run the dev server in the worktree. If using the storyboard-dev launcher:
+
+```bash
+npx storyboard-dev
+```
+
+Or if using a custom dev script:
+
+```bash
+npm run dev
+```
+
+The dev server automatically uses the port assigned in Step 2.
+
+**Skip this step if the worktree skill was invoked from the ship skill** — ship runs the dev server as its own final step to avoid starting it twice.
+
+---
+
+## Notes
+
+- 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`.

package/scaffold/storyboard.config.json

@@ -0,0 +1,44 @@
+{
+  "customDomain": "",
+  "repository": {
+    "owner": "",
+    "name": ""
+  },
+  "modes": {
+    "enabled": false
+  },
+  "comments": {
+    "discussions": {
+      "category": "Comments"
+    }
+  },
+  "plugins": {
+    "devtools": true
+  },
+  "workshop": {
+    "enabled": false,
+    "features": {
+      "createPrototype": true,
+      "createFlow": true,
+      "createCanvas": true
+    }
+  },
+  "featureFlags": {},
+  "canvas": {
+    "github": {
+      "embedBehavior": "link-preview",
+      "ghGuard": "copy"
+    },
+    "terminal": {
+      "resizable": false,
+      "defaultWidth": 800,
+      "defaultHeight": 450
+    }
+  },
+  "customerMode": {
+    "enabled": false,
+    "hideChrome": false,
+    "hideHomepage": false,
+    "protoHomepage": ""
+  }
+}

package/src/canvas/Canvas.jsx

@@ -0,0 +1,78 @@
+import { Children } from 'react';
+import Draggable from './Draggable';
+import { findDragId, generateDragId } from './utils';
+
+function readInitialPosition(child, pad = 0) {
+  const x = Number(child?.props?.['data-tc-x']);
+  const y = Number(child?.props?.['data-tc-y']);
+  if (Number.isFinite(x) && Number.isFinite(y)) {
+    return { x: Math.max(pad, x), y: Math.max(pad, y) };
+  }
+  return null;
+}
+
+/** Read an optional CSS selector that restricts drag to a handle element. */
+function readHandle(child) {
+  return child?.props?.['data-tc-handle'] || null;
+}
+
+function Canvas({
+  children,
+  dotted = false,
+  grid = false,
+  gridSize,
+  snapGrid,
+  colorMode = 'auto',
+  locked = false,
+  boundaryPad,
+  onDragStart,
+  onDrag,
+  onDragEnd,
+}) {
+  const showDots = dotted || grid;
+  const visualGridSize = gridSize;
+  const pad = boundaryPad ?? gridSize ?? 0;
+  const dotRadius = visualGridSize && visualGridSize < 16 ? 1 : 2;
+  const canvasStyle = visualGridSize
+    ? {
+        '--tc-grid-size': `${visualGridSize}px`,
+        '--tc-grid-offset': `${visualGridSize / -2}px`,
+        '--tc-dot-radius': `${dotRadius}px`,
+      }
+    : undefined;
+
+  return (
+    <main
+      className="tc-canvas"
+      data-dotted={showDots || undefined}
+      data-locked={locked || undefined}
+      data-color-mode={colorMode !== 'auto' ? colorMode : undefined}
+      style={canvasStyle}
+    >
+      {Children.map(children, (child, index) => {
+        const dragId = findDragId(child) ?? generateDragId(child, index);
+        const initialPosition = readInitialPosition(child, pad);
+        const handle = readHandle(child);
+        return (
+          <Draggable
+            key={dragId}
+            gridSize={gridSize}
+            snapGrid={snapGrid}
+            dragId={dragId}
+            initialPosition={initialPosition}
+            onDragStart={onDragStart}
+            onDrag={onDrag}
+            onDragEnd={onDragEnd}
+            handle={handle}
+            locked={locked}
+            boundaryPad={pad}
+          >
+            {child}
+          </Draggable>
+        );
+      })}
+    </main>
+  );
+}
+
+export default Canvas;