create-appraisejs 0.2.0 → 0.3.0-alpha.1

package/templates/starter/src/lib/sync/sync-registry.ts

@@ -0,0 +1,149 @@
+type BaseSyncScriptDefinition = {
+  id: string
+  label: string
+  description: string
+  orderLabel: string
+  scriptFile: string
+  dependencies: string[]
+}
+
+export const SYNC_ALL_REQUEST_ID = 'sync-all' as const
+
+export const syncScriptDefinitions = [
+  {
+    id: 'sync-modules',
+    label: 'Sync Modules',
+    description: 'Syncs modules to DB.',
+    orderLabel: 'Modules',
+    scriptFile: 'sync-modules.ts',
+    dependencies: [],
+  },
+  {
+    id: 'sync-environments',
+    label: 'Sync Environments',
+    description: 'Syncs environments to DB.',
+    orderLabel: 'Environments',
+    scriptFile: 'sync-environments.ts',
+    dependencies: [],
+  },
+  {
+    id: 'sync-tags',
+    label: 'Sync Tags',
+    description: 'Syncs tags to DB.',
+    orderLabel: 'Tags',
+    scriptFile: 'sync-tags.ts',
+    dependencies: [],
+  },
+  {
+    id: 'sync-template-step-groups',
+    label: 'Sync Template Step Groups',
+    description: 'Syncs template step groups to DB.',
+    orderLabel: 'Template Step Groups',
+    scriptFile: 'sync-template-step-groups.ts',
+    dependencies: [],
+  },
+  {
+    id: 'sync-template-steps',
+    label: 'Sync Template Steps',
+    description: 'Syncs template steps to DB.',
+    orderLabel: 'Template Steps',
+    scriptFile: 'sync-template-steps.ts',
+    dependencies: ['sync-template-step-groups'],
+  },
+  {
+    id: 'sync-locator-groups',
+    label: 'Sync Locator Groups',
+    description: 'Syncs locator groups to DB.',
+    orderLabel: 'Locator Groups',
+    scriptFile: 'sync-locator-groups.ts',
+    dependencies: ['sync-modules'],
+  },
+  {
+    id: 'sync-locators',
+    label: 'Sync Locators',
+    description: 'Syncs locators to DB.',
+    orderLabel: 'Locators',
+    scriptFile: 'sync-locators.ts',
+    dependencies: ['sync-locator-groups'],
+  },
+  {
+    id: 'sync-test-suites',
+    label: 'Sync Test Suites',
+    description: 'Syncs test suites to DB.',
+    orderLabel: 'Test Suites',
+    scriptFile: 'sync-test-suites.ts',
+    dependencies: ['sync-modules', 'sync-tags'],
+  },
+  {
+    id: 'sync-test-cases',
+    label: 'Sync Test Cases',
+    description: 'Syncs test cases to DB.',
+    orderLabel: 'Test Cases',
+    scriptFile: 'sync-test-cases.ts',
+    dependencies: ['sync-test-suites', 'sync-template-steps', 'sync-tags'],
+  },
+] as const satisfies readonly BaseSyncScriptDefinition[]
+
+export type SyncScriptId = (typeof syncScriptDefinitions)[number]['id']
+export type SyncRequestId = SyncScriptId | typeof SYNC_ALL_REQUEST_ID
+export type SyncScriptDefinition = (typeof syncScriptDefinitions)[number]
+
+const syncScriptDefinitionMap = new Map<SyncScriptId, (typeof syncScriptDefinitions)[number]>(
+  syncScriptDefinitions.map(definition => [definition.id, definition]),
+)
+
+export function isSyncScriptId(value: string): value is SyncScriptId {
+  return syncScriptDefinitionMap.has(value as SyncScriptId)
+}
+
+export function isSyncRequestId(value: string): value is SyncRequestId {
+  return value === SYNC_ALL_REQUEST_ID || isSyncScriptId(value)
+}
+
+export function getSyncScriptDefinition(scriptId: SyncScriptId) {
+  const definition = syncScriptDefinitionMap.get(scriptId)
+
+  if (!definition) {
+    throw new Error(`Unknown sync script: ${scriptId}`)
+  }
+
+  return definition
+}
+
+export function resolveSyncExecutionOrder(requestedScriptId: SyncScriptId): SyncScriptId[] {
+  const visiting = new Set<SyncScriptId>()
+  const visited = new Set<SyncScriptId>()
+  const executionOrder: SyncScriptId[] = []
+
+  const visit = (scriptId: SyncScriptId) => {
+    if (visited.has(scriptId)) {
+      return
+    }
+
+    if (visiting.has(scriptId)) {
+      throw new Error(`Circular sync dependency detected for ${scriptId}`)
+    }
+
+    visiting.add(scriptId)
+
+    for (const dependencyId of getSyncScriptDefinition(scriptId).dependencies) {
+      visit(dependencyId as SyncScriptId)
+    }
+
+    visiting.delete(scriptId)
+    visited.add(scriptId)
+    executionOrder.push(scriptId)
+  }
+
+  visit(requestedScriptId)
+
+  return executionOrder
+}
+
+export function resolveRequestedSyncExecutionOrder(requestedScriptId: SyncRequestId): SyncScriptId[] {
+  if (requestedScriptId === SYNC_ALL_REQUEST_ID) {
+    return syncScriptDefinitions.map(definition => definition.id)
+  }
+
+  return resolveSyncExecutionOrder(requestedScriptId)
+}

package/templates/starter/src/lib/tag-utils.ts

@@ -0,0 +1,28 @@
+import { Tag, TagType } from '@prisma/client'
+
+type TagShape = Pick<Tag, 'name' | 'tagExpression' | 'type'>
+
+export function isIdentifierTagName(name: string): boolean {
+  return name.startsWith('tc_') || name.startsWith('ts_')
+}
+
+export function isIdentifierTagExpression(tagExpression: string): boolean {
+  const normalized = tagExpression.startsWith('@') ? tagExpression.slice(1) : tagExpression
+  return isIdentifierTagName(normalized)
+}
+
+export function getTagTypeFromName(name: string): TagType {
+  return isIdentifierTagName(name) ? TagType.IDENTIFIER : TagType.FILTER
+}
+
+export function getTagTypeFromExpression(tagExpression: string): TagType {
+  return isIdentifierTagExpression(tagExpression) ? TagType.IDENTIFIER : TagType.FILTER
+}
+
+export function getIdentifierTagByPrefix<T extends TagShape>(tags: T[], prefix: 'tc_' | 'ts_'): T | undefined {
+  return tags.find(tag => tag.type === TagType.IDENTIFIER && tag.name.startsWith(prefix))
+}
+
+export function getFilterTags<T extends TagShape>(tags: T[]): T[] {
+  return tags.filter(tag => tag.type === TagType.FILTER)
+}

package/templates/starter/src/lib/template-sync-utils.d.ts

@@ -0,0 +1,7 @@
+export declare function shouldExcludeTemplatePath(relativePath: string): boolean;
+export declare function shouldBackfillLegacyEnvironmentConfig(targetHasEnvironmentsFile: boolean, legacyEnvironmentsDirExists: boolean): boolean;
+export declare function getAutomationFeaturesDir(baseDir: string): string;
+export declare function getAutomationLocatorsDir(baseDir: string): string;
+export declare function getAutomationLocatorMapPath(baseDir: string): string;
+export declare function extractModulePathFromAutomationFile(filePath: string, baseDir: string, automationSubdir: 'features' | 'locators'): string;
+//# sourceMappingURL=template-sync-utils.d.ts.map

package/templates/starter/src/lib/template-sync-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"template-sync-utils.d.ts","sourceRoot":"","sources":["template-sync-utils.ts"],"names":[],"mappings":"AAUA,wBAAgB,yBAAyB,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAgBvE;AAED,wBAAgB,qCAAqC,CACnD,yBAAyB,EAAE,OAAO,EAClC,2BAA2B,EAAE,OAAO,GACnC,OAAO,CAET;AAED,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAEhE;AAED,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAEhE;AAED,wBAAgB,2BAA2B,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAEnE;AAED,wBAAgB,mCAAmC,CACjD,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,EACf,gBAAgB,EAAE,UAAU,GAAG,UAAU,GACxC,MAAM,CAWR"}

package/templates/starter/src/lib/template-sync-utils.js

@@ -0,0 +1,50 @@
+import { join, relative } from 'path';
+const EXCLUDED_DIRS = new Set(['node_modules', '.next', '.git', 'dist']);
+const EXCLUDED_EXTENSIONS = new Set(['.db', '.sqlite', '.sqlite3', '.tsbuildinfo']);
+const EXCLUDED_PATH_PREFIXES = ['automation/reports/'];
+const EXCLUDED_FILENAMES = new Set(['.DS_Store']);
+function toPosixPath(value) {
+    return value.replace(/\\/g, '/');
+}
+export function shouldExcludeTemplatePath(relativePath) {
+    const normalizedPath = toPosixPath(relativePath);
+    const parts = normalizedPath.split('/');
+    if (parts.some(part => EXCLUDED_DIRS.has(part)))
+        return true;
+    if (parts.some(part => EXCLUDED_FILENAMES.has(part)))
+        return true;
+    if (EXCLUDED_PATH_PREFIXES.some(prefix => normalizedPath.startsWith(prefix)))
+        return true;
+    const ext = normalizedPath.endsWith('.sqlite3')
+        ? '.sqlite3'
+        : normalizedPath.endsWith('.sqlite')
+            ? '.sqlite'
+            : normalizedPath.endsWith('.tsbuildinfo')
+                ? '.tsbuildinfo'
+                : normalizedPath.slice(normalizedPath.lastIndexOf('.'));
+    return EXCLUDED_EXTENSIONS.has(ext);
+}
+export function shouldBackfillLegacyEnvironmentConfig(targetHasEnvironmentsFile, legacyEnvironmentsDirExists) {
+    return !targetHasEnvironmentsFile && legacyEnvironmentsDirExists;
+}
+export function getAutomationFeaturesDir(baseDir) {
+    return join(baseDir, 'automation', 'features');
+}
+export function getAutomationLocatorsDir(baseDir) {
+    return join(baseDir, 'automation', 'locators');
+}
+export function getAutomationLocatorMapPath(baseDir) {
+    return join(baseDir, 'automation', 'mapping', 'locator-map.json');
+}
+export function extractModulePathFromAutomationFile(filePath, baseDir, automationSubdir) {
+    const automationBaseDir = automationSubdir === 'features' ? getAutomationFeaturesDir(baseDir) : getAutomationLocatorsDir(baseDir);
+    const normalizedBaseDir = toPosixPath(automationBaseDir).replace(/\/$/, '');
+    const normalizedFilePath = toPosixPath(filePath);
+    const relativePath = normalizedFilePath.startsWith(`${normalizedBaseDir}/`)
+        ? normalizedFilePath.slice(normalizedBaseDir.length + 1)
+        : toPosixPath(relative(automationBaseDir, filePath));
+    const pathParts = relativePath.split('/').filter(part => part && part !== '');
+    const moduleParts = pathParts.slice(0, -1);
+    return moduleParts.length > 0 ? `/${moduleParts.join('/')}` : '/';
+}
+//# sourceMappingURL=template-sync-utils.js.map

package/templates/starter/src/lib/template-sync-utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"template-sync-utils.js","sourceRoot":"","sources":["template-sync-utils.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,MAAM,CAAA;AAErC,MAAM,aAAa,GAAG,IAAI,GAAG,CAAC,CAAC,cAAc,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC,CAAA;AACxE,MAAM,mBAAmB,GAAG,IAAI,GAAG,CAAC,CAAC,KAAK,EAAE,SAAS,EAAE,UAAU,EAAE,cAAc,CAAC,CAAC,CAAA;AACnF,MAAM,sBAAsB,GAAG,CAAC,qBAAqB,CAAC,CAAA;AAEtD,SAAS,WAAW,CAAC,KAAa;IAChC,OAAO,KAAK,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,CAAA;AAClC,CAAC;AAED,MAAM,UAAU,yBAAyB,CAAC,YAAoB;IAC5D,MAAM,cAAc,GAAG,WAAW,CAAC,YAAY,CAAC,CAAA;IAChD,MAAM,KAAK,GAAG,cAAc,CAAC,KAAK,CAAC,GAAG,CAAC,CAAA;IAEvC,IAAI,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,aAAa,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QAAE,OAAO,IAAI,CAAA;IAC5D,IAAI,sBAAsB,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC,cAAc,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC;QAAE,OAAO,IAAI,CAAA;IAEzF,MAAM,GAAG,GAAG,cAAc,CAAC,QAAQ,CAAC,UAAU,CAAC;QAC7C,CAAC,CAAC,UAAU;QACZ,CAAC,CAAC,cAAc,CAAC,QAAQ,CAAC,SAAS,CAAC;YAClC,CAAC,CAAC,SAAS;YACX,CAAC,CAAC,cAAc,CAAC,QAAQ,CAAC,cAAc,CAAC;gBACvC,CAAC,CAAC,cAAc;gBAChB,CAAC,CAAC,cAAc,CAAC,KAAK,CAAC,cAAc,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC,CAAA;IAE7D,OAAO,mBAAmB,CAAC,GAAG,CAAC,GAAG,CAAC,CAAA;AACrC,CAAC;AAED,MAAM,UAAU,qCAAqC,CACnD,yBAAkC,EAClC,2BAAoC;IAEpC,OAAO,CAAC,yBAAyB,IAAI,2BAA2B,CAAA;AAClE,CAAC;AAED,MAAM,UAAU,wBAAwB,CAAC,OAAe;IACtD,OAAO,IAAI,CAAC,OAAO,EAAE,YAAY,EAAE,UAAU,CAAC,CAAA;AAChD,CAAC;AAED,MAAM,UAAU,wBAAwB,CAAC,OAAe;IACtD,OAAO,IAAI,CAAC,OAAO,EAAE,YAAY,EAAE,UAAU,CAAC,CAAA;AAChD,CAAC;AAED,MAAM,UAAU,2BAA2B,CAAC,OAAe;IACzD,OAAO,IAAI,CAAC,OAAO,EAAE,YAAY,EAAE,SAAS,EAAE,kBAAkB,CAAC,CAAA;AACnE,CAAC;AAED,MAAM,UAAU,mCAAmC,CACjD,QAAgB,EAChB,OAAe,EACf,gBAAyC;IAEzC,MAAM,iBAAiB,GACrB,gBAAgB,KAAK,UAAU,CAAC,CAAC,CAAC,wBAAwB,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,wBAAwB,CAAC,OAAO,CAAC,CAAA;IACzG,MAAM,iBAAiB,GAAG,WAAW,CAAC,iBAAiB,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAA;IAC3E,MAAM,kBAAkB,GAAG,WAAW,CAAC,QAAQ,CAAC,CAAA;IAChD,MAAM,YAAY,GAAG,kBAAkB,CAAC,UAAU,CAAC,GAAG,iBAAiB,GAAG,CAAC;QACzE,CAAC,CAAC,kBAAkB,CAAC,KAAK,CAAC,iBAAiB,CAAC,MAAM,GAAG,CAAC,CAAC;QACxD,CAAC,CAAC,WAAW,CAAC,QAAQ,CAAC,iBAAiB,EAAE,QAAQ,CAAC,CAAC,CAAA;IACtD,MAAM,SAAS,GAAG,YAAY,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,IAAI,IAAI,KAAK,EAAE,CAAC,CAAA;IAC7E,MAAM,WAAW,GAAG,SAAS,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAA;IAC1C,OAAO,WAAW,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,WAAW,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,CAAA;AACnE,CAAC"}

package/templates/starter/src/lib/template-sync-utils.ts

@@ -0,0 +1,65 @@
+import { join, relative } from 'path'
+
+const EXCLUDED_DIRS = new Set(['node_modules', '.next', '.git', 'dist'])
+const EXCLUDED_EXTENSIONS = new Set(['.db', '.sqlite', '.sqlite3', '.tsbuildinfo'])
+const EXCLUDED_PATH_PREFIXES = ['automation/reports/']
+const EXCLUDED_FILENAMES = new Set(['.DS_Store'])
+
+function toPosixPath(value: string): string {
+  return value.replace(/\\/g, '/')
+}
+
+export function shouldExcludeTemplatePath(relativePath: string): boolean {
+  const normalizedPath = toPosixPath(relativePath)
+  const parts = normalizedPath.split('/')
+
+  if (parts.some(part => EXCLUDED_DIRS.has(part))) return true
+  if (parts.some(part => EXCLUDED_FILENAMES.has(part))) return true
+  if (EXCLUDED_PATH_PREFIXES.some(prefix => normalizedPath.startsWith(prefix))) return true
+
+  const ext = normalizedPath.endsWith('.sqlite3')
+    ? '.sqlite3'
+    : normalizedPath.endsWith('.sqlite')
+      ? '.sqlite'
+      : normalizedPath.endsWith('.tsbuildinfo')
+        ? '.tsbuildinfo'
+        : normalizedPath.slice(normalizedPath.lastIndexOf('.'))
+
+  return EXCLUDED_EXTENSIONS.has(ext)
+}
+
+export function shouldBackfillLegacyEnvironmentConfig(
+  targetHasEnvironmentsFile: boolean,
+  legacyEnvironmentsDirExists: boolean,
+): boolean {
+  return !targetHasEnvironmentsFile && legacyEnvironmentsDirExists
+}
+
+export function getAutomationFeaturesDir(baseDir: string): string {
+  return join(baseDir, 'automation', 'features')
+}
+
+export function getAutomationLocatorsDir(baseDir: string): string {
+  return join(baseDir, 'automation', 'locators')
+}
+
+export function getAutomationLocatorMapPath(baseDir: string): string {
+  return join(baseDir, 'automation', 'mapping', 'locator-map.json')
+}
+
+export function extractModulePathFromAutomationFile(
+  filePath: string,
+  baseDir: string,
+  automationSubdir: 'features' | 'locators',
+): string {
+  const automationBaseDir =
+    automationSubdir === 'features' ? getAutomationFeaturesDir(baseDir) : getAutomationLocatorsDir(baseDir)
+  const normalizedBaseDir = toPosixPath(automationBaseDir).replace(/\/$/, '')
+  const normalizedFilePath = toPosixPath(filePath)
+  const relativePath = normalizedFilePath.startsWith(`${normalizedBaseDir}/`)
+    ? normalizedFilePath.slice(normalizedBaseDir.length + 1)
+    : toPosixPath(relative(automationBaseDir, filePath))
+  const pathParts = relativePath.split('/').filter(part => part && part !== '')
+  const moduleParts = pathParts.slice(0, -1)
+  return moduleParts.length > 0 ? `/${moduleParts.join('/')}` : '/'
+}

package/templates/starter/src/lib/test-case-utils.ts

@@ -0,0 +1,6 @@
+import crypto from 'crypto'
+
+export function generateUniqueTestCaseIdentifier(): string {
+  const id = crypto.randomBytes(8).toString('hex')
+  return `tc_${id}`
+}

package/templates/starter/src/lib/test-run/log-formatter.ts

@@ -0,0 +1,83 @@
+/**
+ * Log formatting utilities for storing and retrieving test run logs
+ */
+
+export interface LogEntry {
+  type: 'stdout' | 'stderr' | 'status'
+  message: string
+  timestamp: Date
+}
+
+/**
+ * Formats log entries into a single text string for storage in the database
+ * Format: [timestamp] [TYPE] message
+ * 
+ * @param logs - Array of log entries to format
+ * @returns Formatted log string
+ */
+export function formatLogsForStorage(logs: LogEntry[]): string {
+  return logs
+    .map(log => {
+      const timestamp = log.timestamp.toISOString()
+      const type = log.type.toUpperCase()
+      // Escape newlines in message to preserve them in the formatted string
+      const escapedMessage = log.message.replace(/\n/g, '\\n')
+      return `[${timestamp}] [${type}] ${escapedMessage}`
+    })
+    .join('\n')
+}
+
+/**
+ * Parses formatted log text back into an array of LogEntry objects
+ * 
+ * @param formattedLogs - Formatted log string from database
+ * @returns Array of log entries
+ */
+export function parseLogsFromStorage(formattedLogs: string): LogEntry[] {
+  if (!formattedLogs || formattedLogs.trim() === '') {
+    return []
+  }
+
+  const lines = formattedLogs.split('\n')
+  const parsedLogs: LogEntry[] = []
+
+  for (const line of lines) {
+    if (!line.trim()) continue
+
+    try {
+      // Match format: [timestamp] [TYPE] message
+      const match = line.match(/^\[([^\]]+)\] \[([^\]]+)\] (.+)$/)
+      
+      if (match) {
+        const [, timestampStr, typeStr, message] = match
+        const timestamp = new Date(timestampStr)
+        const type = typeStr.toLowerCase() as 'stdout' | 'stderr' | 'status'
+        
+        // Unescape newlines in message
+        const unescapedMessage = message.replace(/\\n/g, '\n')
+        
+        // Validate type
+        if (type === 'stdout' || type === 'stderr' || type === 'status') {
+          parsedLogs.push({
+            type,
+            message: unescapedMessage,
+            timestamp: isNaN(timestamp.getTime()) ? new Date() : timestamp,
+          })
+        }
+      } else {
+        // Fallback: treat as stdout if format doesn't match
+        parsedLogs.push({
+          type: 'stdout',
+          message: line,
+          timestamp: new Date(),
+        })
+      }
+    } catch (error) {
+      // Skip malformed lines
+      console.error('[LogFormatter] Error parsing log line:', line, error)
+    }
+  }
+
+  return parsedLogs
+}
+

package/templates/starter/src/lib/test-run/matching.ts

@@ -0,0 +1,117 @@
+import { TagType, TestRunTestCaseStatus } from '@prisma/client'
+import { getIdentifierTagByPrefix } from '@/lib/tag-utils'
+
+type TagLike = {
+  name: string
+  tagExpression: string
+  type: TagType
+}
+
+type MatchableRunTestCase = {
+  id: string
+  status: TestRunTestCaseStatus
+  testSuiteId: string | null
+  testCase: {
+    id: string
+    title: string
+    tags: TagLike[]
+  }
+  testSuite?: {
+    id: string
+    name: string
+    tags: TagLike[]
+  } | null
+}
+
+type ScenarioMatchInput = {
+  scenarioName: string
+  scenarioTags?: string[]
+}
+
+function normalizeTagExpression(tagExpression: string): string {
+  return tagExpression.startsWith('@') ? tagExpression : `@${tagExpression}`
+}
+
+function consumeCandidate<T extends MatchableRunTestCase>(candidates: T[]): T | undefined {
+  const unconsumed = candidates.find(
+    candidate =>
+      candidate.status !== TestRunTestCaseStatus.COMPLETED && candidate.status !== TestRunTestCaseStatus.CANCELLED,
+  )
+
+  return unconsumed ?? candidates[0]
+}
+
+export function extractTestCaseTitleFromScenarioName(scenarioName: string): string | null {
+  const bracketMatch = scenarioName.match(/^\[([^\]]+)\]/)
+  if (bracketMatch) {
+    return bracketMatch[1].trim()
+  }
+
+  const trimmedName = scenarioName.trim()
+  return trimmedName.length > 0 ? trimmedName : null
+}
+
+export function findMatchingTestRunTestCase<T extends MatchableRunTestCase>(
+  testRunTestCases: T[],
+  { scenarioName, scenarioTags = [] }: ScenarioMatchInput,
+): T | undefined {
+  const suiteIdentifierTag = scenarioTags.find(tag => normalizeTagExpression(tag).startsWith('@ts_'))
+  const testCaseIdentifierTag = scenarioTags.find(tag => normalizeTagExpression(tag).startsWith('@tc_'))
+  const testCaseTitle = extractTestCaseTitleFromScenarioName(scenarioName)
+
+  const bySuite = suiteIdentifierTag
+    ? testRunTestCases.filter(testRunTestCase => {
+        const identifierTag = testRunTestCase.testSuite
+          ? getIdentifierTagByPrefix(testRunTestCase.testSuite.tags, 'ts_')
+          : undefined
+
+        return identifierTag?.tagExpression === normalizeTagExpression(suiteIdentifierTag)
+      })
+    : []
+
+  if (bySuite.length > 0) {
+    if (testCaseIdentifierTag) {
+      const bySuiteAndTestCaseIdentifier = bySuite.filter(testRunTestCase => {
+        const identifierTag = getIdentifierTagByPrefix(testRunTestCase.testCase.tags, 'tc_')
+        return identifierTag?.tagExpression === normalizeTagExpression(testCaseIdentifierTag)
+      })
+
+      const matchedBySuiteAndTestCaseIdentifier = consumeCandidate(bySuiteAndTestCaseIdentifier)
+      if (matchedBySuiteAndTestCaseIdentifier) {
+        return matchedBySuiteAndTestCaseIdentifier
+      }
+    }
+
+    if (testCaseTitle) {
+      const bySuiteAndTitle = bySuite.filter(testRunTestCase => testRunTestCase.testCase.title === testCaseTitle)
+      const matchedBySuiteAndTitle = consumeCandidate(bySuiteAndTitle)
+      if (matchedBySuiteAndTitle) {
+        return matchedBySuiteAndTitle
+      }
+    }
+
+    return consumeCandidate(bySuite)
+  }
+
+  if (testCaseIdentifierTag) {
+    const byTestCaseIdentifier = testRunTestCases.filter(testRunTestCase => {
+      const identifierTag = getIdentifierTagByPrefix(testRunTestCase.testCase.tags, 'tc_')
+      return identifierTag?.tagExpression === normalizeTagExpression(testCaseIdentifierTag)
+    })
+
+    const matchedByTestCaseIdentifier = consumeCandidate(byTestCaseIdentifier)
+    if (matchedByTestCaseIdentifier) {
+      return matchedByTestCaseIdentifier
+    }
+  }
+
+  if (testCaseTitle) {
+    const byTitle = testRunTestCases.filter(testRunTestCase => testRunTestCase.testCase.title === testCaseTitle)
+    const matchedByTitle = consumeCandidate(byTitle)
+    if (matchedByTitle) {
+      return matchedByTitle
+    }
+  }
+
+  return undefined
+}

package/templates/starter/src/lib/test-run/process-manager.ts

@@ -0,0 +1,115 @@
+import type { SpawnedProcess } from '@/lib/process/task-spawner'
+import { EventEmitter } from 'events'
+import { taskSpawner } from '@/lib/process/task-spawner'
+
+class ProcessManager extends EventEmitter {
+  private processes: Map<string, SpawnedProcess> = new Map()
+  private eventListeners: Map<string, Map<string, () => void>> = new Map()
+
+  private constructor() {
+    super()
+  }
+
+  static getInstance(): ProcessManager {
+    const globalForProcessManager = global as unknown as {
+      processManager: ProcessManager | undefined
+    }
+
+    if (!globalForProcessManager.processManager) {
+      globalForProcessManager.processManager = new ProcessManager()
+    }
+
+    return globalForProcessManager.processManager
+  }
+
+  register(testRunId: string, process: SpawnedProcess): void {
+    this.processes.set(testRunId, process)
+    const listeners = new Map<string, () => void>()
+
+    const onStdout = ({ processName, data }: { processName: string; data: string }) => {
+      if (processName === process.name) {
+        this.parseAndEmitCustomEvents(testRunId, data)
+      }
+    }
+
+    const onStderr = ({ processName, data }: { processName: string; data: string }) => {
+      if (processName === process.name) {
+        this.parseAndEmitCustomEvents(testRunId, data)
+      }
+    }
+
+    listeners.set('stdout', () => taskSpawner.removeListener('stdout', onStdout))
+    listeners.set('stderr', () => taskSpawner.removeListener('stderr', onStderr))
+
+    taskSpawner.on('stdout', onStdout)
+    taskSpawner.on('stderr', onStderr)
+
+    this.eventListeners.set(testRunId, listeners)
+  }
+
+  private parseAndEmitCustomEvents(testRunId: string, output: string): void {
+    const lines = output.split('\n')
+
+    for (const line of lines) {
+      if (!line.trim()) {
+        continue
+      }
+
+      try {
+        const jsonMatch = line.match(/\{[\s\S]*"event"[\s\S]*\}/)
+        if (jsonMatch) {
+          const eventData = JSON.parse(jsonMatch[0])
+          if (eventData.event === 'scenario::end') {
+            this.emit('scenario::end', {
+              testRunId,
+              featureName: eventData.data?.featureName,
+              scenarioName: eventData.data?.scenarioName,
+              scenarioTags: eventData.data?.scenarioTags,
+              status: eventData.data?.status,
+              tracePath: eventData.data?.tracePath,
+              ...eventData.data,
+            })
+          }
+        }
+      } catch {
+        continue
+      }
+    }
+  }
+
+  get(testRunId: string): SpawnedProcess | undefined {
+    return this.processes.get(testRunId)
+  }
+
+  unregister(testRunId: string): boolean {
+    const listeners = this.eventListeners.get(testRunId)
+    if (listeners) {
+      listeners.forEach(cleanup => cleanup())
+      this.eventListeners.delete(testRunId)
+    }
+
+    return this.processes.delete(testRunId)
+  }
+
+  has(testRunId: string): boolean {
+    return this.processes.has(testRunId)
+  }
+
+  getAllTestRunIds(): string[] {
+    return Array.from(this.processes.keys())
+  }
+
+  clear(): void {
+    this.eventListeners.forEach(listeners => {
+      listeners.forEach(cleanup => cleanup())
+    })
+    this.eventListeners.clear()
+    this.processes.clear()
+  }
+
+  size(): number {
+    return this.processes.size
+  }
+}
+
+export const processManager = ProcessManager.getInstance()