@dfosco/storyboard 0.10.3 → 0.10.4-beta.0

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@dfosco/storyboard",
-    "version": "0.10.3",
+    "version": "0.10.4-beta.0",
     "type": "module",
     "license": "MIT",
     "description": "Storyboard prototyping framework — core engine, React integration, and canvas",

package/src/core/cli/index.js

@@ -147,6 +147,7 @@ function helpScreen(version) {
     `  ${bold(cyan('Updates'))}`,
     cmd('update', 'Update storyboard packages to latest'),
     cmd('update:<tag>', 'Update to a specific tag ' + dim('(beta, alpha, ...)')),
+    cmd('migrate', 'Re-run version-bridge migrations'),
     '',
     `  ${dim('All create commands accept --flags for non-interactive use.')}`,
     `  ${dim('Run')} ${yellow('npx storyboard create <type> --help')} ${dim('for flag details.')}`,
@@ -304,6 +305,9 @@ switch (command) {
   case 'workleaf':
     import('./workleaf.js')
     break
+  case 'migrate':
+    import('./migrate.js')
+    break
   default: {
     if (command === 'update' || (command && command.startsWith('update:'))) {
       import('./updateVersion.js')

package/src/core/cli/migrate.js

@@ -0,0 +1,63 @@
+/**
+ * storyboard migrate — re-run version-bridge migrations outside of an upgrade.
+ *
+ * Usage:
+ *   storyboard migrate                  Replay any pending migrations against
+ *                                       the currently-installed @dfosco/storyboard
+ *                                       version (fromVersion = 0.0.0 covers everything).
+ *   storyboard migrate --from <v>       Override fromVersion (useful when re-running
+ *                                       after an aborted upgrade or to force replay
+ *                                       — does NOT bypass the lock file).
+ *   storyboard migrate --yes            Auto-accept the copilot finalize prompt.
+ *
+ * Migrations are still gated by storyboard.lock — once an id is recorded, it
+ * will not run again. Delete the relevant entry from storyboard.lock if you
+ * truly need to replay.
+ */
+
+import * as p from '@clack/prompts'
+import { readFileSync } from 'fs'
+import { resolve } from 'path'
+import { runMigrations } from '../migrations/runner.js'
+
+const args = process.argv.slice(3)
+const assumeYes = args.includes('--yes') || args.includes('-y')
+const fromIndex = args.indexOf('--from')
+const fromOverride = fromIndex >= 0 ? args[fromIndex + 1] : null
+
+function readInstalledVersion() {
+  try {
+    const pkg = JSON.parse(
+      readFileSync(resolve(process.cwd(), 'node_modules', '@dfosco', 'storyboard', 'package.json'), 'utf8')
+    )
+    return pkg.version || null
+  } catch {
+    return null
+  }
+}
+
+const installed = readInstalledVersion()
+if (!installed) {
+  p.log.error('Could not determine installed @dfosco/storyboard version — is it installed?')
+  process.exit(1)
+}
+
+p.intro('storyboard migrate')
+p.log.info(`from ${fromOverride || '0.0.0'} → ${installed}`)
+
+try {
+  const result = await runMigrations({
+    fromVersion: fromOverride || '0.0.0',
+    toVersion: installed,
+    cwd: process.cwd(),
+    assumeYes,
+  })
+  const summary = []
+  if (result.ran.length) summary.push(`${result.ran.length} ran`)
+  if (result.failed.length) summary.push(`${result.failed.length} failed`)
+  if (result.skipped.length) summary.push(`${result.skipped.length} skipped`)
+  p.outro(summary.length ? summary.join(', ') : 'nothing to do')
+} catch (err) {
+  p.log.error(`Migration runner failed: ${err.message}`)
+  process.exit(1)
+}

package/src/core/cli/updateVersion.js

@@ -13,10 +13,28 @@ import * as p from '@clack/prompts'
 import { execSync } from 'child_process'
 import { copyFileSync, existsSync, mkdirSync, readFileSync } from 'fs'
 import { dirname, resolve } from 'path'
+import { runMigrations } from '../migrations/runner.js'
 
 const command = process.argv[2]
 const channels = { 'update:beta': 'beta', 'update:alpha': 'alpha' }
 
+// --yes / -y skips migration confirmation prompts (codemods still run; the
+// copilot finalize step auto-accepts instead of asking).
+const assumeYes = process.argv.includes('--yes') || process.argv.includes('-y')
+
+function readInstalledStoryboardVersion() {
+  try {
+    const pkg = JSON.parse(
+      readFileSync(resolve(process.cwd(), 'node_modules', '@dfosco', 'storyboard', 'package.json'), 'utf8')
+    )
+    return pkg.version || null
+  } catch {
+    return null
+  }
+}
+
+const preUpdateVersion = readInstalledStoryboardVersion() || '0.0.0'
+
 let channel, targetVersion
 if (channels[command]) {
   channel = channels[command]
@@ -128,6 +146,23 @@ function checkArtifactDiscoveryWorkflow() {
 p.log.info('Checking cross-branch artifact workflow integration…')
 checkArtifactDiscoveryWorkflow()
 
+// Run version-bridge migrations between the pre-install version and the
+// freshly-installed one. Each migration's codemods run deterministically;
+// anything contextual is handed off to the `copilot` CLI when present, or
+// printed as a paste-into-your-AI-assistant prompt when absent.
+p.log.info('Running migrations…')
+try {
+  const postUpdateVersion = readInstalledStoryboardVersion() || preUpdateVersion
+  await runMigrations({
+    fromVersion: preUpdateVersion,
+    toVersion: postUpdateVersion,
+    cwd: process.cwd(),
+    assumeYes,
+  })
+} catch (err) {
+  p.log.warn(`Migrations failed: ${err.message}`)
+}
+
 // Auto-commit the version update (only if package.json or lock file changed)
 try {
   // Read the installed version from the storyboard package (try unified first, then legacy core)
@@ -144,12 +179,14 @@ try {
   installedVersion = installedVersion || suffix.slice(1)
   const commitMsg = `[storyboard-update] Update storyboard to ${installedVersion}`
 
-  // Only stage update-related files (package.json, lock files, scaffold outputs)
+  // Only stage update-related files (package.json, lock files, scaffold outputs,
+  // migration lock).
   const filesToStage = [
     'package.json',
     'package-lock.json',
     'yarn.lock',
     'pnpm-lock.yaml',
+    'storyboard.lock',
     '.github/skills',
     '.github/workflows/scripts/aggregate-artifacts.mjs',
     'scripts',

package/src/core/migrations/0.10.0-primer-extraction.js

@@ -0,0 +1,251 @@
+/**
+ * 0.10.0-primer-extraction — finishes the migration to the consumer-wrapper
+ * architecture introduced in storyboard 0.10.0.
+ *
+ * Storyboard 0.10.0 removed the `@dfosco/storyboard/primer` subpath export
+ * and stopped wrapping prototypes/stories in <ThemeProvider><BaseStyles>.
+ * Consumers now wire their design system through src/_prototype.jsx and
+ * src/_story.jsx. The library SPA entry moved to src/library/mount.jsx and
+ * is Primer-free.
+ *
+ * What this codemod does deterministically:
+ *   1. Rewrites index.html's <script src> from the legacy /src/index.jsx
+ *      entry to /src/library/mount.jsx (if both ends exist).
+ *   2. Scaffolds src/library/PrimerThemeSync.jsx (the bridge component that
+ *      used to live in @dfosco/storyboard/primer) — only when the consumer's
+ *      legacy entry actually imported it AND the file doesn't exist yet.
+ *
+ * What goes to the AI prompt (everything contextual):
+ *   - Moving the Primer <ThemeProvider><BaseStyles><ThemeSync /> wrap from
+ *     the deleted entry into src/_prototype.jsx + src/_story.jsx.
+ *   - Re-homing any root-level JSX siblings (e.g. global dialogs) from the
+ *     old entry. These can sit alongside mount.jsx via a small user file or
+ *     be merged into a wrapper component — depends on the project.
+ *   - Merging extra `handlers:` keys from the legacy mountStoryboardCore
+ *     call into the new mount.jsx call.
+ *   - Deleting src/index.jsx once verified.
+ *   - Running `npm run dev` and confirming prototype routes still theme.
+ */
+
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'fs'
+import { dirname, join } from 'path'
+
+export const id = '0.10.0-primer-extraction'
+export const fromRange = '<0.10.0'
+export const toRange = '>=0.10.0'
+
+const LEGACY_ENTRY = 'src/index.jsx'
+const NEW_ENTRY = 'src/library/mount.jsx'
+const INDEX_HTML = 'index.html'
+const PRIMER_SUBPATH_IMPORT = '@dfosco/storyboard/primer'
+const THEME_SYNC_TARGET = 'src/library/PrimerThemeSync.jsx'
+
+/** Migration only fires for repos that actually used the removed primer subpath. */
+export async function detect({ cwd }) {
+  const legacy = join(cwd, LEGACY_ENTRY)
+  if (!existsSync(legacy)) return false
+  try {
+    return readFileSync(legacy, 'utf8').includes(PRIMER_SUBPATH_IMPORT)
+  } catch {
+    return false
+  }
+}
+
+export const codemods = [
+  {
+    name: 'rewrite-index-html-entry',
+    intent:
+      `Rewrite ${INDEX_HTML} <script src="/${LEGACY_ENTRY}"> to ` +
+      `<script src="/${NEW_ENTRY}">, so the SPA boots from the new ` +
+      `Primer-free library entry.`,
+    async run({ cwd }) {
+      const newEntryAbs = join(cwd, NEW_ENTRY)
+      if (!existsSync(newEntryAbs)) {
+        throw new Error(`${NEW_ENTRY} does not exist yet — re-run storyboard-scaffold first`)
+      }
+      const htmlPath = join(cwd, INDEX_HTML)
+      if (!existsSync(htmlPath)) {
+        throw new Error(`${INDEX_HTML} not found at repo root`)
+      }
+      const html = readFileSync(htmlPath, 'utf8')
+      const legacyMatcher = /(<script\b[^>]*\bsrc=["'])\/?src\/index\.jsx(["'][^>]*>)/
+      if (!legacyMatcher.test(html)) {
+        // Either already on /src/library/mount.jsx, or uses a non-standard
+        // entry path we don't recognise — bail safely so the AI prompt can
+        // pick it up.
+        if (html.includes(`/${NEW_ENTRY}`)) return
+        throw new Error(`could not find <script src="/${LEGACY_ENTRY}"> in ${INDEX_HTML}`)
+      }
+      const rewritten = html.replace(legacyMatcher, `$1/${NEW_ENTRY}$2`)
+      writeFileSync(htmlPath, rewritten)
+    },
+  },
+  {
+    name: 'scaffold-primer-themesync',
+    intent:
+      `Scaffold ${THEME_SYNC_TARGET} (the bridge component formerly at ` +
+      `@dfosco/storyboard/primer) so src/_prototype.jsx can import it.`,
+    async run({ cwd }) {
+      const target = join(cwd, THEME_SYNC_TARGET)
+      if (existsSync(target)) return
+      mkdirSync(dirname(target), { recursive: true })
+      writeFileSync(target, PRIMER_THEMESYNC_SOURCE)
+    },
+  },
+]
+
+export const copilotPrompt = `
+# Storyboard 0.10.0 migration — finalize Primer extraction
+
+Storyboard 0.10.0 removed the \`@dfosco/storyboard/primer\` subpath export and
+decoupled storyboard core from \`@primer/react\`. Consumers now wire their
+design system through two seams:
+
+- \`src/_prototype.jsx\` — wraps every prototype route (workspace SPA + iframe)
+- \`src/_story.jsx\` — wraps every story render
+
+The deterministic codemods just rewrote \`index.html\` to load the new
+\`src/library/mount.jsx\` entry and scaffolded \`src/library/PrimerThemeSync.jsx\`.
+What's left needs project-specific judgment:
+
+## 1. Move the Primer wrap into the consumer seams
+
+Inspect the legacy \`src/index.jsx\` (still present until you delete it) and
+move its Primer provider stack into \`src/_prototype.jsx\`. Replace the
+current pass-through with something like:
+
+\`\`\`jsx
+import { ThemeProvider, BaseStyles } from '@primer/react'
+import './globals.css'
+import PrimerThemeSync from './library/PrimerThemeSync.jsx'
+
+export default function PrototypeWrapper({ children }) {
+  return (
+    <ThemeProvider colorMode="auto">
+      <BaseStyles>
+        <PrimerThemeSync />
+        {children}
+      </BaseStyles>
+    </ThemeProvider>
+  )
+}
+\`\`\`
+
+Then make \`src/_story.jsx\` re-export the same wrapper:
+
+\`\`\`jsx
+export { default } from './_prototype.jsx'
+\`\`\`
+
+## 2. Re-home root-level JSX siblings
+
+The old \`src/index.jsx\` likely renders extra components alongside
+\`<RouterProvider>\` (global dialogs, listeners, toasters, etc). These were
+mounted at the SPA root. In 0.10.0 the SPA shell is \`src/library/_app.jsx\` —
+but that file is library-owned and should not be edited.
+
+Pick one of:
+  - **Mount inside \`_prototype.jsx\`** — works if the component is only
+    needed while a prototype is visible (it'll unmount on workspace routes).
+  - **Add a sibling file** like \`src/userExtensions.jsx\` exporting a small
+    component, and import + render it from \`src/library/_app.jsx\` (this
+    counts as a documented library edit — see src/library/README.md).
+
+## 3. Merge \`mountStoryboardCore\` options
+
+If the legacy entry passed extra \`handlers\` or other options to
+\`mountStoryboardCore(storyboardConfig, { ... })\`, merge them into the
+matching call in \`src/library/mount.jsx\`.
+
+## 4. Delete the legacy entry and verify
+
+Once items 1–3 are done, delete \`src/index.jsx\`, run \`npm run dev\`, and
+confirm:
+  - Workspace and canvas routes load.
+  - Prototype routes are themed correctly (Primer base styles applied).
+  - Theme toggling in the toolbar updates prototypes as expected.
+`
+
+// ---------------------------------------------------------------------------
+// PrimerThemeSync source — pulled out of git history (commit ae9e4c122~1).
+// Kept verbatim so the bridge behavior on consumer repos is unchanged from
+// pre-0.10.0.
+// ---------------------------------------------------------------------------
+
+const PRIMER_THEMESYNC_SOURCE = `/**
+ * PrimerThemeSync — invisible React component that bridges the storyboard
+ * toolbar theme switcher with Primer's ThemeProvider context.
+ *
+ * Listens for \`storyboard:theme:changed\` custom events dispatched by the
+ * core theme store and calls setColorMode/setDayScheme/setNightScheme on
+ * Primer's useTheme() hook accordingly.
+ *
+ * On mount it reads localStorage to initialize Primer to the correct scheme
+ * before the storyboard toolbar has loaded.
+ *
+ * When prototype sync is disabled (via "Apply theme to" settings), the
+ * prototype is forced to light mode regardless of the selected theme.
+ *
+ * Scaffolded by the 0.10.0-primer-extraction migration. Replaces the
+ * \`ThemeSync\` component that used to live at \`@dfosco/storyboard/primer\`
+ * (removed when storyboard core became Primer-agnostic). Safe to edit.
+ */
+
+import { useEffect } from 'react'
+import { useTheme } from '@primer/react'
+
+const THEME_STORAGE_KEY = 'sb-color-scheme'
+const THEME_SYNC_STORAGE_KEY = 'sb-theme-sync'
+
+const DEFAULT_SYNC = {
+  prototype: true,
+  toolbar: false,
+  codeBoxes: true,
+}
+
+function readSyncTargets() {
+  try {
+    const raw = localStorage.getItem(THEME_SYNC_STORAGE_KEY)
+    if (!raw) return DEFAULT_SYNC
+    return { ...DEFAULT_SYNC, ...JSON.parse(raw) }
+  } catch {
+    return DEFAULT_SYNC
+  }
+}
+
+function applyToPrimer(setColorMode, setDayScheme, setNightScheme, themeValue) {
+  if (themeValue === 'system' || !themeValue) {
+    setColorMode('auto')
+    setDayScheme('light')
+    setNightScheme('dark')
+  } else {
+    setColorMode('day')
+    setDayScheme(themeValue)
+    setNightScheme(themeValue)
+  }
+}
+
+export default function PrimerThemeSync() {
+  const { setColorMode, setDayScheme, setNightScheme } = useTheme()
+
+  useEffect(() => {
+    const saved = localStorage.getItem(THEME_STORAGE_KEY)
+    const syncTargets = readSyncTargets()
+    const prototypeTheme = syncTargets.prototype ? saved : 'light'
+    applyToPrimer(setColorMode, setDayScheme, setNightScheme, prototypeTheme)
+  }, []) // eslint-disable-line react-hooks/exhaustive-deps
+
+  useEffect(() => {
+    function handleThemeChanged(e) {
+      const detail = e.detail || {}
+      const prototypeTheme = detail.bySurface?.prototype ?? detail.prototypeTheme
+      if (typeof prototypeTheme !== 'string') return
+      applyToPrimer(setColorMode, setDayScheme, setNightScheme, prototypeTheme)
+    }
+    document.addEventListener('storyboard:theme:changed', handleThemeChanged)
+    return () => document.removeEventListener('storyboard:theme:changed', handleThemeChanged)
+  }, [setColorMode, setDayScheme, setNightScheme])
+
+  return null
+}
+`

package/src/core/migrations/0.10.0-primer-extraction.test.js

@@ -0,0 +1,158 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest'
+import { mkdtempSync, rmSync, existsSync, readFileSync, writeFileSync, mkdirSync } from 'fs'
+import { tmpdir } from 'os'
+import { join } from 'path'
+
+import { runMigrations } from './runner.js'
+import * as migration from './0.10.0-primer-extraction.js'
+
+let cwd
+let logs
+
+const LEGACY_INDEX_JSX = `
+import { StrictMode } from 'react'
+import { createRoot } from 'react-dom/client'
+import { RouterProvider, createBrowserRouter } from 'react-router-dom'
+import { routes } from './routes'
+import { ThemeProvider, BaseStyles } from '@primer/react'
+import { ThemeSync } from '@dfosco/storyboard/primer'
+`
+
+const INDEX_HTML_WITH_LEGACY_ENTRY = `<!doctype html>
+<html><body>
+  <div id="root"></div>
+  <script type="module" src="/src/index.jsx"></script>
+</body></html>
+`
+
+const INDEX_HTML_WITH_NEW_ENTRY = `<!doctype html>
+<html><body>
+  <div id="root"></div>
+  <script type="module" src="/src/library/mount.jsx"></script>
+</body></html>
+`
+
+function captureLog() {
+  const entries = { info: [], message: [], warn: [], step: [], error: [] }
+  return {
+    entries,
+    info:    (m) => entries.info.push(m),
+    message: (m) => entries.message.push(m),
+    warn:    (m) => entries.warn.push(m),
+    step:    (m) => entries.step.push(m),
+    error:   (m) => entries.error.push(m),
+  }
+}
+
+function scaffoldClient(cwd, { withLegacyImport = true, withMountJsx = true } = {}) {
+  mkdirSync(join(cwd, 'src'), { recursive: true })
+  writeFileSync(
+    join(cwd, 'src/index.jsx'),
+    withLegacyImport ? LEGACY_INDEX_JSX : '// nothing here\n',
+  )
+  if (withMountJsx) {
+    mkdirSync(join(cwd, 'src/library'), { recursive: true })
+    writeFileSync(join(cwd, 'src/library/mount.jsx'), '// mount\n')
+  }
+  writeFileSync(join(cwd, 'index.html'), INDEX_HTML_WITH_LEGACY_ENTRY)
+}
+
+beforeEach(() => {
+  cwd = mkdtempSync(join(tmpdir(), 'sb-mig010-'))
+  logs = captureLog()
+})
+
+afterEach(() => {
+  rmSync(cwd, { recursive: true, force: true })
+})
+
+describe('0.10.0-primer-extraction — detect()', () => {
+  it('returns true when legacy entry imports @dfosco/storyboard/primer', async () => {
+    scaffoldClient(cwd)
+    expect(await migration.detect({ cwd })).toBe(true)
+  })
+
+  it('returns false when legacy entry does not import the removed subpath', async () => {
+    scaffoldClient(cwd, { withLegacyImport: false })
+    expect(await migration.detect({ cwd })).toBe(false)
+  })
+
+  it('returns false when there is no legacy entry at all', async () => {
+    expect(await migration.detect({ cwd })).toBe(false)
+  })
+})
+
+describe('0.10.0-primer-extraction — codemods via runner', () => {
+  it('rewrites index.html and scaffolds PrimerThemeSync, records ran', async () => {
+    scaffoldClient(cwd)
+    const result = await runMigrations({
+      fromVersion: '0.9.5', toVersion: '0.10.3',
+      cwd, modules: [migration], log: logs,
+      prompts: { confirm: vi.fn().mockResolvedValue(false) },
+      detectCopilot: () => null, runCopilot: vi.fn(),
+    })
+
+    expect(result.ran).toEqual(['0.10.0-primer-extraction'])
+    expect(readFileSync(join(cwd, 'index.html'), 'utf8'))
+      .toContain('src="/src/library/mount.jsx"')
+    expect(existsSync(join(cwd, 'src/library/PrimerThemeSync.jsx'))).toBe(true)
+    expect(readFileSync(join(cwd, 'src/library/PrimerThemeSync.jsx'), 'utf8'))
+      .toContain("import { useTheme } from '@primer/react'")
+
+    // Lock recorded — re-running is a no-op
+    const result2 = await runMigrations({
+      fromVersion: '0.9.5', toVersion: '0.10.3',
+      cwd, modules: [migration], log: logs,
+      prompts: { confirm: vi.fn() },
+      detectCopilot: () => null, runCopilot: vi.fn(),
+    })
+    expect(result2.ran).toEqual([])
+  })
+
+  it('fails gracefully when index.html points to a non-standard entry', async () => {
+    scaffoldClient(cwd)
+    writeFileSync(
+      join(cwd, 'index.html'),
+      '<html><script type="module" src="/src/wat.jsx"></script></html>',
+    )
+    const result = await runMigrations({
+      fromVersion: '0.9.5', toVersion: '0.10.3',
+      cwd, modules: [migration], log: logs,
+      prompts: { confirm: vi.fn().mockResolvedValue(false) },
+      detectCopilot: () => null, runCopilot: vi.fn(),
+    })
+    expect(result.failed).toEqual(['0.10.0-primer-extraction'])
+    const printed = logs.entries.message.join('\n')
+    expect(printed).toContain('Codemods that failed')
+    expect(printed).toContain('rewrite-index-html-entry')
+    expect(printed).toContain('could not find')
+  })
+
+  it('is a no-op for index.html that already uses the new entry', async () => {
+    scaffoldClient(cwd)
+    writeFileSync(join(cwd, 'index.html'), INDEX_HTML_WITH_NEW_ENTRY)
+    const result = await runMigrations({
+      fromVersion: '0.9.5', toVersion: '0.10.3',
+      cwd, modules: [migration], log: logs,
+      prompts: { confirm: vi.fn().mockResolvedValue(false) },
+      detectCopilot: () => null, runCopilot: vi.fn(),
+    })
+    expect(result.ran).toEqual(['0.10.0-primer-extraction'])
+    expect(readFileSync(join(cwd, 'index.html'), 'utf8'))
+      .toContain('src="/src/library/mount.jsx"')
+  })
+
+  it('does not overwrite an existing PrimerThemeSync', async () => {
+    scaffoldClient(cwd)
+    mkdirSync(join(cwd, 'src/library'), { recursive: true })
+    writeFileSync(join(cwd, 'src/library/PrimerThemeSync.jsx'), '// custom\n')
+    await runMigrations({
+      fromVersion: '0.9.5', toVersion: '0.10.3',
+      cwd, modules: [migration], log: logs,
+      prompts: { confirm: vi.fn().mockResolvedValue(false) },
+      detectCopilot: () => null, runCopilot: vi.fn(),
+    })
+    expect(readFileSync(join(cwd, 'src/library/PrimerThemeSync.jsx'), 'utf8'))
+      .toBe('// custom\n')
+  })
+})

package/src/core/migrations/detectCopilot.js

@@ -0,0 +1,21 @@
+/**
+ * detectCopilot — checks whether `copilot` is on PATH.
+ * Returns 'copilot' when present, null otherwise.
+ *
+ * Intentionally narrow: we don't probe for `gh copilot`, `claude`, `codex`,
+ * or any other CLI. The fallback path prints the prompt directly so the
+ * user can hand it to whichever assistant they're already using.
+ */
+
+import { spawnSync } from 'child_process'
+
+export function detectCopilot() {
+  try {
+    const probe = spawnSync('command', ['-v', 'copilot'], {
+      stdio: 'ignore',
+      shell: true,
+    })
+    if (probe.status === 0) return 'copilot'
+  } catch { /* fall through */ }
+  return null
+}

package/src/core/migrations/lockFile.js

@@ -0,0 +1,54 @@
+/**
+ * storyboard.lock — append-only record of which migrations have run in a
+ * consumer repository. Lives at the consumer repo root, committed.
+ *
+ * Schema (version 1):
+ *   {
+ *     "version": 1,
+ *     "migrations": [
+ *       { "id": "...", "status": "ran" | "skipped" | "failed",
+ *         "at": "<ISO>", "reason"?: string }
+ *     ]
+ *   }
+ *
+ * Once a migration id appears in the array, the runner never replays it —
+ * even if status is "failed" (failures are handed off to the AI prompt and
+ * considered "delivered to the user"; replaying would re-run codemods the
+ * user may have already finished by hand).
+ */
+
+import { existsSync, readFileSync, writeFileSync } from 'fs'
+import { join } from 'path'
+
+const LOCK_FILENAME = 'storyboard.lock'
+const SCHEMA_VERSION = 1
+
+function lockPath(cwd) {
+  return join(cwd, LOCK_FILENAME)
+}
+
+export function readLock(cwd) {
+  const path = lockPath(cwd)
+  if (!existsSync(path)) return { version: SCHEMA_VERSION, migrations: [] }
+  try {
+    const parsed = JSON.parse(readFileSync(path, 'utf8'))
+    if (!parsed || typeof parsed !== 'object') return { version: SCHEMA_VERSION, migrations: [] }
+    return {
+      version: parsed.version || SCHEMA_VERSION,
+      migrations: Array.isArray(parsed.migrations) ? parsed.migrations : [],
+    }
+  } catch {
+    return { version: SCHEMA_VERSION, migrations: [] }
+  }
+}
+
+export function hasRun(lock, id) {
+  return lock.migrations.some((m) => m.id === id)
+}
+
+export function appendMigration(cwd, entry) {
+  const lock = readLock(cwd)
+  lock.migrations.push({ at: new Date().toISOString(), ...entry })
+  writeFileSync(lockPath(cwd), JSON.stringify(lock, null, 2) + '\n')
+  return lock
+}

package/src/core/migrations/lockFile.test.js

@@ -0,0 +1,78 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest'
+import { mkdtempSync, rmSync, readFileSync, writeFileSync } from 'fs'
+import { tmpdir } from 'os'
+import { join } from 'path'
+
+import { readLock, hasRun, appendMigration } from './lockFile.js'
+
+let cwd
+
+beforeEach(() => {
+  cwd = mkdtempSync(join(tmpdir(), 'sb-lockfile-'))
+})
+
+afterEach(() => {
+  rmSync(cwd, { recursive: true, force: true })
+})
+
+describe('readLock', () => {
+  it('returns empty shape when storyboard.lock does not exist', () => {
+    const lock = readLock(cwd)
+    expect(lock).toEqual({ version: 1, migrations: [] })
+  })
+
+  it('parses an existing lock file', () => {
+    writeFileSync(
+      join(cwd, 'storyboard.lock'),
+      JSON.stringify({ version: 1, migrations: [{ id: 'a', status: 'ran' }] })
+    )
+    const lock = readLock(cwd)
+    expect(lock.migrations).toHaveLength(1)
+    expect(lock.migrations[0].id).toBe('a')
+  })
+
+  it('returns empty shape when lock is malformed JSON', () => {
+    writeFileSync(join(cwd, 'storyboard.lock'), 'not json')
+    expect(readLock(cwd)).toEqual({ version: 1, migrations: [] })
+  })
+})
+
+describe('hasRun', () => {
+  it('returns true when id is present regardless of status', () => {
+    const lock = { version: 1, migrations: [
+      { id: 'a', status: 'ran' },
+      { id: 'b', status: 'failed' },
+      { id: 'c', status: 'skipped' },
+    ]}
+    expect(hasRun(lock, 'a')).toBe(true)
+    expect(hasRun(lock, 'b')).toBe(true)
+    expect(hasRun(lock, 'c')).toBe(true)
+    expect(hasRun(lock, 'd')).toBe(false)
+  })
+})
+
+describe('appendMigration', () => {
+  it('creates the file and appends an entry', () => {
+    appendMigration(cwd, { id: 'a', status: 'ran' })
+    const lock = readLock(cwd)
+    expect(lock.migrations).toHaveLength(1)
+    expect(lock.migrations[0].id).toBe('a')
+    expect(lock.migrations[0].status).toBe('ran')
+    expect(lock.migrations[0].at).toMatch(/T.*Z/)
+  })
+
+  it('appends to existing entries', () => {
+    appendMigration(cwd, { id: 'a', status: 'ran' })
+    appendMigration(cwd, { id: 'b', status: 'failed' })
+    const lock = readLock(cwd)
+    expect(lock.migrations).toHaveLength(2)
+    expect(lock.migrations.map(m => m.id)).toEqual(['a', 'b'])
+  })
+
+  it('writes pretty-printed JSON with trailing newline', () => {
+    appendMigration(cwd, { id: 'a', status: 'ran' })
+    const raw = readFileSync(join(cwd, 'storyboard.lock'), 'utf8')
+    expect(raw.endsWith('\n')).toBe(true)
+    expect(raw).toContain('  "migrations":')
+  })
+})

package/src/core/migrations/runner.js

@@ -0,0 +1,208 @@
+/**
+ * Migration runner — discovers migration modules, filters by version + lock,
+ * runs deterministic codemods, then hands the AI-assisted finish to copilot
+ * (or prints the prompt for the user to paste elsewhere).
+ *
+ * Each migration module exports:
+ *   id          string                           required, unique
+ *   fromRange   string (semver range)            required
+ *   toRange     string (semver range)            required
+ *   detect      async ({ cwd }) => boolean       optional (default: true)
+ *   codemods    Array<{ name, intent, run }>     optional
+ *   copilotPrompt  string                        optional
+ *
+ * Codemod contract:
+ *   { name, intent, async run({ cwd, log }) }
+ *   - intent is a short human-readable sentence describing what the codemod
+ *     attempts to do. If run() throws, the intent gets appended to the
+ *     copilot prompt under "Codemods that failed — please apply manually".
+ *
+ * Failure semantics:
+ *   - codemod throws  → recorded internally, intent merged into prompt
+ *   - migration always finishes (status: ran), unless detect() returns false
+ *     (status: skipped). The lock is append-only and never re-runs an id.
+ */
+
+import * as p from '@clack/prompts'
+import { execSync, spawn } from 'child_process'
+import { readdirSync } from 'fs'
+import { join } from 'path'
+import { pathToFileURL } from 'url'
+
+import { satisfies } from './semver.js'
+import { readLock, hasRun, appendMigration } from './lockFile.js'
+import { detectCopilot } from './detectCopilot.js'
+
+const MIGRATIONS_DIR = new URL('.', import.meta.url).pathname
+
+async function loadMigrationModules(dir = MIGRATIONS_DIR) {
+  const entries = readdirSync(dir, { withFileTypes: true })
+  const mods = []
+  for (const entry of entries) {
+    if (!entry.isFile()) continue
+    if (!/^\d/.test(entry.name)) continue
+    if (!entry.name.endsWith('.js')) continue
+    if (entry.name.endsWith('.test.js')) continue
+    const mod = await import(pathToFileURL(join(dir, entry.name)).href)
+    if (!mod.id) continue
+    mods.push(mod)
+  }
+  return mods
+}
+
+function isApplicable(mod, fromVersion, toVersion) {
+  return (
+    satisfies(fromVersion, mod.fromRange) &&
+    satisfies(toVersion, mod.toRange)
+  )
+}
+
+function buildFailureAppendix(failures) {
+  if (failures.length === 0) return ''
+  const lines = ['', '## Codemods that failed — please apply manually', '']
+  for (const f of failures) {
+    lines.push(`- **${f.name}** — ${f.intent}`)
+    if (f.error) lines.push(`  - Error: \`${f.error}\``)
+  }
+  return lines.join('\n') + '\n'
+}
+
+function printPromptFallback(id, prompt, log) {
+  const border = '─'.repeat(64)
+  log.info(`Manual step needed: ${id}`)
+  log.message('Paste the following prompt into your AI coding assistant:')
+  log.message('')
+  log.message(border)
+  log.message(prompt.trim())
+  log.message(border)
+}
+
+async function invokeCopilot(prompt, cwd) {
+  return new Promise((resolve, reject) => {
+    const child = spawn('copilot', ['-p', prompt], { stdio: 'inherit', cwd })
+    child.on('error', reject)
+    child.on('exit', (code) => {
+      if (code === 0) resolve()
+      else reject(new Error(`copilot exited with code ${code}`))
+    })
+  })
+}
+
+/**
+ * @param {object} opts
+ * @param {string} opts.fromVersion
+ * @param {string} opts.toVersion
+ * @param {string} opts.cwd
+ * @param {boolean} [opts.assumeYes]    — skip the copilot confirmation
+ * @param {Array}   [opts.modules]      — inject migrations (for tests)
+ * @param {object}  [opts.log]          — defaults to clack's p.log
+ * @param {object}  [opts.prompts]      — { confirm }, for tests
+ * @param {Function} [opts.runCopilot]  — for tests
+ * @param {Function} [opts.detectCopilot] — for tests
+ */
+export async function runMigrations(opts) {
+  const {
+    fromVersion,
+    toVersion,
+    cwd,
+    assumeYes = false,
+    modules,
+    log = p.log,
+    prompts = p,
+    runCopilot = invokeCopilot,
+    detectCopilot: detect = detectCopilot,
+  } = opts
+
+  const all = modules || (await loadMigrationModules())
+  const lock = readLock(cwd)
+
+  const candidates = all
+    .filter((m) => isApplicable(m, fromVersion, toVersion))
+    .filter((m) => !hasRun(lock, m.id))
+
+  if (candidates.length === 0) {
+    log.message('No migrations to run')
+    return { ran: [], skipped: [], failed: [] }
+  }
+
+  log.info(`Running ${candidates.length} migration(s)`)
+
+  const ran = []
+  const skipped = []
+  const failedMigrations = []
+
+  for (const mod of candidates) {
+    const applicable = mod.detect ? await mod.detect({ cwd }) : true
+    if (!applicable) {
+      appendMigration(cwd, { id: mod.id, status: 'skipped', reason: 'not-applicable' })
+      skipped.push(mod.id)
+      log.message(`  ${mod.id} — skipped (not applicable)`)
+      continue
+    }
+
+    log.step(mod.id)
+
+    const failures = []
+    for (const cm of mod.codemods || []) {
+      try {
+        await cm.run({ cwd, log })
+        log.message(`  ✔ ${cm.name}`)
+      } catch (err) {
+        failures.push({ name: cm.name, intent: cm.intent, error: err.message })
+        log.warn(`  ✗ ${cm.name} — ${err.message}`)
+      }
+    }
+
+    if (mod.copilotPrompt) {
+      const promptWithFailures = mod.copilotPrompt.trim() + '\n' + buildFailureAppendix(failures)
+      const tool = detect()
+      if (tool) {
+        let ok = assumeYes
+        if (!assumeYes) {
+          ok = await prompts.confirm({
+            message: `Run \`${tool}\` to finalize ${mod.id}?`,
+            initialValue: true,
+          })
+        }
+        if (ok) {
+          try {
+            await runCopilot(promptWithFailures, cwd)
+          } catch (err) {
+            log.warn(`copilot failed: ${err.message} — printing prompt instead`)
+            printPromptFallback(mod.id, promptWithFailures, log)
+          }
+        } else {
+          printPromptFallback(mod.id, promptWithFailures, log)
+        }
+      } else {
+        printPromptFallback(mod.id, promptWithFailures, log)
+      }
+    } else if (failures.length > 0) {
+      printPromptFallback(
+        mod.id,
+        buildFailureAppendix(failures),
+        log,
+      )
+    }
+
+    appendMigration(cwd, {
+      id: mod.id,
+      status: failures.length > 0 ? 'failed' : 'ran',
+      ...(failures.length > 0 && { failures: failures.map((f) => f.name) }),
+    })
+    if (failures.length > 0) {
+      failedMigrations.push(mod.id)
+    } else {
+      ran.push(mod.id)
+    }
+  }
+
+  return { ran, skipped, failed: failedMigrations }
+}
+
+export { loadMigrationModules, buildFailureAppendix, printPromptFallback }
+// re-export for callers that want to read the lock without importing the module
+export { readLock, hasRun } from './lockFile.js'
+// unused but kept exported for callers that want to invoke deterministic
+// shell helpers from a migration's codemod
+export { execSync as _execSyncForCodemods }

package/src/core/migrations/runner.test.js

@@ -0,0 +1,236 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest'
+import { mkdtempSync, rmSync } from 'fs'
+import { tmpdir } from 'os'
+import { join } from 'path'
+
+import { runMigrations, buildFailureAppendix } from './runner.js'
+import { readLock, hasRun } from './lockFile.js'
+
+let cwd
+let logs
+
+const captureLog = () => {
+  const entries = { info: [], message: [], warn: [], step: [], error: [] }
+  return {
+    entries,
+    info:    (m) => entries.info.push(m),
+    message: (m) => entries.message.push(m),
+    warn:    (m) => entries.warn.push(m),
+    step:    (m) => entries.step.push(m),
+    error:   (m) => entries.error.push(m),
+  }
+}
+
+const noPrompt = { confirm: vi.fn().mockResolvedValue(true) }
+const detectNone = () => null
+const detectCopilotTool = () => 'copilot'
+
+function makeMigration(overrides = {}) {
+  return {
+    id: 'test-mig',
+    fromRange: '<1.0.0',
+    toRange: '>=1.0.0',
+    codemods: [],
+    ...overrides,
+  }
+}
+
+beforeEach(() => {
+  cwd = mkdtempSync(join(tmpdir(), 'sb-migrations-'))
+  logs = captureLog()
+})
+
+afterEach(() => {
+  rmSync(cwd, { recursive: true, force: true })
+})
+
+describe('runMigrations — version filter', () => {
+  it('runs a migration when fromVersion satisfies fromRange and toVersion satisfies toRange', async () => {
+    const mig = makeMigration({
+      codemods: [{ name: 'noop', intent: '', run: vi.fn() }],
+    })
+    const result = await runMigrations({
+      fromVersion: '0.9.5', toVersion: '1.0.0',
+      cwd, modules: [mig], log: logs, prompts: noPrompt,
+      detectCopilot: detectNone, runCopilot: vi.fn(),
+    })
+    expect(result.ran).toEqual(['test-mig'])
+    expect(mig.codemods[0].run).toHaveBeenCalled()
+  })
+
+  it('skips a migration when toVersion does not satisfy toRange', async () => {
+    const mig = makeMigration({
+      codemods: [{ name: 'noop', intent: '', run: vi.fn() }],
+    })
+    const result = await runMigrations({
+      fromVersion: '0.9.5', toVersion: '0.9.8',
+      cwd, modules: [mig], log: logs, prompts: noPrompt,
+      detectCopilot: detectNone, runCopilot: vi.fn(),
+    })
+    expect(result.ran).toEqual([])
+    expect(mig.codemods[0].run).not.toHaveBeenCalled()
+  })
+})
+
+describe('runMigrations — lock file', () => {
+  it('records the migration as ran and never replays it', async () => {
+    const mig = makeMigration({
+      codemods: [{ name: 'noop', intent: '', run: vi.fn() }],
+    })
+    await runMigrations({
+      fromVersion: '0.9.5', toVersion: '1.0.0',
+      cwd, modules: [mig], log: logs, prompts: noPrompt,
+      detectCopilot: detectNone, runCopilot: vi.fn(),
+    })
+    const lock = readLock(cwd)
+    expect(hasRun(lock, 'test-mig')).toBe(true)
+
+    // Replay
+    mig.codemods[0].run.mockClear()
+    const result = await runMigrations({
+      fromVersion: '0.9.5', toVersion: '1.0.0',
+      cwd, modules: [mig], log: logs, prompts: noPrompt,
+      detectCopilot: detectNone, runCopilot: vi.fn(),
+    })
+    expect(mig.codemods[0].run).not.toHaveBeenCalled()
+    expect(result.ran).toEqual([])
+  })
+
+  it('records skipped when detect() returns false', async () => {
+    const mig = makeMigration({
+      detect: async () => false,
+      codemods: [{ name: 'noop', intent: '', run: vi.fn() }],
+    })
+    const result = await runMigrations({
+      fromVersion: '0.9.5', toVersion: '1.0.0',
+      cwd, modules: [mig], log: logs, prompts: noPrompt,
+      detectCopilot: detectNone, runCopilot: vi.fn(),
+    })
+    expect(result.skipped).toEqual(['test-mig'])
+    expect(mig.codemods[0].run).not.toHaveBeenCalled()
+    const lock = readLock(cwd)
+    expect(lock.migrations[0].status).toBe('skipped')
+    expect(lock.migrations[0].reason).toBe('not-applicable')
+  })
+})
+
+describe('runMigrations — codemod failures', () => {
+  it('records failed status and appends intent to the printed prompt', async () => {
+    const mig = makeMigration({
+      copilotPrompt: 'Finish the migration.',
+      codemods: [
+        { name: 'good', intent: 'do good things', run: vi.fn() },
+        {
+          name: 'bad',
+          intent: 'rewrite something tricky',
+          run: () => { throw new Error('regex did not match') },
+        },
+      ],
+    })
+    const result = await runMigrations({
+      fromVersion: '0.9.5', toVersion: '1.0.0',
+      cwd, modules: [mig], log: logs, prompts: noPrompt,
+      detectCopilot: detectNone, runCopilot: vi.fn(),
+    })
+    expect(result.failed).toEqual(['test-mig'])
+    expect(result.ran).toEqual([])
+
+    const printed = logs.entries.message.join('\n')
+    expect(printed).toContain('Finish the migration.')
+    expect(printed).toContain('Codemods that failed')
+    expect(printed).toContain('rewrite something tricky')
+    expect(printed).toContain('regex did not match')
+
+    const lock = readLock(cwd)
+    expect(lock.migrations[0].status).toBe('failed')
+    expect(lock.migrations[0].failures).toEqual(['bad'])
+  })
+
+  it('still prints failure appendix even when migration has no copilotPrompt', async () => {
+    const mig = makeMigration({
+      codemods: [{
+        name: 'bad', intent: 'do a thing',
+        run: () => { throw new Error('nope') },
+      }],
+    })
+    await runMigrations({
+      fromVersion: '0.9.5', toVersion: '1.0.0',
+      cwd, modules: [mig], log: logs, prompts: noPrompt,
+      detectCopilot: detectNone, runCopilot: vi.fn(),
+    })
+    const printed = logs.entries.message.join('\n')
+    expect(printed).toContain('Codemods that failed')
+    expect(printed).toContain('do a thing')
+  })
+})
+
+describe('runMigrations — copilot branch', () => {
+  it('runs copilot when detected and user confirms', async () => {
+    const mig = makeMigration({
+      copilotPrompt: 'Do the AI thing.',
+    })
+    const runCopilot = vi.fn().mockResolvedValue()
+    const confirm = vi.fn().mockResolvedValue(true)
+    await runMigrations({
+      fromVersion: '0.9.5', toVersion: '1.0.0',
+      cwd, modules: [mig], log: logs,
+      prompts: { confirm }, detectCopilot: detectCopilotTool, runCopilot,
+    })
+    expect(confirm).toHaveBeenCalled()
+    expect(runCopilot).toHaveBeenCalledOnce()
+    expect(runCopilot.mock.calls[0][0]).toContain('Do the AI thing.')
+  })
+
+  it('skips copilot prompt and prints fallback when user declines', async () => {
+    const mig = makeMigration({ copilotPrompt: 'Do the AI thing.' })
+    const runCopilot = vi.fn()
+    const confirm = vi.fn().mockResolvedValue(false)
+    await runMigrations({
+      fromVersion: '0.9.5', toVersion: '1.0.0',
+      cwd, modules: [mig], log: logs,
+      prompts: { confirm }, detectCopilot: detectCopilotTool, runCopilot,
+    })
+    expect(runCopilot).not.toHaveBeenCalled()
+    expect(logs.entries.message.join('\n')).toContain('Do the AI thing.')
+  })
+
+  it('auto-accepts copilot when assumeYes is set', async () => {
+    const mig = makeMigration({ copilotPrompt: 'Do the AI thing.' })
+    const runCopilot = vi.fn().mockResolvedValue()
+    const confirm = vi.fn()
+    await runMigrations({
+      fromVersion: '0.9.5', toVersion: '1.0.0',
+      cwd, modules: [mig], log: logs, assumeYes: true,
+      prompts: { confirm }, detectCopilot: detectCopilotTool, runCopilot,
+    })
+    expect(confirm).not.toHaveBeenCalled()
+    expect(runCopilot).toHaveBeenCalledOnce()
+  })
+
+  it('prints prompt fallback when copilot is not detected', async () => {
+    const mig = makeMigration({ copilotPrompt: 'Do the AI thing.' })
+    const runCopilot = vi.fn()
+    await runMigrations({
+      fromVersion: '0.9.5', toVersion: '1.0.0',
+      cwd, modules: [mig], log: logs, prompts: noPrompt,
+      detectCopilot: detectNone, runCopilot,
+    })
+    expect(runCopilot).not.toHaveBeenCalled()
+    expect(logs.entries.message.join('\n')).toContain('Do the AI thing.')
+  })
+})
+
+describe('buildFailureAppendix', () => {
+  it('returns empty string when no failures', () => {
+    expect(buildFailureAppendix([])).toBe('')
+  })
+
+  it('formats failures as a markdown section', () => {
+    const out = buildFailureAppendix([
+      { name: 'foo', intent: 'do a thing', error: 'oops' },
+    ])
+    expect(out).toContain('## Codemods that failed')
+    expect(out).toContain('**foo** — do a thing')
+    expect(out).toContain('`oops`')
+  })
+})

package/src/core/migrations/semver.js

@@ -0,0 +1,47 @@
+/**
+ * Minimal semver range checker for migration version filters.
+ *
+ * Supports the subset we actually use in fromRange/toRange:
+ *   "X.Y.Z"   — exact match
+ *   ">=X.Y.Z" / ">X.Y.Z" / "<=X.Y.Z" / "<X.Y.Z"
+ *   "*"       — matches anything
+ *
+ * Pre-release tags (e.g. 0.10.0-beta.1) are normalized to their base version
+ * for comparison purposes — a migration with fromRange "<0.10.0" matches
+ * "0.10.0-beta.1" because the user has not yet reached the stable cut.
+ */
+
+function parse(version) {
+  if (!version || typeof version !== 'string') return [0, 0, 0]
+  const base = version.split('-')[0].split('+')[0]
+  const parts = base.split('.').map((n) => Number.parseInt(n, 10))
+  return [parts[0] || 0, parts[1] || 0, parts[2] || 0]
+}
+
+function compare(a, b) {
+  const [a1, a2, a3] = parse(a)
+  const [b1, b2, b3] = parse(b)
+  if (a1 !== b1) return a1 - b1
+  if (a2 !== b2) return a2 - b2
+  return a3 - b3
+}
+
+export function satisfies(version, range) {
+  if (!range || range === '*') return true
+  const trimmed = range.trim()
+  const operatorMatch = trimmed.match(/^(>=|<=|>|<|=)?\s*(.+)$/)
+  if (!operatorMatch) return false
+  const op = operatorMatch[1] || '='
+  const target = operatorMatch[2]
+  const cmp = compare(version, target)
+  switch (op) {
+    case '>=': return cmp >= 0
+    case '<=': return cmp <= 0
+    case '>':  return cmp > 0
+    case '<':  return cmp < 0
+    case '=':  return cmp === 0
+    default:   return false
+  }
+}
+
+export { compare, parse }

package/src/core/migrations/semver.test.js

@@ -0,0 +1,67 @@
+import { describe, it, expect } from 'vitest'
+import { satisfies, compare, parse } from './semver.js'
+
+describe('semver.parse', () => {
+  it('parses standard 3-part versions', () => {
+    expect(parse('1.2.3')).toEqual([1, 2, 3])
+  })
+
+  it('strips pre-release tags', () => {
+    expect(parse('0.10.0-beta.1')).toEqual([0, 10, 0])
+  })
+
+  it('strips build metadata', () => {
+    expect(parse('1.2.3+abcdef')).toEqual([1, 2, 3])
+  })
+
+  it('returns zeros for missing parts', () => {
+    expect(parse('1')).toEqual([1, 0, 0])
+    expect(parse('1.2')).toEqual([1, 2, 0])
+  })
+
+  it('handles falsy input', () => {
+    expect(parse(undefined)).toEqual([0, 0, 0])
+    expect(parse('')).toEqual([0, 0, 0])
+  })
+})
+
+describe('semver.compare', () => {
+  it('orders versions correctly', () => {
+    expect(compare('1.0.0', '1.0.0')).toBe(0)
+    expect(compare('1.0.0', '1.0.1') < 0).toBe(true)
+    expect(compare('1.1.0', '1.0.5') > 0).toBe(true)
+    expect(compare('2.0.0', '1.99.99') > 0).toBe(true)
+  })
+})
+
+describe('semver.satisfies', () => {
+  it('"*" matches everything', () => {
+    expect(satisfies('0.0.0', '*')).toBe(true)
+    expect(satisfies('99.99.99', '*')).toBe(true)
+  })
+
+  it('exact match', () => {
+    expect(satisfies('1.0.0', '1.0.0')).toBe(true)
+    expect(satisfies('1.0.0', '=1.0.0')).toBe(true)
+    expect(satisfies('1.0.0', '1.0.1')).toBe(false)
+  })
+
+  it('>= and >', () => {
+    expect(satisfies('1.0.0', '>=1.0.0')).toBe(true)
+    expect(satisfies('1.0.0', '>1.0.0')).toBe(false)
+    expect(satisfies('1.0.1', '>1.0.0')).toBe(true)
+  })
+
+  it('<= and <', () => {
+    expect(satisfies('0.9.9', '<1.0.0')).toBe(true)
+    expect(satisfies('1.0.0', '<1.0.0')).toBe(false)
+    expect(satisfies('1.0.0', '<=1.0.0')).toBe(true)
+  })
+
+  it('treats pre-release as the base version', () => {
+    // a project on 0.10.0-beta.1 has NOT crossed the 0.10.0 stable cut
+    expect(satisfies('0.10.0-beta.1', '<0.10.0')).toBe(false) // matches 0.10.0 base
+    expect(satisfies('0.10.0-beta.1', '>=0.10.0')).toBe(true)
+    expect(satisfies('0.9.5-rc.2', '<0.10.0')).toBe(true)
+  })
+})