create-appraisejs 0.3.0-alpha.0 → 0.3.0-alpha.1

package/templates/blank/public/favicon.svg

@@ -0,0 +1,8 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 128 128">
+  <circle class="ring" cx="64" cy="64" r="50" fill="none" stroke-width="5.5"/>
+  <polyline class="ck" points="38,66 55,83 92,41" fill="none" stroke-width="9" stroke-linecap="round" stroke-linejoin="round"/>
+  <style>
+    .ring{stroke:#d4d4d4}
+    .ck{stroke:#5cb85c}
+  </style>
+</svg>

package/templates/blank/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/blank/scripts/sync-appraise-base-template.ts

@@ -0,0 +1,244 @@
+#!/usr/bin/env node
+/**
+ * Sync the starter template from the base app (repo root).
+ * Copies src/, automation/, prisma/, public/, scripts/, selected internal packages,
+ * and root config files into templates/starter/ while preserving template-only files.
+ *
+ * Usage: npx tsx scripts/sync-appraise-base-template.ts
+ * Or: npm run sync-template
+ */
+import { cpSync, existsSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync } from 'fs'
+import { dirname, join } from 'path'
+import { fileURLToPath } from 'url'
+import { shouldBackfillLegacyEnvironmentConfig, shouldExcludeTemplatePath } from '../src/lib/template-sync-utils'
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+const repoRoot = join(__dirname, '..')
+const target = join(repoRoot, 'templates', 'starter')
+
+/**
+ * Delegates template path exclusion decisions to shared sync rules.
+ */
+function shouldExclude(relativePath: string): boolean {
+  return shouldExcludeTemplatePath(relativePath)
+}
+
+/**
+ * Recursively copies a directory while applying path-level exclusion rules.
+ */
+function copyDirWithFilter(
+  src: string,
+  dest: string,
+  options: { base?: string; shouldExcludePath?: (relativePath: string) => boolean } = {},
+): void {
+  if (!existsSync(src)) return
+
+  const { base = src, shouldExcludePath = shouldExclude } = options
+  mkdirSync(dest, { recursive: true })
+  for (const entry of readdirSync(src, { withFileTypes: true })) {
+    const srcPath = join(src, entry.name)
+    const relativePath = srcPath.slice(base.length + 1).replace(/\\/g, '/')
+    if (shouldExcludePath(relativePath)) continue
+
+    const destPath = join(dest, entry.name)
+    if (entry.isDirectory()) {
+      copyDirWithFilter(srcPath, destPath, { base, shouldExcludePath })
+      continue
+    }
+
+    cpSync(srcPath, destPath, { force: true })
+  }
+}
+
+/**
+ * Copies a file and ensures destination directory exists.
+ */
+function copyFile(src: string, dest: string): void {
+  mkdirSync(dirname(dest), { recursive: true })
+  cpSync(src, dest, { force: true })
+}
+
+/**
+ * Resets reports directory in template to an empty starter shape.
+ */
+function resetAutomationReports(templateRoot: string): void {
+  const reportsRoot = join(templateRoot, 'automation', 'reports')
+  rmSync(reportsRoot, { recursive: true, force: true })
+  mkdirSync(join(reportsRoot, 'logs'), { recursive: true })
+  mkdirSync(join(reportsRoot, 'traces'), { recursive: true })
+}
+
+/**
+ * Resets template locator map to a clean empty array.
+ */
+function resetAutomationLocatorMap(templateRoot: string): void {
+  const locatorMapPath = join(templateRoot, 'automation', 'mapping', 'locator-map.json')
+  mkdirSync(dirname(locatorMapPath), { recursive: true })
+  writeFileSync(locatorMapPath, '[]\n')
+}
+
+/**
+ * Backfills legacy environment config when new location is missing.
+ */
+function syncLegacyEnvironmentConfig(): void {
+  const legacyEnvironmentsDir = join(repoRoot, 'src', 'tests', 'config', 'environments')
+  const targetEnvironmentsDir = join(target, 'automation', 'config', 'environments')
+  const targetEnvironmentsFile = join(targetEnvironmentsDir, 'environments.json')
+
+  if (!shouldBackfillLegacyEnvironmentConfig(existsSync(targetEnvironmentsFile), existsSync(legacyEnvironmentsDir))) {
+    return
+  }
+
+  mkdirSync(targetEnvironmentsDir, { recursive: true })
+  cpSync(legacyEnvironmentsDir, targetEnvironmentsDir, { recursive: true, force: true })
+  console.log('Backfilled automation/config/environments from legacy src/tests config.')
+}
+
+type InternalPackageSyncConfig = {
+  name: string
+  directories: string[]
+}
+
+const INTERNAL_PACKAGES: InternalPackageSyncConfig[] = [
+  { name: 'cucumber-runtime', directories: ['src'] },
+  { name: 'locator-picker-companion', directories: ['src', 'dist'] },
+]
+
+/**
+ * Syncs one internal package into template/packages.
+ */
+function syncInternalPackage({ name, directories }: InternalPackageSyncConfig): void {
+  const packageRoot = join(repoRoot, 'packages', name)
+  const packageTarget = join(target, 'packages', name)
+
+  rmSync(packageTarget, { recursive: true, force: true })
+  mkdirSync(packageTarget, { recursive: true })
+
+  copyFile(join(packageRoot, 'package.json'), join(packageTarget, 'package.json'))
+  copyFile(join(packageRoot, 'tsconfig.json'), join(packageTarget, 'tsconfig.json'))
+
+  const shouldExcludeInternalPackagePath = (relativePath: string): boolean => {
+    if (relativePath === 'dist' || relativePath.startsWith('dist/')) {
+      return false
+    }
+
+    return shouldExclude(relativePath)
+  }
+
+  for (const directory of directories) {
+    copyDirWithFilter(join(packageRoot, directory), join(packageTarget, directory), {
+      base: packageRoot,
+      shouldExcludePath: shouldExcludeInternalPackagePath,
+    })
+  }
+}
+
+function main(): void {
+  const readmePath = join(target, 'README.md')
+  const appraisejsConfigPath = join(target, 'appraisejs.config.json')
+  const savedReadme = existsSync(readmePath) ? readFileSync(readmePath, 'utf8') : null
+  const savedAppraisejsConfig = existsSync(appraisejsConfigPath) ? readFileSync(appraisejsConfigPath, 'utf8') : null
+
+  rmSync(target, { recursive: true, force: true })
+  mkdirSync(target, { recursive: true })
+
+  console.log('Copying src/...')
+  copyDirWithFilter(join(repoRoot, 'src'), join(target, 'src'))
+
+console.log('Copying automation/...')
+copyDirWithFilter(join(repoRoot, 'automation'), join(target, 'automation'))
+syncLegacyEnvironmentConfig()
+resetAutomationReports(target)
+resetAutomationLocatorMap(target)
+
+for (const internalPackage of INTERNAL_PACKAGES) {
+  console.log(`Copying internal package ${internalPackage.name}...`)
+  syncInternalPackage(internalPackage)
+}
+
+console.log('Copying prisma/...')
+copyDirWithFilter(join(repoRoot, 'prisma'), join(target, 'prisma'))
+console.log('Copying public/...')
+copyDirWithFilter(join(repoRoot, 'public'), join(target, 'public'))
+console.log('Copying scripts/...')
+copyDirWithFilter(join(repoRoot, 'scripts'), join(target, 'scripts'))
+
+const legacyTestsRoot = join(target, 'src', 'tests')
+if (existsSync(legacyTestsRoot)) {
+  rmSync(legacyTestsRoot, { recursive: true, force: true })
+}
+
+const configFiles = [
+  '.gitignore',
+  'eslint.config.mjs',
+  'tailwind.config.ts',
+  'tsconfig.json',
+  'postcss.config.mjs',
+  'components.json',
+  'next.config.ts',
+  'next-env.d.ts',
+  '.env.example',
+  'package-lock.json',
+  'yarn.lock',
+  'pnpm-lock.yaml',
+  'bun.lockb',
+]
+for (const name of configFiles) {
+  const src = join(repoRoot, name)
+  if (existsSync(src)) {
+    copyFile(src, join(target, name))
+  }
+}
+
+const cucumberSource = join(repoRoot, 'cucumber.mjs')
+if (existsSync(cucumberSource)) {
+  copyFile(cucumberSource, join(target, 'cucumber.mjs'))
+  console.log('Synced cucumber.mjs to template')
+}
+
+const vscodeSource = join(repoRoot, '.vscode')
+if (existsSync(vscodeSource)) {
+  cpSync(vscodeSource, join(target, '.vscode'), { recursive: true, force: true })
+  console.log('Synced .vscode to template')
+}
+
+const rootPkg = JSON.parse(readFileSync(join(repoRoot, 'package.json'), 'utf8')) as {
+  scripts: Record<string, string>
+  [key: string]: unknown
+}
+rootPkg.scripts = {
+  ...rootPkg.scripts,
+  build: 'npm run build:local',
+  'build:local':
+    'npm run generate-db-client && npm run build:cucumber-runtime && npm run build:locator-picker-companion && next build',
+  start: 'next start',
+  'generate-db-client': 'npx prisma generate --schema prisma/schema.prisma',
+  'migrate-db': 'npx prisma migrate deploy',
+  'install-playwright': 'npx playwright install',
+  setup: 'npm run install-dependencies && npm run setup:db && npm run build:local && npm run protect-seeded-files',
+  'setup:db': 'npm run setup-env && npm run generate-db-client && npm run migrate-db && npm run sync-all',
+  'setup:full':
+    'npm run install-dependencies && npm run setup:db && npm run build:local && npm run protect-seeded-files',
+  'protect-seeded-files': 'npx tsx scripts/protect-seeded-files.ts',
+  'appraisejs:setup': 'npm run setup',
+  'appraisejs:sync': 'npm run sync-all',
+  'appraisejs:install-step': 'npx tsx scripts/install-template-step.ts',
+}
+delete rootPkg.scripts['build:appraisejs']
+delete rootPkg.scripts['build-step-registry']
+writeFileSync(join(target, 'package.json'), JSON.stringify(rootPkg, null, 2) + '\n')
+console.log('Wrote template package.json with production-first scaffold scripts.')
+
+  if (savedReadme) {
+    writeFileSync(readmePath, savedReadme)
+    console.log('Restored README.md')
+  }
+  if (savedAppraisejsConfig) {
+    writeFileSync(appraisejsConfigPath, savedAppraisejsConfig)
+    console.log('Restored appraisejs.config.json')
+  }
+
+  console.log('Synced base app to templates/starter with starter automation assets.')
+}
+
+main()

package/templates/blank/scripts/sync-template-step-groups.ts

@@ -0,0 +1,247 @@
+#!/usr/bin/env tsx
+
+/**
+ * Script to synchronize template step groups from filesystem to database
+ * Scans step definition files to ensure all step groups exist in DB
+ * Filesystem is the source of truth - groups in DB but not in FS will be deleted
+ * Run this after merging changes to ensure step group sync
+ *
+ * Usage: npx tsx scripts/sync-template-step-groups.ts
+ */
+
+import { promises as fs } from 'fs'
+import { join } from 'path'
+import { glob } from 'glob'
+import prisma from '../src/config/db-config'
+import { TemplateStepGroupType } from '@prisma/client'
+import { parseGroupJSDoc } from './lib/jsdoc-parser'
+import { printSyncSummary } from './lib/sync-summary'
+import { runSyncScript } from './lib/sync-script-runner'
+
+interface StepGroupData {
+  name: string
+  description: string | null
+  type: TemplateStepGroupType
+}
+
+interface SyncResult {
+  groupsScanned: number
+  groupsExisting: number
+  groupsCreated: number
+  groupsDeleted: number
+  groupsSkipped: number
+  errors: string[]
+  createdGroups: string[]
+  existingGroups: string[]
+  deletedGroups: string[]
+  skippedGroups: string[]
+}
+
+/**
+ * Scans step definition files in actions and validations directories
+ */
+async function scanStepFiles(baseDir: string): Promise<string[]> {
+  const stepFiles: string[] = []
+
+  try {
+    // Get all .step.ts files in actions and validations directories
+    const patterns = ['automation/steps/actions/**/*.step.ts', 'automation/steps/validations/**/*.step.ts']
+
+    for (const pattern of patterns) {
+      const files = await glob(pattern, {
+        cwd: baseDir,
+      })
+      stepFiles.push(...files)
+    }
+  } catch (error) {
+    console.error('Error scanning step files:', error)
+    throw error
+  }
+
+  return stepFiles
+}
+
+/**
+ * Reads and parses step files to extract step group metadata
+ */
+async function readStepGroupsFromFiles(baseDir: string): Promise<StepGroupData[]> {
+  const stepFiles = await scanStepFiles(baseDir)
+  const stepGroups: StepGroupData[] = []
+  const errors: string[] = []
+
+  for (const file of stepFiles) {
+    try {
+      const filePath = join(baseDir, file)
+      const content = await fs.readFile(filePath, 'utf-8')
+      const jsdoc = parseGroupJSDoc(content)
+
+      if (jsdoc) {
+        stepGroups.push(jsdoc)
+      } else {
+        errors.push(`File '${file}' does not have a valid group JSDoc comment`)
+      }
+    } catch (error) {
+      const errorMsg = `Error reading file '${file}': ${error}`
+      errors.push(errorMsg)
+      console.error(`   ⚠️  ${errorMsg}`)
+    }
+  }
+
+  if (errors.length > 0) {
+    console.log(`\n⚠️  Warning: ${errors.length} file(s) skipped due to missing or invalid JSDoc:`)
+    errors.forEach((error, index) => {
+      console.log(`      ${index + 1}. ${error}`)
+    })
+  }
+
+  return stepGroups
+}
+
+/**
+ * Syncs step groups to database
+ */
+async function syncStepGroupsToDatabase(stepGroups: StepGroupData[]): Promise<SyncResult> {
+  const result: SyncResult = {
+    groupsScanned: stepGroups.length,
+    groupsExisting: 0,
+    groupsCreated: 0,
+    groupsDeleted: 0,
+    groupsSkipped: 0,
+    errors: [],
+    createdGroups: [],
+    existingGroups: [],
+    deletedGroups: [],
+    skippedGroups: [],
+  }
+
+  // Get set of step group names from filesystem
+  const fsGroupNames = new Set(stepGroups.map(group => group.name))
+
+  // Get all step groups from database
+  const allDbGroups = await prisma.templateStepGroup.findMany({
+    select: { id: true, name: true },
+  })
+
+  // Delete step groups from DB that are not in filesystem
+  for (const dbGroup of allDbGroups) {
+    if (!fsGroupNames.has(dbGroup.name)) {
+      try {
+        // Check if step group has template steps (foreign key constraint prevents deletion)
+        const templateStepCount = await prisma.templateStep.count({
+          where: { templateStepGroupId: dbGroup.id },
+        })
+
+        if (templateStepCount > 0) {
+          result.groupsSkipped++
+          result.skippedGroups.push(dbGroup.name)
+          console.log(`   ⚠️  Skipped deletion of '${dbGroup.name}' (has ${templateStepCount} template step(s))`)
+        } else {
+          await prisma.templateStepGroup.delete({
+            where: { id: dbGroup.id },
+          })
+          result.groupsDeleted++
+          result.deletedGroups.push(dbGroup.name)
+          console.log(`   🗑️  Deleted step group '${dbGroup.name}' (not in filesystem)`)
+        }
+      } catch (error) {
+        const errorMsg = `Error deleting step group '${dbGroup.name}': ${error}`
+        result.errors.push(errorMsg)
+        console.error(`   ❌ ${errorMsg}`)
+      }
+    }
+  }
+
+  // Create or update step groups from filesystem
+  for (const group of stepGroups) {
+    try {
+      // Check if step group already exists by name
+      const existing = await prisma.templateStepGroup.findFirst({
+        where: { name: group.name },
+      })
+
+      if (existing) {
+        // Check if update is needed (description or type changed)
+        const needsUpdate = existing.description !== group.description || existing.type !== group.type
+
+        if (needsUpdate) {
+          await prisma.templateStepGroup.update({
+            where: { id: existing.id },
+            data: {
+              description: group.description,
+              type: group.type,
+            },
+          })
+          result.groupsExisting++
+          result.existingGroups.push(group.name)
+          console.log(`   🔄 Updated step group '${group.name}'`)
+        } else {
+          result.groupsExisting++
+          result.existingGroups.push(group.name)
+          console.log(`   ✓ Step group '${group.name}' already exists`)
+        }
+      } else {
+        // Create the step group
+        await prisma.templateStepGroup.create({
+          data: {
+            name: group.name,
+            description: group.description,
+            type: group.type,
+          },
+        })
+        result.groupsCreated++
+        result.createdGroups.push(group.name)
+        console.log(`   ➕ Created step group '${group.name}'`)
+      }
+    } catch (error) {
+      const errorMsg = `Error syncing step group '${group.name}': ${error}`
+      result.errors.push(errorMsg)
+      console.error(`   ❌ ${errorMsg}`)
+    }
+  }
+
+  return result
+}
+
+/**
+ * Generates and displays sync summary
+ */
+async function main(): Promise<SyncResult> {
+    console.log('🔄 Starting template step group sync...')
+    console.log('This will scan step definition files and sync step groups to database.\n')
+
+    const baseDir = process.cwd()
+
+    // Read step groups from files
+    console.log('📁 Scanning step definition files...')
+    const stepGroups = await readStepGroupsFromFiles(baseDir)
+    console.log(`   Found ${stepGroups.length} step group(s) with valid JSDoc`)
+
+    if (stepGroups.length === 0) {
+      console.log('\n⚠️  No step groups found. Continuing so the database can be reconciled with an empty filesystem state.')
+    }
+
+    // Sync to database
+    console.log('\n✅ Syncing step groups to database...')
+    const result = await syncStepGroupsToDatabase(stepGroups)
+
+    printSyncSummary(
+      [
+        { label: '📁 Step groups scanned', value: result.groupsScanned },
+        { label: '✅ Step groups existing', value: result.groupsExisting },
+        { label: '➕ Step groups created', value: result.groupsCreated },
+        { label: '🗑️  Step groups deleted', value: result.groupsDeleted },
+        { label: '⚠️  Step groups skipped', value: result.groupsSkipped },
+        { label: '❌ Errors', value: result.errors.length },
+      ],
+      [
+        { title: 'Created step groups', items: result.createdGroups },
+        { title: 'Existing step groups', items: result.existingGroups },
+        { title: 'Deleted step groups', items: result.deletedGroups },
+        { title: 'Skipped step groups (have template steps)', items: result.skippedGroups },
+        { title: 'Errors', items: result.errors },
+      ],
+    )
+    return result
+}
+
+runSyncScript(main)

package/templates/blank/src/app/globals.css

@@ -0,0 +1,90 @@
+@tailwind base;
+@tailwind components;
+@tailwind utilities;
+
+body {
+  font-family: Arial, Helvetica, sans-serif;
+}
+
+@layer base {
+  :root {
+    --background: oklch(0.2077 0.0398 265.7549);
+    --foreground: oklch(0.8717 0.0093 258.3382);
+    --card: oklch(0.2795 0.0368 260.031);
+    --card-foreground: oklch(0.8717 0.0093 258.3382);
+    --popover: oklch(0.2795 0.0368 260.031);
+    --popover-foreground: oklch(0.8717 0.0093 258.3382);
+    --primary: oklch(0.7729 0.1535 163.2231);
+    --primary-foreground: oklch(0.2077 0.0398 265.7549);
+    --secondary: oklch(0.3351 0.0331 260.912);
+    --secondary-foreground: oklch(0.7118 0.0129 286.0665);
+    --muted: oklch(0.2463 0.0275 259.9628);
+    --muted-foreground: oklch(0.551 0.0234 264.3637);
+    --accent: oklch(0.3729 0.0306 259.7328);
+    --accent-foreground: oklch(0.7118 0.0129 286.0665);
+    --destructive: oklch(0.6368 0.2078 25.3313);
+    --destructive-foreground: oklch(0.2077 0.0398 265.7549);
+    --border: oklch(0.4461 0.0263 256.8018);
+    --input: oklch(0.4461 0.0263 256.8018);
+    --ring: oklch(0.7729 0.1535 163.2231);
+    --chart-1: oklch(0.7729 0.1535 163.2231);
+    --chart-2: oklch(0.7845 0.1325 181.912);
+    --chart-3: oklch(0.7227 0.192 149.5793);
+    --chart-4: oklch(0.6959 0.1491 162.4796);
+    --chart-5: oklch(0.596 0.1274 163.2254);
+    --sidebar: oklch(0.2795 0.0368 260.031);
+    --sidebar-foreground: oklch(0.8717 0.0093 258.3382);
+    --sidebar-primary: oklch(0.7729 0.1535 163.2231);
+    --sidebar-primary-foreground: oklch(0.2077 0.0398 265.7549);
+    --sidebar-accent: oklch(0.3729 0.0306 259.7328);
+    --sidebar-accent-foreground: oklch(0.7118 0.0129 286.0665);
+    --sidebar-border: oklch(0.4461 0.0263 256.8018);
+    --sidebar-ring: oklch(0.7729 0.1535 163.2231);
+    --font-sans: DM Sans, sans-serif;
+    --font-serif: Lora, serif;
+    --font-mono: IBM Plex Mono, monospace;
+    --radius: 0.5rem;
+    --shadow-x: 0px;
+    --shadow-y: 4px;
+    --shadow-blur: 8px;
+    --shadow-spread: -1px;
+    --shadow-opacity: 0.1;
+    --shadow-color: hsl(0 0% 0%);
+    --shadow-2xs: 0px 4px 8px -1px hsl(0 0% 0% / 0.05);
+    --shadow-xs: 0px 4px 8px -1px hsl(0 0% 0% / 0.05);
+    --shadow-sm: 0px 4px 8px -1px hsl(0 0% 0% / 0.1), 0px 1px 2px -2px hsl(0 0% 0% / 0.1);
+    --shadow: 0px 4px 8px -1px hsl(0 0% 0% / 0.1), 0px 1px 2px -2px hsl(0 0% 0% / 0.1);
+    --shadow-md: 0px 4px 8px -1px hsl(0 0% 0% / 0.1), 0px 2px 4px -2px hsl(0 0% 0% / 0.1);
+    --shadow-lg: 0px 4px 8px -1px hsl(0 0% 0% / 0.1), 0px 4px 6px -2px hsl(0 0% 0% / 0.1);
+    --shadow-xl: 0px 4px 8px -1px hsl(0 0% 0% / 0.1), 0px 8px 10px -2px hsl(0 0% 0% / 0.1);
+    --shadow-2xl: 0px 4px 8px -1px hsl(0 0% 0% / 0.25);
+    --shadow-offset-x: 0px;
+    --shadow-offset-y: 4px;
+    --letter-spacing: 0em;
+    --spacing: 0.25rem;
+  }
+
+  .theme {
+    --font-sans: DM Sans, sans-serif;
+    --font-mono: IBM Plex Mono, monospace;
+    --font-serif: Lora, serif;
+    --radius: 0.5rem;
+    --tracking-tighter: calc(var(--tracking-normal) - 0.05em);
+    --tracking-tight: calc(var(--tracking-normal) - 0.025em);
+    --tracking-wide: calc(var(--tracking-normal) + 0.025em);
+    --tracking-wider: calc(var(--tracking-normal) + 0.05em);
+    --tracking-widest: calc(var(--tracking-normal) + 0.1em);
+  }
+  body {
+    letter-spacing: var(--tracking-normal);
+  }
+}
+
+@layer base {
+  * {
+    @apply border-border;
+  }
+  body {
+    @apply bg-background text-foreground;
+  }
+}