create-appraisejs 0.3.0-alpha.0 → 0.3.0

package/templates/starter/public/globe.svg

@@ -0,0 +1 @@
+<svg fill="none" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 16"><g clip-path="url(#a)"><path fill-rule="evenodd" clip-rule="evenodd" d="M10.27 14.1a6.5 6.5 0 0 0 3.67-3.45q-1.24.21-2.7.34-.31 1.83-.97 3.1M8 16A8 8 0 1 0 8 0a8 8 0 0 0 0 16m.48-1.52a7 7 0 0 1-.96 0H7.5a4 4 0 0 1-.84-1.32q-.38-.89-.63-2.08a40 40 0 0 0 3.92 0q-.25 1.2-.63 2.08a4 4 0 0 1-.84 1.31zm2.94-4.76q1.66-.15 2.95-.43a7 7 0 0 0 0-2.58q-1.3-.27-2.95-.43a18 18 0 0 1 0 3.44m-1.27-3.54a17 17 0 0 1 0 3.64 39 39 0 0 1-4.3 0 17 17 0 0 1 0-3.64 39 39 0 0 1 4.3 0m1.1-1.17q1.45.13 2.69.34a6.5 6.5 0 0 0-3.67-3.44q.65 1.26.98 3.1M8.48 1.5l.01.02q.41.37.84 1.31.38.89.63 2.08a40 40 0 0 0-3.92 0q.25-1.2.63-2.08a4 4 0 0 1 .85-1.32 7 7 0 0 1 .96 0m-2.75.4a6.5 6.5 0 0 0-3.67 3.44 29 29 0 0 1 2.7-.34q.31-1.83.97-3.1M4.58 6.28q-1.66.16-2.95.43a7 7 0 0 0 0 2.58q1.3.27 2.95.43a18 18 0 0 1 0-3.44m.17 4.71q-1.45-.12-2.69-.34a6.5 6.5 0 0 0 3.67 3.44q-.65-1.27-.98-3.1" fill="#666"/></g><defs><clipPath id="a"><path fill="#fff" d="M0 0h16v16H0z"/></clipPath></defs></svg>

package/templates/starter/public/logo.svg

@@ -0,0 +1,13 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 128 128">
+  <line class="ln" x1="14" y1="64" x2="62" y2="64" stroke-width="4.5" stroke-linecap="round"/>
+  <circle class="dot" cx="16" cy="64" r="6.5" stroke-width="3.5"/>
+  <circle class="dot" cx="42" cy="64" r="8.5" stroke-width="3.5"/>
+  <circle class="ring" cx="88" cy="64" r="26" fill="none" stroke-width="7"/>
+  <polyline class="ck" points="76,66 85,76 102,54" fill="none" stroke-width="6.5" stroke-linecap="round" stroke-linejoin="round"/>
+  <style>
+    .ln{stroke:#d4d4d4}
+    .dot{fill:#999;stroke:#d4d4d4}
+    .ring{stroke:#eee}
+    .ck{stroke:#5cb85c}
+  </style>
+</svg>

package/templates/starter/public/next.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 394 80"><path fill="#000" d="M262 0h68.5v12.7h-27.2v66.6h-13.6V12.7H262V0ZM149 0v12.7H94v20.4h44.3v12.6H94v21h55v12.6H80.5V0h68.7zm34.3 0h-17.8l63.8 79.4h17.9l-32-39.7 32-39.6h-17.9l-23 28.6-23-28.6zm18.3 56.7-9-11-27.1 33.7h17.8l18.3-22.7z"/><path fill="#000" d="M81 79.3 17 0H0v79.3h13.6V17l50.2 62.3H81Zm252.6-.4c-1 0-1.8-.4-2.5-1s-1.1-1.6-1.1-2.6.3-1.8 1-2.5 1.6-1 2.6-1 1.8.3 2.5 1a3.4 3.4 0 0 1 .6 4.3 3.7 3.7 0 0 1-3 1.8zm23.2-33.5h6v23.3c0 2.1-.4 4-1.3 5.5a9.1 9.1 0 0 1-3.8 3.5c-1.6.8-3.5 1.3-5.7 1.3-2 0-3.7-.4-5.3-1s-2.8-1.8-3.7-3.2c-.9-1.3-1.4-3-1.4-5h6c.1.8.3 1.6.7 2.2s1 1.2 1.6 1.5c.7.4 1.5.5 2.4.5 1 0 1.8-.2 2.4-.6a4 4 0 0 0 1.6-1.8c.3-.8.5-1.8.5-3V45.5zm30.9 9.1a4.4 4.4 0 0 0-2-3.3 7.5 7.5 0 0 0-4.3-1.1c-1.3 0-2.4.2-3.3.5-.9.4-1.6 1-2 1.6a3.5 3.5 0 0 0-.3 4c.3.5.7.9 1.3 1.2l1.8 1 2 .5 3.2.8c1.3.3 2.5.7 3.7 1.2a13 13 0 0 1 3.2 1.8 8.1 8.1 0 0 1 3 6.5c0 2-.5 3.7-1.5 5.1a10 10 0 0 1-4.4 3.5c-1.8.8-4.1 1.2-6.8 1.2-2.6 0-4.9-.4-6.8-1.2-2-.8-3.4-2-4.5-3.5a10 10 0 0 1-1.7-5.6h6a5 5 0 0 0 3.5 4.6c1 .4 2.2.6 3.4.6 1.3 0 2.5-.2 3.5-.6 1-.4 1.8-1 2.4-1.7a4 4 0 0 0 .8-2.4c0-.9-.2-1.6-.7-2.2a11 11 0 0 0-2.1-1.4l-3.2-1-3.8-1c-2.8-.7-5-1.7-6.6-3.2a7.2 7.2 0 0 1-2.4-5.7 8 8 0 0 1 1.7-5 10 10 0 0 1 4.3-3.5c2-.8 4-1.2 6.4-1.2 2.3 0 4.4.4 6.2 1.2 1.8.8 3.2 2 4.3 3.4 1 1.4 1.5 3 1.5 5h-5.8z"/></svg>

package/templates/starter/public/vercel.svg

@@ -0,0 +1 @@
+<svg fill="none" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1155 1000"><path d="m577.3 0 577.4 1000H0z" fill="#fff"/></svg>

package/templates/starter/public/window.svg

@@ -0,0 +1 @@
+<svg fill="none" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 16"><path fill-rule="evenodd" clip-rule="evenodd" d="M1.5 2.5h13v10a1 1 0 0 1-1 1h-11a1 1 0 0 1-1-1zM0 1h16v11.5a2.5 2.5 0 0 1-2.5 2.5h-11A2.5 2.5 0 0 1 0 12.5zm3.75 4.5a.75.75 0 1 0 0-1.5.75.75 0 0 0 0 1.5M7 4.75a.75.75 0 1 1-1.5 0 .75.75 0 0 1 1.5 0m1.75.75a.75.75 0 1 0 0-1.5.75.75 0 0 0 0 1.5" fill="#666"/></svg>

package/templates/starter/scripts/build-step-registry.ts

@@ -0,0 +1,33 @@
+#!/usr/bin/env tsx
+
+import path from 'path'
+import { promises as fs } from 'fs'
+import { fileURLToPath } from 'url'
+import { buildStepRegistry } from './lib/template-step-registry'
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url))
+const repoRoot = path.join(__dirname, '..')
+const registryRoot = path.join(repoRoot, 'packages', 'appraisejs', 'registry', 'template-steps')
+const fragmentsRoot = path.join(registryRoot, 'fragments')
+
+async function writeRegistry(): Promise<void> {
+  const { manifest, fragments } = await buildStepRegistry(repoRoot)
+
+  await fs.rm(registryRoot, { recursive: true, force: true })
+  await fs.mkdir(fragmentsRoot, { recursive: true })
+
+  await fs.writeFile(path.join(registryRoot, 'manifest.json'), JSON.stringify(manifest, null, 2) + '\n')
+
+  for (const fragment of fragments) {
+    const fragmentPath = path.join(registryRoot, fragment.path)
+    await fs.mkdir(path.dirname(fragmentPath), { recursive: true })
+    await fs.writeFile(fragmentPath, fragment.content)
+  }
+
+  console.log(`Generated template-step registry with ${manifest.steps.length} step(s) at ${registryRoot}`)
+}
+
+writeRegistry().catch(error => {
+  console.error(error)
+  process.exit(1)
+})

package/templates/starter/scripts/install-playwright.ts

@@ -0,0 +1,29 @@
+#!/usr/bin/env tsx
+
+import { execa } from 'execa'
+import { createRequire } from 'module'
+import path from 'path'
+
+const require = createRequire(import.meta.url)
+
+/**
+ * Installs Playwright browsers for the current platform.
+ * On Linux, also installs OS-level browser dependencies.
+ */
+async function main(): Promise<void> {
+  const playwrightPackageJsonPath = require.resolve('playwright/package.json')
+  const playwrightCliPath = path.join(path.dirname(playwrightPackageJsonPath), 'cli.js')
+  const browserArgs = process.argv.slice(2)
+
+  await execa(process.execPath, [playwrightCliPath, 'install', ...browserArgs], {
+    stdio: 'inherit',
+  })
+
+  if (process.platform === 'linux') {
+    await execa(process.execPath, [playwrightCliPath, 'install-deps', ...browserArgs], {
+      stdio: 'inherit',
+    })
+  }
+}
+
+await main()

package/templates/starter/scripts/install-template-step.ts

@@ -0,0 +1,128 @@
+#!/usr/bin/env tsx
+
+import path from 'path'
+import { existsSync, promises as fs } from 'fs'
+import { spawn } from 'child_process'
+import { installTemplateStepPayload, type TemplateStepInstallPayload } from './lib/template-step-installer'
+
+type CliOptions = {
+  payloadFile: string
+  overwrite: boolean
+  dryRun: boolean
+}
+
+function parseArgs(argv: string[]): CliOptions {
+  let payloadFile = ''
+  let overwrite = false
+  let dryRun = false
+
+  for (let index = 0; index < argv.length; index++) {
+    const current = argv[index]
+    if (current === '--payload-file') {
+      payloadFile = argv[index + 1] ?? ''
+      index++
+      continue
+    }
+    if (current === '--overwrite') {
+      overwrite = true
+      continue
+    }
+    if (current === '--dry-run') {
+      dryRun = true
+      continue
+    }
+  }
+
+  if (!payloadFile) {
+    throw new Error('Missing required --payload-file argument.')
+  }
+
+  return {
+    payloadFile,
+    overwrite,
+    dryRun,
+  }
+}
+
+function detectPackageManager(projectRoot: string): 'npm' | 'pnpm' | 'yarn' | 'bun' {
+  const userAgent = process.env.npm_config_user_agent ?? ''
+  if (userAgent.startsWith('pnpm/')) return 'pnpm'
+  if (userAgent.startsWith('yarn/')) return 'yarn'
+  if (userAgent.startsWith('bun/')) return 'bun'
+  if (userAgent.startsWith('npm/')) return 'npm'
+
+  if (existsSync(path.join(projectRoot, 'pnpm-lock.yaml'))) return 'pnpm'
+  if (existsSync(path.join(projectRoot, 'yarn.lock'))) return 'yarn'
+  if (existsSync(path.join(projectRoot, 'bun.lockb'))) return 'bun'
+  return 'npm'
+}
+
+function getRunArgs(packageManager: 'npm' | 'pnpm' | 'yarn' | 'bun', scriptName: string): string[] {
+  if (packageManager === 'npm' || packageManager === 'pnpm' || packageManager === 'bun') {
+    return ['run', scriptName]
+  }
+
+  return ['run', scriptName]
+}
+
+async function runScript(projectRoot: string, packageManager: 'npm' | 'pnpm' | 'yarn' | 'bun', scriptName: string): Promise<void> {
+  await new Promise<void>((resolve, reject) => {
+    const child = spawn(packageManager, getRunArgs(packageManager, scriptName), {
+      cwd: projectRoot,
+      stdio: 'inherit',
+      env: process.env,
+    })
+
+    child.on('error', reject)
+    child.on('close', code => {
+      if (code === 0) {
+        resolve()
+        return
+      }
+
+      reject(new Error(`${packageManager} run ${scriptName} exited with code ${code}`))
+    })
+  })
+}
+
+async function readPayload(payloadFile: string): Promise<TemplateStepInstallPayload> {
+  const raw = await fs.readFile(payloadFile, 'utf8')
+  return JSON.parse(raw) as TemplateStepInstallPayload
+}
+
+async function main(): Promise<void> {
+  const options = parseArgs(process.argv.slice(2))
+  const projectRoot = process.cwd()
+  const payloadFile = path.resolve(projectRoot, options.payloadFile)
+  const payload = await readPayload(payloadFile)
+
+  const result = await installTemplateStepPayload(payload, {
+    projectRoot,
+    overwrite: options.overwrite,
+    dryRun: options.dryRun,
+  })
+
+  console.log(result.reason)
+  console.log(`Target file: ${path.relative(projectRoot, result.targetFilePath)}`)
+
+  if (options.dryRun) {
+    if (result.changed) {
+      console.log('Dry run: would run sync-template-step-groups')
+      console.log('Dry run: would run sync-template-steps')
+    }
+    return
+  }
+
+  if (!result.changed) {
+    return
+  }
+
+  const packageManager = detectPackageManager(projectRoot)
+  await runScript(projectRoot, packageManager, 'sync-template-step-groups')
+  await runScript(projectRoot, packageManager, 'sync-template-steps')
+}
+
+main().catch(error => {
+  console.error(error instanceof Error ? error.message : String(error))
+  process.exit(1)
+})

package/templates/starter/scripts/lib/filename-utils.test.ts

@@ -0,0 +1,24 @@
+import { describe, expect, it } from 'vitest'
+import { extractLocatorGroupName, extractTestSuiteNameFromFilename } from './filename-utils'
+
+describe('filename utils', () => {
+  it('extractTestSuiteNameFromFilename handles .feature extension', () => {
+    expect(extractTestSuiteNameFromFilename('login.feature')).toBe('login')
+  })
+
+  it('extractTestSuiteNameFromFilename handles nested unix path', () => {
+    expect(extractTestSuiteNameFromFilename('/a/b/login-validation.feature')).toBe('login-validation')
+  })
+
+  it('extractTestSuiteNameFromFilename handles windows path', () => {
+    expect(extractTestSuiteNameFromFilename('a\\b\\suite.feature')).toBe('suite')
+  })
+
+  it('extractLocatorGroupName handles json extension', () => {
+    expect(extractLocatorGroupName('buttons.json')).toBe('buttons')
+  })
+
+  it('extractLocatorGroupName handles nested path', () => {
+    expect(extractLocatorGroupName('/a/b/users.json')).toBe('users')
+  })
+})

package/templates/starter/scripts/lib/filename-utils.ts

@@ -0,0 +1,24 @@
+import { extractModulePathFromAutomationFile } from '../../src/lib/template-sync-utils'
+
+/**
+ * Extracts test-suite identity from a `.feature` filename.
+ */
+export function extractTestSuiteNameFromFilename(filePath: string): string {
+  const fileName = filePath.split(/[/\\]/).pop() || ''
+  return fileName.replace(/\.feature$/, '')
+}
+
+/**
+ * Extracts locator group name from a locator `.json` file path.
+ */
+export function extractLocatorGroupName(filePath: string): string {
+  const fileName = filePath.split(/[/\\]/).pop() || ''
+  return fileName.replace('.json', '')
+}
+
+/**
+ * Resolves module path from a locator file under `automation/locators`.
+ */
+export function extractModulePathFromLocatorFile(filePath: string, baseDir: string): string {
+  return extractModulePathFromAutomationFile(filePath, baseDir, 'locators')
+}

package/templates/starter/scripts/lib/jsdoc-parser.test.ts

@@ -0,0 +1,63 @@
+import { describe, expect, it } from 'vitest'
+import { parseGroupJSDoc } from './jsdoc-parser'
+
+describe('parseGroupJSDoc', () => {
+  it('parses ACTION group metadata', () => {
+    const content = `/**
+ * @name Auth Actions
+ * @description auth flows
+ * @type ACTION
+ */`
+    expect(parseGroupJSDoc(content)).toEqual({
+      name: 'Auth Actions',
+      description: 'auth flows',
+      type: 'ACTION',
+    })
+  })
+
+  it('parses VALIDATION group metadata', () => {
+    const content = `/**
+ * @name Auth Validations
+ * @type VALIDATION
+ */`
+    expect(parseGroupJSDoc(content)).toEqual({
+      name: 'Auth Validations',
+      description: null,
+      type: 'VALIDATION',
+    })
+  })
+
+  it('returns null when @type is missing', () => {
+    const content = `/**
+ * @name Missing Type
+ */`
+    expect(parseGroupJSDoc(content)).toBeNull()
+  })
+
+  it('returns null when @name is missing', () => {
+    const content = `/**
+ * @type ACTION
+ */`
+    expect(parseGroupJSDoc(content)).toBeNull()
+  })
+
+  it('returns null for empty content', () => {
+    expect(parseGroupJSDoc('')).toBeNull()
+  })
+
+  it('parses when imports are before jsdoc', () => {
+    const content = `import { x } from 'y'
+/**
+ * @name Imported Group
+ * @type ACTION
+ */`
+    expect(parseGroupJSDoc(content)?.name).toBe('Imported Group')
+  })
+
+  it('returns null for malformed close', () => {
+    const content = `/**
+ * @name Broken
+ * @type ACTION`
+    expect(parseGroupJSDoc(content)).toBeNull()
+  })
+})

package/templates/starter/scripts/lib/jsdoc-parser.ts

@@ -0,0 +1,88 @@
+import { TemplateStepGroupType } from '@prisma/client'
+
+export interface StepGroupJSDoc {
+  name: string
+  description: string | null
+  type: TemplateStepGroupType
+}
+
+/**
+ * Parses JSDoc comment to extract top-of-file step group metadata.
+ * Returns null if no valid group JSDoc is found.
+ */
+export function parseGroupJSDoc(content: string): StepGroupJSDoc | null {
+  const lines = content.split('\n')
+
+  if (lines.length === 0) {
+    return null
+  }
+
+  let startLine = 0
+  while (startLine < lines.length) {
+    const line = lines[startLine].trim()
+    if (line === '' || line.startsWith('import ')) {
+      startLine++
+      continue
+    }
+    break
+  }
+
+  if (startLine >= lines.length || !lines[startLine].trim().startsWith('/**')) {
+    return null
+  }
+
+  let hasType = false
+  let endLine = -1
+  let name: string | null = null
+  let description: string | null = null
+  let type: string | null = null
+
+  const maxLines = Math.min(lines.length, startLine + 50)
+  for (let i = startLine; i < maxLines; i++) {
+    const line = lines[i].trim()
+
+    if (line.includes('*/')) {
+      const beforeClose = line.split('*/')[0].trim()
+
+      if (beforeClose.startsWith('* @name') || beforeClose.startsWith('*@name')) {
+        const match = beforeClose.match(/@name\s+(.+)/)
+        if (match) name = match[1].trim()
+      } else if (beforeClose.startsWith('* @description') || beforeClose.startsWith('*@description')) {
+        const match = beforeClose.match(/@description\s+(.+)/)
+        if (match) description = match[1].trim() || null
+      } else if (beforeClose.startsWith('* @type') || beforeClose.startsWith('*@type')) {
+        hasType = true
+        const match = beforeClose.match(/@type\s+(.+)/)
+        if (match) type = match[1].trim()
+      }
+
+      endLine = i
+      break
+    } else if (line.startsWith('* @name') || line.startsWith('*@name')) {
+      const match = line.match(/@name\s+(.+)/)
+      if (match) name = match[1].trim()
+    } else if (line.startsWith('* @description') || line.startsWith('*@description')) {
+      const match = line.match(/@description\s+(.+)/)
+      if (match) description = match[1].trim() || null
+    } else if (line.startsWith('* @type') || line.startsWith('*@type')) {
+      hasType = true
+      const match = line.match(/@type\s+(.+)/)
+      if (match) type = match[1].trim()
+    }
+  }
+
+  if (hasType && endLine >= 0 && name && type) {
+    const normalizedType = type.toUpperCase()
+    if (normalizedType !== 'ACTION' && normalizedType !== 'VALIDATION') {
+      throw new Error(`Invalid @type value: ${type}. Must be ACTION or VALIDATION`)
+    }
+
+    return {
+      name: name.trim(),
+      description: description ? description.trim() : null,
+      type: normalizedType as TemplateStepGroupType,
+    }
+  }
+
+  return null
+}

package/templates/starter/scripts/lib/step-file-parser.test.ts

@@ -0,0 +1,71 @@
+import { describe, expect, it } from 'vitest'
+import { mapTypeToParameterType, parseStepFile, parseStepJSDoc } from './step-file-parser'
+
+describe('parseStepJSDoc', () => {
+  it('parses valid step jsdoc', () => {
+    const content = `/**
+ * @name Click Save
+ * @description clicks save button
+ * @icon MOUSE
+ */
+When("click save", async function () {})`
+    expect(parseStepJSDoc(content, 5)).toEqual({
+      name: 'Click Save',
+      description: 'clicks save button',
+      icon: 'MOUSE',
+    })
+  })
+
+  it('returns null when @icon is missing', () => {
+    const content = `/**
+ * @name Click Save
+ */
+When("click save", async function () {})`
+    expect(parseStepJSDoc(content, 4)).toBeNull()
+  })
+
+  it('returns null when @name is missing', () => {
+    const content = `/**
+ * @icon MOUSE
+ */
+When("click save", async function () {})`
+    expect(parseStepJSDoc(content, 4)).toBeNull()
+  })
+})
+
+describe('mapTypeToParameterType', () => {
+  it('maps SelectorName', () => expect(mapTypeToParameterType('SelectorName')).toBe('LOCATOR'))
+  it('maps string', () => expect(mapTypeToParameterType('string')).toBe('STRING'))
+  it('maps number', () => expect(mapTypeToParameterType('number')).toBe('NUMBER'))
+  it('maps int', () => expect(mapTypeToParameterType('int')).toBe('NUMBER'))
+  it('maps boolean', () => expect(mapTypeToParameterType('boolean')).toBe('BOOLEAN'))
+  it('maps Date', () => expect(mapTypeToParameterType('Date')).toBe('DATE'))
+  it('throws on unsupported type', () => expect(() => mapTypeToParameterType('unknown')).toThrow())
+})
+
+describe('parseStepFile', () => {
+  it('parses minimal valid step file with one When step', () => {
+    const content = `/**
+ * @name Auth Steps
+ * @type ACTION
+ */
+import { When } from "@cucumber/cucumber";
+/**
+ * @name Enter Email
+ * @description fills email
+ * @icon MOUSE
+ */
+When("enter {string}", async function (value: string) {
+  // no-op
+});`
+
+    const parsed = parseStepFile(content, 'automation/steps/actions/auth.step.ts')
+    expect(parsed).not.toBeNull()
+    expect(parsed?.group.name).toBe('Auth Steps')
+    expect(parsed?.steps).toHaveLength(1)
+    expect(parsed?.steps[0].signature).toBe('enter {string}')
+    expect(parsed?.steps[0].keyword).toBe('When')
+    expect(parsed?.steps[0].source).toContain('@name Enter Email')
+    expect(parsed?.steps[0].source).toContain('When("enter {string}"')
+  })
+})