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

package/templates/starter/scripts/lib/template-step-registry.test.ts

@@ -0,0 +1,118 @@
+import os from 'os'
+import path from 'path'
+import { promises as fs } from 'fs'
+import { afterEach, describe, expect, it } from 'vitest'
+import { buildStepRegistry, createContentSha256, slugifyRegistryName } from './template-step-registry'
+
+const tempDirs: string[] = []
+
+async function createTempWorkspace(): Promise<string> {
+  const dir = await fs.mkdtemp(path.join(os.tmpdir(), 'appraise-step-registry-'))
+  tempDirs.push(dir)
+  return dir
+}
+
+async function writeFile(root: string, relativePath: string, content: string): Promise<void> {
+  const absolutePath = path.join(root, relativePath)
+  await fs.mkdir(path.dirname(absolutePath), { recursive: true })
+  await fs.writeFile(absolutePath, content)
+}
+
+afterEach(async () => {
+  await Promise.all(tempDirs.splice(0).map(dir => fs.rm(dir, { recursive: true, force: true })))
+})
+
+describe('slugifyRegistryName', () => {
+  it('creates hyphenated slugs for CLI lookup', () => {
+    expect(slugifyRegistryName('Text Assertion')).toBe('text-assertion')
+    expect(slugifyRegistryName('Assert element contains text')).toBe('assert-element-contains-text')
+  })
+})
+
+describe('buildStepRegistry', () => {
+  it('builds manifest entries and source fragments from canonical step files', async () => {
+    const workspace = await createTempWorkspace()
+
+    await writeFile(
+      workspace,
+      'automation/steps/actions/click.step.ts',
+      `/**
+ * @name click
+ * @description Click helpers
+ * @type ACTION
+ */
+import { When, CustomWorld, SelectorName, resolveLocator } from '../../../packages/cucumber-runtime/src/index.js'
+
+/**
+ * @name click element
+ * @description clicks the target element
+ * @icon MOUSE
+ */
+When('click {string}', async function (this: CustomWorld, elementName: SelectorName) {
+  const selector = await resolveLocator(this.page, elementName)
+  await this.page.locator(selector!).click()
+})
+`,
+    )
+
+    const registry = await buildStepRegistry(workspace)
+    expect(registry.manifest.version).toBe(1)
+    expect(registry.manifest.steps).toHaveLength(1)
+
+    const entry = registry.manifest.steps[0]
+    expect(entry.slug).toBe('click/click-element')
+    expect(entry.sourcePath).toBe('fragments/click/click-element.ts')
+    expect(entry.signature).toBe('click {string}')
+    expect(entry.group).toEqual({
+      slug: 'click',
+      name: 'click',
+      description: 'Click helpers',
+      type: 'ACTION',
+    })
+
+    expect(registry.fragments).toEqual([
+      {
+        path: 'fragments/click/click-element.ts',
+        content: expect.stringContaining("@name click element"),
+      },
+    ])
+    expect(registry.fragments[0]?.content).toContain("When('click {string}'")
+    expect(entry.sourceSha256).toBe(createContentSha256(registry.fragments[0]!.content))
+  })
+
+  it('fails when duplicate signatures would produce an ambiguous registry', async () => {
+    const workspace = await createTempWorkspace()
+
+    await writeFile(
+      workspace,
+      'automation/steps/actions/click.step.ts',
+      `/**
+ * @name click
+ * @type ACTION
+ */
+/**
+ * @name click element
+ * @icon MOUSE
+ */
+When('click {string}', async function () {})
+`,
+    )
+
+    await writeFile(
+      workspace,
+      'automation/steps/actions/hover.step.ts',
+      `/**
+ * @name hover
+ * @type ACTION
+ */
+/**
+ * @name hover element
+ * @icon MOUSE
+ */
+When('click {string}', async function () {})
+`,
+    )
+
+    await expect(buildStepRegistry(workspace)).rejects.toThrow('Duplicate step signature')
+  })
+})

package/templates/starter/scripts/lib/template-step-registry.ts

@@ -0,0 +1,137 @@
+import crypto from 'crypto'
+import { promises as fs } from 'fs'
+import path from 'path'
+import { glob } from 'glob'
+import { TemplateStepGroupType, TemplateStepIcon } from '@prisma/client'
+import { parseStepFile } from './step-file-parser'
+
+export type RegistryStepEntry = {
+  slug: string
+  sourcePath: string
+  sourceSha256: string
+  signature: string
+  name: string
+  description: string | null
+  icon: TemplateStepIcon
+  group: {
+    slug: string
+    name: string
+    description: string | null
+    type: TemplateStepGroupType
+  }
+}
+
+export type StepRegistryManifest = {
+  version: 1
+  generatedAt: string
+  steps: RegistryStepEntry[]
+}
+
+export type StepRegistryFragment = {
+  path: string
+  content: string
+}
+
+export type BuiltStepRegistry = {
+  manifest: StepRegistryManifest
+  fragments: StepRegistryFragment[]
+}
+
+const STEP_FILE_PATTERNS = ['automation/steps/actions/**/*.step.ts', 'automation/steps/validations/**/*.step.ts'] as const
+
+export function slugifyRegistryName(value: string): string {
+  return value
+    .toLowerCase()
+    .trim()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+}
+
+export function renderStepSourceFragment(source: string): string {
+  return `${source.trim()}\n`
+}
+
+export function createContentSha256(content: string): string {
+  return crypto.createHash('sha256').update(content).digest('hex')
+}
+
+export async function buildStepRegistry(baseDir: string): Promise<BuiltStepRegistry> {
+  const fragments: StepRegistryFragment[] = []
+  const steps: RegistryStepEntry[] = []
+  const seenSlugs = new Set<string>()
+  const seenSourcePaths = new Set<string>()
+  const seenSignatures = new Set<string>()
+
+  for (const pattern of STEP_FILE_PATTERNS) {
+    const files = await glob(pattern, { cwd: baseDir })
+
+    for (const file of files.sort()) {
+      const absolutePath = path.join(baseDir, file)
+      const content = await fs.readFile(absolutePath, 'utf8')
+      const parsed = parseStepFile(content, file)
+      if (!parsed) {
+        throw new Error(`Step file is missing a valid group JSDoc: ${file}`)
+      }
+
+      const groupSlug = slugifyRegistryName(parsed.group.name)
+      if (!groupSlug) {
+        throw new Error(`Unable to derive registry slug for step group "${parsed.group.name}" (${file})`)
+      }
+
+      for (const step of parsed.steps) {
+        const stepSlug = slugifyRegistryName(step.jsdoc.name)
+        if (!stepSlug) {
+          throw new Error(`Unable to derive registry slug for step "${step.jsdoc.name}" (${file})`)
+        }
+
+        const slug = `${groupSlug}/${stepSlug}`
+        const sourcePath = path.posix.join('fragments', groupSlug, `${stepSlug}.ts`)
+        const fragmentContent = renderStepSourceFragment(step.source)
+        const sourceSha256 = createContentSha256(fragmentContent)
+
+        if (seenSlugs.has(slug)) {
+          throw new Error(`Duplicate registry slug "${slug}" generated from ${file}`)
+        }
+        if (seenSourcePaths.has(sourcePath)) {
+          throw new Error(`Duplicate registry source path "${sourcePath}" generated from ${file}`)
+        }
+        if (seenSignatures.has(step.signature)) {
+          throw new Error(`Duplicate step signature "${step.signature}" encountered while building the registry`)
+        }
+
+        seenSlugs.add(slug)
+        seenSourcePaths.add(sourcePath)
+        seenSignatures.add(step.signature)
+
+        fragments.push({
+          path: sourcePath,
+          content: fragmentContent,
+        })
+        steps.push({
+          slug,
+          sourcePath,
+          sourceSha256,
+          signature: step.signature,
+          name: step.jsdoc.name,
+          description: step.jsdoc.description,
+          icon: step.jsdoc.icon,
+          group: {
+            slug: groupSlug,
+            name: parsed.group.name,
+            description: parsed.group.description,
+            type: parsed.group.type,
+          },
+        })
+      }
+    }
+  }
+
+  return {
+    manifest: {
+      version: 1,
+      generatedAt: new Date().toISOString(),
+      steps: steps.sort((left, right) => left.slug.localeCompare(right.slug)),
+    },
+    fragments: fragments.sort((left, right) => left.path.localeCompare(right.path)),
+  }
+}

package/templates/starter/scripts/protect-seeded-files.ts

@@ -0,0 +1,51 @@
+#!/usr/bin/env tsx
+
+import fs from 'fs'
+import path from 'path'
+
+const SEEDED_TEMPLATE_PATHS = ['prisma/dev.db', 'automation/config/environments/environments.json']
+
+/**
+ * Trims trailing blank lines while preserving internal spacing.
+ */
+function trimTrailingBlankLines(lines: string[]): string[] {
+  const trimmed = [...lines]
+  while (trimmed.length > 0 && trimmed[trimmed.length - 1] === '') {
+    trimmed.pop()
+  }
+  return trimmed
+}
+
+/**
+ * Rewrites `.gitignore` content to enforce seeded-template tracking rules.
+ */
+function setSeededTemplateFilesTracked(content: string, tracked: boolean): string {
+  const managedLines = new Set(SEEDED_TEMPLATE_PATHS.flatMap(filePath => [filePath, `!${filePath}`]))
+  const lines = trimTrailingBlankLines(content.split(/\r?\n/)).filter(line => !managedLines.has(line.trim()))
+
+  for (const filePath of SEEDED_TEMPLATE_PATHS) {
+    lines.push(tracked ? `!${filePath}` : filePath)
+  }
+
+  return `${lines.join('\n')}\n`
+}
+
+/**
+ * Updates `.gitignore` so seeded local files stay ignored.
+ */
+function main(): void {
+  const gitignorePath = path.join(process.cwd(), '.gitignore')
+  const packagedGitignorePath = path.join(process.cwd(), 'gitignore')
+  const sourceGitignorePath = fs.existsSync(gitignorePath) ? gitignorePath : packagedGitignorePath
+  const currentGitignore = fs.existsSync(sourceGitignorePath) ? fs.readFileSync(sourceGitignorePath, 'utf8') : ''
+
+  fs.writeFileSync(gitignorePath, setSeededTemplateFilesTracked(currentGitignore, false))
+
+  if (sourceGitignorePath === packagedGitignorePath && fs.existsSync(packagedGitignorePath)) {
+    fs.rmSync(packagedGitignorePath, { force: true })
+  }
+
+  console.log('Updated .gitignore to ignore seeded local files.')
+}
+
+main()

package/templates/starter/scripts/regenerate-features.ts

@@ -0,0 +1,98 @@
+#!/usr/bin/env tsx
+
+/**
+ * Script to synchronize feature files between database and filesystem
+ * This performs bidirectional sync - both DB->FS and FS->DB
+ * Run this after merging changes or database migrations to ensure sync
+ *
+ * Usage: npx tsx scripts/regenerate-features.ts [--dry-run]
+ */
+
+import { performBidirectionalSync, performDryRunSync } from '../src/lib/bidirectional-sync'
+import { ensureAutomationWorkspaceReady, getAutomationFeaturesDir } from '../src/lib/automation/paths'
+
+/**
+ * Runs bidirectional feature sync in dry-run or apply mode.
+ */
+async function main(): Promise<void> {
+  try {
+    const isDryRun = process.argv.includes('--dry-run')
+    await ensureAutomationWorkspaceReady()
+    const featuresBaseDir = getAutomationFeaturesDir()
+
+    if (isDryRun) {
+      console.log('🔍 Performing dry run of bidirectional sync...')
+      console.log('This will show what would be changed without making any modifications.\n')
+
+      const dryRunResult = await performDryRunSync(featuresBaseDir)
+
+      console.log('\n📊 Dry run results:')
+      console.log(`📁 Would generate ${dryRunResult.wouldGenerate.length} feature files:`)
+      dryRunResult.wouldGenerate.forEach((filePath, index) => {
+        const relativePath = filePath.replace(process.cwd(), '.')
+        console.log(`   ${index + 1}. ${relativePath}`)
+      })
+
+      console.log(`\n🔄 Would update ${dryRunResult.wouldUpdate.length} feature files:`)
+      dryRunResult.wouldUpdate.forEach((filePath, index) => {
+        const relativePath = filePath.replace(process.cwd(), '.')
+        console.log(`   ${index + 1}. ${relativePath}`)
+      })
+
+      console.log(`\n➕ Would create ${dryRunResult.wouldCreate.testSuites.length} test suites:`)
+      dryRunResult.wouldCreate.testSuites.forEach((item, index) => {
+        console.log(`   ${index + 1}. ${item}`)
+      })
+
+      console.log(`\n📝 Would create ${dryRunResult.wouldCreate.testCases.length} test cases:`)
+      dryRunResult.wouldCreate.testCases.forEach((item, index) => {
+        console.log(`   ${index + 1}. ${item}`)
+      })
+
+      console.log(`\n🔧 Would create ${dryRunResult.wouldCreate.templateSteps.length} template steps:`)
+      dryRunResult.wouldCreate.templateSteps.forEach((item, index) => {
+        console.log(`   ${index + 1}. ${item}`)
+      })
+
+      console.log(`\n🏷️  Would create ${dryRunResult.wouldCreate.tags.length} tags:`)
+      dryRunResult.wouldCreate.tags.forEach((tag, index) => {
+        console.log(`   ${index + 1}. ${tag}`)
+      })
+
+      console.log('\n💡 To perform the actual sync, run without --dry-run flag')
+    } else {
+      console.log('🔄 Starting bidirectional sync between database and feature files...')
+      console.log('This will sync both directions:')
+      console.log('   📁 Feature files → Database (create missing test suites/cases)')
+      console.log('   🗄️ Database → Feature files (generate/update feature files)')
+      console.log('')
+
+      const syncResult = await performBidirectionalSync(featuresBaseDir)
+
+      console.log('\n✅ Bidirectional sync completed successfully!')
+      console.log(`📊 Summary:`)
+      console.log(`   📁 Generated feature files: ${syncResult.generatedFeatureFiles}`)
+      console.log(`   🔄 Updated feature files: ${syncResult.updatedFeatureFiles}`)
+      console.log(`   🗄️ Merged test suites: ${syncResult.mergedTestSuites}`)
+      console.log(`   📝 Added scenarios: ${syncResult.addedScenarios}`)
+      console.log(`   📊 Total processed: ${syncResult.totalProcessed}`)
+
+      if (syncResult.errors.length > 0) {
+        console.log(`\n⚠️  Errors encountered: ${syncResult.errors.length}`)
+        syncResult.errors.forEach((error, index) => {
+          console.log(`   ${index + 1}. ${error}`)
+        })
+      }
+
+      console.log('\n💡 Tips:')
+      console.log('   - Run with --dry-run to see what would be changed')
+      console.log('   - This script is safe to run multiple times')
+      console.log('   - Changes are automatically merged, not overwritten')
+    }
+  } catch (error) {
+    console.error('\n❌ Error during sync:', error)
+    process.exit(1)
+  }
+}
+
+main()

package/templates/starter/scripts/run-vitest.ts

@@ -0,0 +1,59 @@
+#!/usr/bin/env tsx
+
+import fs from 'node:fs'
+import os from 'node:os'
+import process from 'node:process'
+import { spawnSync } from 'node:child_process'
+import { fileURLToPath } from 'node:url'
+
+function isUsableDirectory(directory: string | undefined): directory is string {
+  if (!directory) {
+    return false
+  }
+
+  try {
+    fs.mkdirSync(directory, { recursive: true })
+    fs.accessSync(directory, fs.constants.R_OK | fs.constants.W_OK)
+    return true
+  } catch {
+    return false
+  }
+}
+
+function getTempDirectory(): string | undefined {
+  const envCandidates = [process.env.TMPDIR, process.env.TMP, process.env.TEMP]
+  const fallbackCandidates =
+    process.platform === 'win32' ? [os.tmpdir()] : ['/tmp', os.tmpdir(), '/var/tmp', '/usr/tmp']
+
+  return [...envCandidates, ...fallbackCandidates].find(isUsableDirectory)
+}
+
+function main(): void {
+  const tempDirectory = getTempDirectory()
+  if (!tempDirectory) {
+    console.error('Unable to find a writable temporary directory for Vitest.')
+    process.exit(1)
+  }
+
+  const vitestEntry = fileURLToPath(new URL('../node_modules/vitest/vitest.mjs', import.meta.url))
+  const env = {
+    ...process.env,
+    TMPDIR: tempDirectory,
+    TMP: tempDirectory,
+    TEMP: tempDirectory,
+  }
+
+  const result = spawnSync(process.execPath, [vitestEntry, 'run', ...process.argv.slice(2)], {
+    stdio: 'inherit',
+    env,
+  })
+
+  if (result.error) {
+    console.error(result.error)
+    process.exit(1)
+  }
+
+  process.exit(result.status ?? 1)
+}
+
+main()

package/templates/starter/scripts/setup-env.ts

@@ -0,0 +1,26 @@
+#!/usr/bin/env tsx
+
+import fs from 'fs'
+import path from 'path'
+
+const envContent = `# Database configuration for local development
+DATABASE_URL="file:./dev.db"
+`
+
+/**
+ * Ensures local `.env` exists with a default SQLite DATABASE_URL.
+ */
+function main(): void {
+  const envPath = path.join(process.cwd(), '.env')
+
+  if (!fs.existsSync(envPath)) {
+    fs.writeFileSync(envPath, envContent)
+    console.log('Created .env file with SQLite configuration')
+  } else {
+    console.log('.env file already exists, skipping creation')
+  }
+
+  console.log('Environment setup complete!')
+}
+
+main()