nuxt-spec 0.3.4 → 0.4.0-alpha.2

package/bin/setup.js

@@ -1,287 +0,0 @@
-#!/usr/bin/env node
-
-import { execSync } from 'node:child_process'
-import {
-  createFileFromWebTemplate, deletePath, hasJsonKey,
-  pathExists, promptUser, removeFromJsonFile, showMessage,
-  updateConfigFile, updateJsonFile, updateTextFile,
-} from 'elrh-cosca'
-import {
-  getPlaywrightInstallCmd, getPrepareCmd,
-} from './helpers/commands.js'
-
-const TARGET_VERSION = '0.3.4'
-
-/**
- * CLI tool to scaffold necessary adjustments in project folder.
- *
- * It first asks whether to run in "auto" mode (no prompts, force = true) or "manual" mode (with prompts, force = false).
- *
- * Then it:
- *  1) adds `nuxt-spec` into `package.json` dependencies and removes `nuxt`, `vue` and `vue-router` if present
- *  2) adds `extends: ['nuxt-spec']` to `nuxt.config.ts`
- *  3) creates/updates `pnpm-workspace.yaml` file (only if pnpm is used)
- *  4) creates default `vitest.config.ts` file
- *  5) creates default `.nuxtrc` file
- *  6) adds test-related scripts in `package.json`
- *  7) creates sample test files
- *  8) clear node_modules and lock file(s)
- *  9) run install command
- * 10) run Nuxt prepare command to generate types and auto-imports
- * 11) run Playwright setup command
- *
- * @param {boolean} autoRun - Whether to run the setup automatically without any prompts (defaults to false).
- * @param {string} [packageManager] - Package manager to be used (`npm`, `pnpm`, `yarn`, `bun` or `deno`).
- */
-export async function specSetup(autoRun = false, packageManager) {
-  showMessage('NUXT SPEC SETUP')
-  showMessage('This CLI tool will help you include Nuxt Spec in your project.')
-  showMessage('Refer to the documentation for more information.', 2)
-
-  const isAutoRun = autoRun || await promptUser('Do you want to set everything up automatically (no more prompts)?')
-  showMessage('')
-
-  // 1) manage dependencies in package.json
-
-  // add nuxt-spec
-  try {
-    await updateJsonFile('package.json', 'dependencies', {
-      ['nuxt-spec']: TARGET_VERSION,
-    }, isAutoRun, `This will add 'nuxt-spec' dependency to your 'package.json'. Continue?`)
-  } catch (error) {
-    console.error(`Error adding 'nuxt-spec' dependency:\n`, error.message)
-  }
-
-  // remove now obsolete nuxt, vue and vue-router
-  const removeDeps = isAutoRun || await promptUser(`As 'nuxt-spec' provides 'nuxt', 'vue' and 'vue-router' dependencies out of the box, do you want to remove them from your 'package.json' to avoid duplications and possible version clashes?`)
-  if (removeDeps) {
-    if (hasJsonKey('package.json', 'dependencies.nuxt')) {
-      try {
-        await removeFromJsonFile('package.json', 'dependencies.nuxt', true)
-      } catch (error) {
-        console.error('Error removing \'nuxt\' dependency:\n', error.message)
-      }
-    }
-    if (hasJsonKey('package.json', 'dependencies.vue')) {
-      try {
-        await removeFromJsonFile('package.json', 'dependencies.vue', true)
-      } catch (error) {
-        console.error('Error removing \'vue\' dependency:\n', error.message)
-      }
-    }
-    if (hasJsonKey('package.json', 'dependencies.vue-router')) {
-      try {
-        await removeFromJsonFile('package.json', 'dependencies.vue-router', true)
-      } catch (error) {
-        console.error('Error removing \'vue-router\' dependency:\n', error.message)
-      }
-    }
-    if (hasJsonKey('package.json', 'devDependencies.nuxt')) {
-      try {
-        await removeFromJsonFile('package.json', 'devDependencies.nuxt', true)
-      } catch (error) {
-        console.error('Error removing \'nuxt\' devDependency:\n', error.message)
-      }
-    }
-    if (hasJsonKey('package.json', 'devDependencies.vue')) {
-      try {
-        await removeFromJsonFile('package.json', 'devDependencies.vue', true)
-      } catch (error) {
-        console.error('Error removing \'vue\' devDependency:\n', error.message)
-      }
-    }
-    if (hasJsonKey('package.json', 'devDependencies.vue-router')) {
-      try {
-        await removeFromJsonFile('package.json', 'devDependencies.vue-router', true)
-      } catch (error) {
-        console.error('Error removing \'vue-router\' devDependency:\n', error.message)
-      }
-    }
-  }
-
-  // 2) modify nuxt.config.ts
-  try {
-    await updateConfigFile('nuxt.config.ts', {
-      extends: [
-        'nuxt-spec',
-      ],
-    }, isAutoRun, `This will add 'nuxt-spec' module to your 'nuxt.config.ts'. Continue?`)
-  } catch (error) {
-    console.error('Error updating \'nuxt.config.ts\':\n', error.message)
-  }
-
-  // 3) `pnpm-workspace.yaml` file (only if pnpm is used)
-  if (packageManager === 'pnpm') {
-    try {
-      if (pathExists('pnpm-workspace.yaml')) {
-        await updateTextFile('pnpm-workspace.yaml', ['shamefully-hoist: true'], isAutoRun, 'This will adjust \'pnpm-workspace.yaml\' file in your project. Continue?')
-      } else {
-        await createFileFromWebTemplate(`https://raw.githubusercontent.com/AloisSeckar/nuxt-spec/refs/tags/v${TARGET_VERSION}/config/templates/pnpm-workspace.yaml.template`,
-          'pnpm-workspace.yaml', isAutoRun, 'This will add \'pnpm-workspace.yaml\' file for your project. Continue?')
-      }
-    } catch (error) {
-      console.error('Error setting up \'pnpm-workspace.yaml\':\n', error.message)
-    }
-  }
-
-  // 4) create vitest.config.ts
-  try {
-    await createFileFromWebTemplate(`https://raw.githubusercontent.com/AloisSeckar/nuxt-spec/refs/tags/v${TARGET_VERSION}/config/templates/vitest.config.ts.template`,
-      'vitest.config.ts', isAutoRun, 'This will create a new \'vitest.config.ts\' file for your project. Continue?')
-  } catch (error) {
-    console.error('Error setting up \'vitest.config.ts\':\n', error.message)
-  }
-
-  // 5) create .nuxtrc to prevent @nuxt/test-utils setup from running automatically on first start
-  if (!pathExists('.nuxtrc')) {
-    try {
-      await createFileFromWebTemplate(`https://raw.githubusercontent.com/AloisSeckar/nuxt-spec/refs/tags/v${TARGET_VERSION}/.nuxtrc`, '.nuxtrc', isAutoRun, 'This will create a \'.nuxtrc\' file to prevent @nuxt/test-utils setup from running automatically when dev server starts. Continue?')
-    } catch (error) {
-      console.error('Error creating \'.nuxtrc\':\n', error.message)
-    }
-  }
-
-  // 6) modify package.json with test scripts
-  try {
-    await updateJsonFile('package.json', 'scripts', {
-      'test': 'vitest run',
-      'test-u': 'vitest run -u',
-      'test-i': 'vitest',
-    }, isAutoRun, 'This will adjust the test-related commands in your \'package.json\'. Continue?')
-  } catch (error) {
-    console.error('Error adjusting scripts in \'package.json\':\n', error.message)
-  }
-
-  // 7) create sample test files
-  const createSampleTests = isAutoRun || await promptUser('Do you want to create sample tests in \'/test\' folder?')
-  if (createSampleTests) {
-    try {
-      await createFileFromWebTemplate(`https://raw.githubusercontent.com/AloisSeckar/nuxt-spec/refs/tags/v${TARGET_VERSION}/test/browser/vitest-browser.test.ts`,
-        'test/browser/vitest-browser.test.ts', true)
-    } catch (error) {
-      console.error('Error setting up \'vitest-browser.test.ts\':\n', error.message)
-    }
-    try {
-      await createFileFromWebTemplate(`https://raw.githubusercontent.com/AloisSeckar/nuxt-spec/refs/tags/v${TARGET_VERSION}/test/e2e/nuxt-e2e.test.ts`,
-        'test/e2e/nuxt-e2e.test.ts', true)
-    } catch (error) {
-      console.error('Error setting up \'nuxt-e2e.test.ts\':\n', error.message)
-    }
-    try {
-      await createFileFromWebTemplate(`https://raw.githubusercontent.com/AloisSeckar/nuxt-spec/refs/tags/v${TARGET_VERSION}/test/e2e/nuxt-visual.test.ts`,
-        'test/e2e/nuxt-visual.test.ts', true)
-    } catch (error) {
-      console.error('Error setting up \'nuxt-visual.test.ts\':\n', error.message)
-    }
-    try {
-      await createFileFromWebTemplate(`https://raw.githubusercontent.com/AloisSeckar/nuxt-spec/refs/tags/v${TARGET_VERSION}/test/nuxt/nuxt-unit.test.ts`,
-        'test/nuxt/nuxt-unit.test.ts', true)
-    } catch (error) {
-      console.error('Error setting up \'nuxt-unit.test.ts\':\n', error.message)
-    }
-    try {
-      await createFileFromWebTemplate(`https://raw.githubusercontent.com/AloisSeckar/nuxt-spec/refs/tags/v${TARGET_VERSION}/test/unit/vitest-unit.test.ts`,
-        'test/unit/vitest-unit.test.ts', true)
-    } catch (error) {
-      console.error('Error setting up \'vitest-unit.test.ts\':\n', error.message)
-    }
-  }
-
-  // 8) clear node_modules and lock file(s)
-  const prepareForReinstall = isAutoRun || await promptUser('Dependencies should be re-installed now. Do you want to remove node_modules and the lock file?')
-  if (prepareForReinstall) {
-    if (pathExists('node_modules')) {
-      try {
-        await deletePath('node_modules', true)
-      } catch (error) {
-        console.error('Error deleting \'node_modules\':\n', error.message)
-      }
-    }
-    if (pathExists('package-lock.json')) {
-      try {
-        await deletePath('package-lock.json', true)
-      } catch (error) {
-        console.error('Error deleting \'package-lock.json\':\n', error.message)
-      }
-    }
-    if (pathExists('pnpm-lock.yaml')) {
-      try {
-        await deletePath('pnpm-lock.yaml', true)
-      } catch (error) {
-        console.error('Error deleting \'pnpm-lock.yaml\':\n', error.message)
-      }
-    }
-    if (pathExists('yarn.lock')) {
-      try {
-        await deletePath('yarn.lock', true)
-      } catch (error) {
-        console.error('Error deleting \'yarn.lock\':\n', error.message)
-      }
-    }
-    if (pathExists('bun.lockb')) {
-      try {
-        await deletePath('bun.lockb', true)
-      } catch (error) {
-        console.error('Error deleting \'bun.lockb\':\n', error.message)
-      }
-    }
-    if (pathExists('deno.lock')) {
-      try {
-        await deletePath('deno.lock', true)
-      } catch (error) {
-        console.error('Error deleting \'deno.lock\':\n', error.message)
-      }
-    }
-  }
-
-  // 9) run install command
-  const runInstall = isAutoRun || await promptUser(`Fresh \`${packageManager} install\` is required. Do you want to run it now?`)
-  if (runInstall) {
-    try {
-      showMessage(`Running \`${packageManager} install\`...`)
-      execSync(`${packageManager} install`, { stdio: 'inherit' })
-    } catch (error) {
-      console.error(`Error running \`${packageManager} install\`:\n`, error.message)
-    }
-  }
-
-  // 10) run Nuxt prepare command to generate types and auto-imports
-  const prepareCmd = getPrepareCmd(packageManager)
-  const runPrepare = isAutoRun || await promptUser(`Nuxt needs to generate types and auto-imports before the project is fully usable. Do you want to run \`${prepareCmd}\` now?`)
-  if (runPrepare) {
-    try {
-      showMessage(`Running \`${prepareCmd}\`...`)
-      execSync(prepareCmd, { stdio: 'inherit' })
-    } catch (error) {
-      console.error(`Error running \`${prepareCmd}\`:\n`, error.message)
-    }
-  }
-
-  // 11) run Playwright browser install command
-  const playwrightInstallCmd = getPlaywrightInstallCmd(packageManager)
-  const runPlaywrightInstall = isAutoRun || await promptUser(`Playwright browser runtimes might need to be installed locally for e2e tests. Do you want to run \`${playwrightInstallCmd}\` now?`)
-  if (runPlaywrightInstall) {
-    try {
-      showMessage(`Running \`${playwrightInstallCmd}\`...`)
-      execSync(playwrightInstallCmd, { stdio: 'inherit' })
-    } catch (error) {
-      console.error(`Error running \`${playwrightInstallCmd}\`:\n`, error.message)
-    }
-  }
-
-  // 12) inform user
-  showMessage('')
-  showMessage('NUXT SPEC SETUP COMPLETE', 2)
-  if (!runInstall) {
-    showMessage(`Proceed with \`${packageManager} install\` to install dependencies.`)
-  }
-  if (!runPrepare) {
-    showMessage(`Run \`${prepareCmd}\` to generate the required Nuxt types and auto-imports.`)
-  }
-  if (!runPlaywrightInstall) {
-    showMessage(`Run \`${playwrightInstallCmd}\` to setup the Playwright browser runtimes for e2e tests.`)
-  }
-
-  // force exit to prevent #20
-  process.exit(0)
-}

package/bin/update.js

@@ -1,94 +0,0 @@
-#!/usr/bin/env node
-
-import { execSync } from 'node:child_process'
-import {
-  hasJsonKey, promptUser, showMessage,
-} from 'elrh-cosca'
-import {
-  getPlaywrightInstallCmd, getPrepareCmd, getUpdateCmd,
-} from './helpers/commands.js'
-
-const TARGET_VERSION = '0.3.4'
-
-/**
- * CLI tool to update existing `nuxt-spec` installation.
- *
- * It first asks whether to run in "auto" mode (no prompts, force = true) or "manual" mode (with prompts, force = false).
- *
- * Then it:
- *  1) verifies `nuxt-spec` is present in `package.json` (fails with a hint to run `setup` otherwise)
- *  2) runs the package manager's update command to bump `nuxt-spec` to the latest version
- *  3) run the `nuxt prepare` command to regenerate types and auto-imports
- *  4) run the `playwright install` command to ensure the Playwright browser runtimes are up to date
- *
- * @param {boolean} autoRun - Whether to run the update automatically without any prompts (defaults to false).
- * @param {string} [packageManager] - Package manager to be used (`npm`, `pnpm`, `yarn`, `bun` or `deno`).
- */
-export async function specUpdate(autoRun = false, packageManager) {
-  showMessage('NUXT SPEC UPDATE')
-  showMessage('This CLI tool will help you update Nuxt Spec in your project.')
-  showMessage('Refer to the documentation for more information.', 2)
-
-  // fail fast if there is nothing to update
-  const isInstalled = hasJsonKey('package.json', `dependencies.nuxt-spec`)
-    || hasJsonKey('package.json', `devDependencies.nuxt-spec`)
-  if (!isInstalled) {
-    console.error(`'nuxt-spec' was not found in your 'package.json'. Run the 'setup' command first.`)
-    process.exit(1)
-  }
-
-  const isAutoRun = autoRun || await promptUser('Do you want to update everything automatically (no more prompts)?')
-  showMessage('')
-
-  // 1) run 'update nuxt-spec'
-  const updateCmd = getUpdateCmd(packageManager, `nuxt-spec@${TARGET_VERSION}`)
-  const runUpdate = isAutoRun || await promptUser(`This will bump 'nuxt-spec' to version '${TARGET_VERSION}' by running \`${updateCmd}\`. Continue?`)
-  if (runUpdate) {
-    try {
-      showMessage(`Running \`${updateCmd}\`...`)
-      execSync(updateCmd, { stdio: 'inherit' })
-    } catch (error) {
-      console.error(`Error running \`${updateCmd}\`:\n`, error.message)
-    }
-  }
-
-  // 2) run 'nuxt prepare'
-  const prepareCmd = getPrepareCmd(packageManager)
-  const runPrepare = isAutoRun || await promptUser(`Nuxt types and auto-imports should be regenerated after the update. Do you want to run \`${prepareCmd}\` now?`)
-  if (runPrepare) {
-    try {
-      showMessage(`Running \`${prepareCmd}\`...`)
-      execSync(prepareCmd, { stdio: 'inherit' })
-    } catch (error) {
-      console.error(`Error running \`${prepareCmd}\`:\n`, error.message)
-    }
-  }
-
-  // 3) run 'playwright install'
-  const playwrightUpdateCmd = getPlaywrightInstallCmd(packageManager)
-  const runPlaywrightUpdate = isAutoRun || await promptUser(`Playwright browser runtimes might need to be updated for e2e tests. Do you want to run \`${playwrightUpdateCmd}\` now?`)
-  if (runPlaywrightUpdate) {
-    try {
-      showMessage(`Running \`${playwrightUpdateCmd}\`...`)
-      execSync(playwrightUpdateCmd, { stdio: 'inherit' })
-    } catch (error) {
-      console.error(`Error running \`${playwrightUpdateCmd}\`:\n`, error.message)
-    }
-  }
-
-  // 4) inform user
-  showMessage('')
-  showMessage('NUXT SPEC UPDATE COMPLETE', 2)
-  if (!runUpdate) {
-    showMessage(`Run \`${updateCmd}\` to update 'nuxt-spec'.`)
-  }
-  if (!runPrepare) {
-    showMessage(`Run \`${prepareCmd}\` to regenerate the Nuxt types and auto-imports.`)
-  }
-  if (!runPlaywrightUpdate) {
-    showMessage(`Run \`${playwrightUpdateCmd}\` to update the Playwright browser runtimes for e2e tests.`)
-  }
-
-  // force exit to prevent #20
-  process.exit(0)
-}

package/utils/screenshot/report-head.html

@@ -1,24 +0,0 @@
-<!DOCTYPE html>
-<html lang="en">
-<head>
-<meta charset="utf-8">
-<title>Visual Regression Report</title>
-<style>
-  body { font-family: system-ui, sans-serif; margin: 2rem; background: #f5f5f5; color: #222; }
-  h1 { font-size: 1.4rem; }
-  .failure { background: #fff; border: 1px solid #ddd; border-radius: 8px; padding: 1rem; margin: 1rem 0; box-shadow: 0 1px 3px rgba(0, 0, 0, .1); }
-  .failure h2 { font-size: 1rem; margin: 0 0 .5rem; }
-  .failure .message { color: #b00; font-size: .85rem; margin: 0 0 .75rem; }
-  .pair { display: flex; gap: 1rem; flex-wrap: wrap; }
-  .pair figure { margin: 0; flex: 1 1 0; min-width: 240px; }
-  .pair figcaption { font-size: .8rem; margin-bottom: .25rem; font-weight: bold; }
-  .pair figure:first-child figcaption { color: #0b0; }
-  .pair figure:last-child figcaption { color: #b00; }
-  .pair img { max-width: 100%; background: #fff; }
-  .pair figure:first-child img { border: 2px solid #0b0; }
-  .pair figure:last-child img { border: 2px solid #b00; }
-</style>
-</head>
-<body>
-<h1>Visual Regression Report - {{TIMESTAMP}}</h1>
-<!-- BEGIN failed screenshot entries -->

package/utils/screenshot/report-tail.html

@@ -1,4 +0,0 @@
-<!-- END failed screenshot entries -->
- <div>Generated by <a href="https://github.com/nuxt/nuxt-spec">Nuxt Spec</a> @ {{TIMESTAMP}}</div>
-</body>
-</html>

package/utils/screenshot/report-utils.ts

@@ -1,236 +0,0 @@
-import { exec } from 'node:child_process'
-import { appendFileSync, existsSync, readFileSync, statSync, unlinkSync, writeFileSync } from 'node:fs'
-import { platform } from 'node:os'
-import { resolve, sep } from 'node:path'
-import { fileURLToPath, pathToFileURL } from 'node:url'
-import type { DecodedPng } from 'fast-png'
-
-const templatesDir = resolve(fileURLToPath(import.meta.url), '..')
-const REPORT_ENTRY = readFileSync(resolve(templatesDir, 'report-entry.html'), 'utf-8')
-const REPORT_PATH = resolve(process.cwd(), '.nuxt/.nuxt-spec-report-path')
-const REPORT_LOCK = resolve(process.cwd(), '.nuxt/.nuxt-spec-report-lock')
-
-// create report file on first call
-// protected from parallel execution issues
-export function ensureReportCreated(targetDir = 'test/e2e'): void {
-  withConcurrentLock(() => {
-    let reportPath: string
-
-    if (!existsSync(targetDir)) {
-      throw new Error(`Target directory "${targetDir}" does not exist.`)
-    }
-
-    if (existsSync(REPORT_PATH)) {
-      // report file was already created
-      reportPath = readFileSync(REPORT_PATH, 'utf-8').trim()
-      // this shouldn't happen...
-      if (!existsSync(reportPath)) {
-        throw new Error(`Invalid data in "${REPORT_PATH}": Report file "${reportPath}" does not exist.`)
-      }
-    } else {
-      // for the first time, prepare and store new time-stamped file path
-      const fileTimestamp = process.env.SCREENSHOT_REPORT_TIMESTAMP ?? reportTimestamp(new Date())
-      reportPath = resolve(targetDir, '__current__', `report-${fileTimestamp}.html`)
-      writeFileSync(REPORT_PATH, reportPath)
-    }
-
-    // store the path for `appendToReport`
-    process.env.SCREENSHOT_REPORT_PATH = reportPath
-
-    // report file was already created
-    if (existsSync(reportPath)) return
-
-    // create new report file from template
-    const titleTimestamp = process.env.SCREENSHOT_REPORT_TITLE ?? reportTimestamp(new Date(), true)
-    const template = readFileSync(resolve(templatesDir, 'report-head.html'), 'utf-8')
-    const report = template.replace('{{TIMESTAMP}}', titleTimestamp)
-    writeFileSync(reportPath, report)
-  })
-}
-
-// append a side-by-side baseline/actual comparison
-// to the HTML report if the screenshots don't match
-// protected from parallel execution issues
-export function appendToReport(fileName: string, message: string, baseline: Uint8Array, actual: Uint8Array): void {
-  const baselineUri = `data:image/png;base64,${Buffer.from(baseline).toString('base64')}`
-  const actualUri = `data:image/png;base64,${Buffer.from(actual).toString('base64')}`
-
-  const entry = REPORT_ENTRY
-    .replace('{{FILE_NAME}}', escapeHtml(fileName))
-    .replace('{{MESSAGE}}', escapeHtml(message))
-    .replace('{{BASELINE_URI}}', baselineUri)
-    .replace('{{ACTUAL_URI}}', actualUri)
-
-  withConcurrentLock(() => {
-    const reportPath = process.env.SCREENSHOT_REPORT_PATH || (existsSync(REPORT_PATH)
-      ? readFileSync(REPORT_PATH, 'utf-8').trim()
-      : '')
-    if (!reportPath || !existsSync(reportPath)) return
-
-    appendFileSync(reportPath, entry)
-  })
-}
-
-// Vitest globalSetup entry point
-// - computes stable timestamp values and exposes them via env variables
-// - the report file itself is created lazily on first compareScreenshot call
-// - provides a callback to close the HTML report once tests are finished (if it was created)
-export function screenshotSetup() {
-  const NOW = new Date()
-  const fileTimestamp = reportTimestamp(NOW)
-  const titleTimestamp = reportTimestamp(NOW, true)
-
-  process.env.SCREENSHOT_REPORT_TIMESTAMP = fileTimestamp
-  process.env.SCREENSHOT_REPORT_TITLE = titleTimestamp
-
-  // callback that is executed upon Vitest teardown phase
-  return () => {
-    if (!existsSync(REPORT_PATH)) return
-
-    const reportPath = readFileSync(REPORT_PATH, 'utf-8').trim()
-    unlinkSync(REPORT_PATH)
-
-    if (!reportPath) return
-    if (!existsSync(reportPath)) return
-
-    // add "success" / "error" message as a conclusion
-    const reportBody = readFileSync(reportPath, 'utf-8')
-    const hasFailure = reportBody.includes('<div class="failure"')
-    if (hasFailure) {
-      appendFileSync(reportPath, '<p style="color: #b00; font-weight: 700; font-size: 18px;">Tests finished with errors</p>\n')
-    } else {
-      appendFileSync(reportPath, '<p style="color: #0b0; font-weight: 700; font-size: 18px;">All tests have passed</p>\n')
-    }
-
-    // wrap the report up with a footer
-    let footer = readFileSync(resolve(templatesDir, 'report-tail.html'), 'utf-8')
-    footer = footer.replace('{{TIMESTAMP}}', new Date().toISOString())
-    appendFileSync(reportPath, footer)
-    console.log(`\n(nuxt-spec) Visual regression report available at:\n${pathToFileURL(reportPath).href}`)
-
-    if (!process.env.CI) {
-      console.log('(nuxt-spec) Opening report in default browser...')
-      const openCmd
-        = platform() === 'darwin'
-          ? `open "${reportPath}"`
-          : platform() === 'win32'
-            ? `start "" "${reportPath}"`
-            : `xdg-open "${reportPath}"`
-      exec(openCmd, (err) => {
-        if (err) {
-          console.log('(nuxt-spec) Failed to automatically open report')
-        }
-      })
-    }
-
-    console.log('\n')
-  }
-}
-
-// helper to keep user-provided targetDir inside the current project root
-export function resolveWithin(base: string, segment: string): string {
-  const target = resolve(base, segment)
-  if (target !== base && !target.startsWith(base + sep)) {
-    throw new Error(`Invalid path: "${segment}" resolves outside of "${base}"`)
-  }
-  return target
-}
-
-// helper for bridging difference between Vitest PNG saving and fast-png encoding
-export function toRGBA(img: DecodedPng): Uint8Array {
-  const { width, height, data, channels = 4 } = img
-  if (channels === 4) return data as Uint8Array
-  const pixels = width * height
-  const rgba = new Uint8Array(pixels * 4)
-  for (let i = 0; i < pixels; i++) {
-    const src = i * 3
-    rgba[i * 4 + 0] = data[src + 0] ?? 0
-    rgba[i * 4 + 1] = data[src + 1] ?? 0
-    rgba[i * 4 + 2] = data[src + 2] ?? 0
-    rgba[i * 4 + 3] = 255
-  }
-  return rgba
-}
-
-// protection from parallel execution issues
-function withConcurrentLock<T>(fn: () => T): T {
-  const start = Date.now()
-
-  while (true) {
-    try {
-      // try acquiring the lock
-      writeFileSync(REPORT_LOCK, String(process.pid), { flag: 'wx' })
-      break
-    } catch (error) {
-      // we only expect "file already exists" error
-      // otherwise it is an issue
-      const code = (error as NodeJS.ErrnoException).code
-      if (code !== 'EEXIST') throw error
-
-      try {
-        const lockAge = Date.now() - statSync(REPORT_LOCK).mtimeMs
-        if (lockAge > 30_000) {
-          // stale lock
-          unlinkSync(REPORT_LOCK)
-          continue
-        }
-      } catch {
-        // lock disappeared between checks, retry acquisition
-      }
-
-      if (Date.now() - start > 10_000) {
-        // not successful in 10 minutes, give up
-        throw new Error('Timed out while waiting for screenshot report lock', {
-          cause: error,
-        })
-      }
-
-      // sleep before next attempt
-      Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 25)
-    }
-  }
-
-  try {
-    return fn()
-  } finally {
-    try {
-      unlinkSync(REPORT_LOCK)
-    } catch {
-      // lock file may already be removed
-    }
-  }
-}
-
-// timestamp string
-// separators=false produces YYYYMMDDHHMMSS for report file name
-// separators=true produces YYYY-MM-DD HH:MM:SS for report title
-function reportTimestamp(date: Date, separators = false): string {
-  const pad2 = (n: number) => String(n).padStart(2, '0')
-  const dateSeparator = separators ? '-' : ''
-  const midSeparator = separators ? ' ' : ''
-  const timeSeparator = separators ? ':' : ''
-  return [
-    date.getFullYear(),
-    dateSeparator,
-    pad2(date.getMonth() + 1),
-    dateSeparator,
-    pad2(date.getDate()),
-    midSeparator,
-    pad2(date.getHours()),
-    timeSeparator,
-    pad2(date.getMinutes()),
-    timeSeparator,
-    pad2(date.getSeconds()),
-  ].join('')
-}
-
-// helper to escape a string for safe interpolation into the HTML report
-function escapeHtml(value: string): string {
-  return value.replace(/[&<>"']/g, char => ({
-    '&': '&amp;',
-    '<': '&lt;',
-    '>': '&gt;',
-    '"': '&quot;',
-    '\'': '&#39;',
-  }[char] ?? char))
-}