create-appraisejs 0.3.0-alpha.0 → 0.3.0

package/templates/starter/packages/locator-picker-companion/src/launcher.ts

@@ -0,0 +1,77 @@
+import { access, readdir, stat } from 'fs/promises'
+import { execa } from 'execa'
+import path from 'path'
+
+async function pathExists(targetPath: string): Promise<boolean> {
+  try {
+    await access(targetPath)
+    return true
+  } catch {
+    return false
+  }
+}
+
+async function getLatestModifiedTime(targetPath: string): Promise<number> {
+  const stats = await stat(targetPath)
+  if (!stats.isDirectory()) {
+    return stats.mtimeMs
+  }
+
+  const entries = await readdir(targetPath, { withFileTypes: true })
+  const times = await Promise.all(
+    entries.map(entry => getLatestModifiedTime(path.join(targetPath, entry.name))),
+  )
+
+  return Math.max(stats.mtimeMs, ...times)
+}
+
+export function getLocatorPickerCompanionPaths(repoRoot = process.cwd()) {
+  const packageRoot = path.join(repoRoot, 'packages', 'locator-picker-companion')
+
+  return {
+    packageRoot,
+    sourceRoot: path.join(packageRoot, 'src'),
+    distCliPath: path.join(packageRoot, 'dist', 'cli.js'),
+    tsconfigPath: path.join(packageRoot, 'tsconfig.json'),
+    tscCliPath: path.join(repoRoot, 'node_modules', 'typescript', 'bin', 'tsc'),
+  }
+}
+
+async function ensureLocatorPickerCompanionBuilt(repoRoot = process.cwd()): Promise<string> {
+  const { distCliPath, sourceRoot, tsconfigPath, tscCliPath } = getLocatorPickerCompanionPaths(repoRoot)
+
+  if (await pathExists(distCliPath)) {
+    const [distMtime, srcMtime] = await Promise.all([
+      getLatestModifiedTime(distCliPath),
+      getLatestModifiedTime(sourceRoot),
+    ])
+
+    if (distMtime >= srcMtime) {
+      return distCliPath
+    }
+  }
+
+  await execa(process.execPath, [tscCliPath, '-p', tsconfigPath], {
+    cwd: repoRoot,
+    env: process.env,
+    stdio: 'pipe',
+  })
+
+  if (!(await pathExists(distCliPath))) {
+    throw new Error('Locator picker companion build completed without producing dist/cli.js.')
+  }
+
+  return distCliPath
+}
+
+export async function resolveLocatorPickerCompanionInvocation(
+  cliArgs: string[],
+  repoRoot = process.cwd(),
+): Promise<{ command: string; args: string[] }> {
+  const distCliPath = await ensureLocatorPickerCompanionBuilt(repoRoot)
+
+  return {
+    command: process.execPath,
+    args: [distCliPath, ...cliArgs],
+  }
+}

package/templates/starter/packages/locator-picker-companion/src/selector-generator.ts

@@ -0,0 +1,339 @@
+import type { ElementHandle, Page } from 'playwright'
+import type { CompanionPickedLocatorPayload, CompanionPickedLocatorStrategy } from './types.js'
+
+interface ElementSnapshot {
+  tagName: string
+  text: string
+  accessibleName: string
+  labelText: string
+  placeholder: string
+  id: string
+  role: string
+  roleNameMatchCount: number
+  stableClasses: string[]
+  nameAttribute: string
+  typeAttribute: string
+  ariaLabel: string
+  testAttributeName: string
+  testAttributeValue: string
+}
+
+function normalizeText(value: string | null | undefined): string {
+  return (value ?? '').replace(/\s+/g, ' ').trim()
+}
+
+function normalizeRoute(value: string): string {
+  if (!value) {
+    return '/'
+  }
+
+  try {
+    return new URL(value).pathname || '/'
+  } catch {
+    return value.startsWith('/') ? value : `/${value}`
+  }
+}
+
+function escapeForCss(value: string): string {
+  return value.replace(/[^a-zA-Z0-9_-]/g, match => `\\${match}`)
+}
+
+function escapeForSelectorText(value: string): string {
+  return value.replace(/\\/g, '\\\\').replace(/"/g, '\\"')
+}
+
+function isLikelyStableIdentifier(value: string | null | undefined): value is string {
+  if (!value) {
+    return false
+  }
+
+  const normalized = value.trim()
+  if (!normalized || normalized.length > 120) {
+    return false
+  }
+
+  return !/\d{4,}/.test(normalized) && !/[A-Fa-f0-9]{8,}/.test(normalized)
+}
+
+function buildCssSelector(snapshot: ElementSnapshot): string {
+  const parts = [snapshot.tagName]
+
+  if (isLikelyStableIdentifier(snapshot.nameAttribute)) {
+    parts.push(`[name="${escapeForSelectorText(snapshot.nameAttribute)}"]`)
+  }
+
+  if (isLikelyStableIdentifier(snapshot.typeAttribute)) {
+    parts.push(`[type="${escapeForSelectorText(snapshot.typeAttribute)}"]`)
+  }
+
+  if (isLikelyStableIdentifier(snapshot.ariaLabel)) {
+    parts.push(`[aria-label="${escapeForSelectorText(snapshot.ariaLabel)}"]`)
+  }
+
+  if (parts.length === 1 && snapshot.stableClasses.length > 0) {
+    parts.push(...snapshot.stableClasses.slice(0, 2).map(className => `.${escapeForCss(className)}`))
+  }
+
+  return parts.length > 1 ? `css=${parts.join('')}` : ''
+}
+
+function buildXPathSelector(snapshot: ElementSnapshot): string {
+  if (snapshot.id) {
+    return `xpath=//*[@id="${snapshot.id.replace(/"/g, '\\"')}"]`
+  }
+
+  if (snapshot.text) {
+    return `xpath=//${snapshot.tagName}[normalize-space()="${snapshot.text.replace(/"/g, '\\"')}"]`
+  }
+
+  return `xpath=//${snapshot.tagName}`
+}
+
+function buildPrimarySelector(snapshot: ElementSnapshot): {
+  selector: string
+  strategy: CompanionPickedLocatorStrategy
+} {
+  if (isLikelyStableIdentifier(snapshot.testAttributeValue)) {
+    return {
+      selector: `css=[${snapshot.testAttributeName}="${escapeForSelectorText(snapshot.testAttributeValue)}"]`,
+      strategy: 'test-id',
+    }
+  }
+
+  if (snapshot.role && snapshot.accessibleName && snapshot.roleNameMatchCount === 1) {
+    return {
+      selector: `role=${snapshot.role}[name="${escapeForSelectorText(snapshot.accessibleName)}"]`,
+      strategy: 'role',
+    }
+  }
+
+  if (snapshot.labelText) {
+    return {
+      selector: `label="${escapeForSelectorText(snapshot.labelText)}"`,
+      strategy: 'label',
+    }
+  }
+
+  if (snapshot.placeholder) {
+    return {
+      selector: `placeholder="${escapeForSelectorText(snapshot.placeholder)}"`,
+      strategy: 'placeholder',
+    }
+  }
+
+  if (isLikelyStableIdentifier(snapshot.id)) {
+    return {
+      selector: `css=#${escapeForCss(snapshot.id)}`,
+      strategy: 'id',
+    }
+  }
+
+  const cssSelector = buildCssSelector(snapshot)
+  if (cssSelector) {
+    return {
+      selector: cssSelector,
+      strategy: 'css',
+    }
+  }
+
+  return {
+    selector: buildXPathSelector(snapshot),
+    strategy: 'xpath',
+  }
+}
+
+async function getElementSnapshot(elementHandle: ElementHandle): Promise<ElementSnapshot> {
+  return elementHandle.evaluate(node => {
+    const element = node as Element
+    const normalizeText = (value: string | null | undefined): string => (value ?? '').replace(/\s+/g, ' ').trim()
+    const isLikelyStableIdentifier = (value: string | null | undefined): value is string => {
+      if (!value) {
+        return false
+      }
+
+      const normalized = value.trim()
+      if (!normalized || normalized.length > 120) {
+        return false
+      }
+
+      return !/\d{4,}/.test(normalized) && !/[A-Fa-f0-9]{8,}/.test(normalized)
+    }
+
+    const getLabelText = (candidate: Element): string => {
+      if (!['input', 'textarea', 'select'].includes(candidate.tagName.toLowerCase())) {
+        return ''
+      }
+
+      const input = candidate as HTMLInputElement | HTMLTextAreaElement | HTMLSelectElement
+      if (input.labels && input.labels.length > 0) {
+        return normalizeText(
+          Array.from(input.labels)
+            .map(label => label.textContent || '')
+            .join(' '),
+        )
+      }
+
+      return ''
+    }
+
+    const getAccessibleName = (candidate: Element): string => {
+      const ariaLabel = normalizeText(candidate.getAttribute('aria-label'))
+      if (ariaLabel) {
+        return ariaLabel
+      }
+
+      const labelledBy = normalizeText(candidate.getAttribute('aria-labelledby'))
+      if (labelledBy) {
+        const text = labelledBy
+          .split(/\s+/)
+          .map(id => document.getElementById(id)?.textContent || '')
+          .join(' ')
+        const normalized = normalizeText(text)
+        if (normalized) {
+          return normalized
+        }
+      }
+
+      const labelText = getLabelText(candidate)
+      if (labelText) {
+        return labelText
+      }
+
+      const alt = normalizeText(candidate.getAttribute('alt'))
+      if (alt) {
+        return alt
+      }
+
+      const title = normalizeText(candidate.getAttribute('title'))
+      if (title) {
+        return title
+      }
+
+      const placeholder = normalizeText(candidate.getAttribute('placeholder'))
+      if (placeholder) {
+        return placeholder
+      }
+
+      return normalizeText(candidate.textContent).slice(0, 240)
+    }
+
+    const getRole = (candidate: Element): string => {
+      const explicitRole = normalizeText(candidate.getAttribute('role'))
+      if (explicitRole) {
+        return explicitRole
+      }
+
+      const tagName = candidate.tagName.toLowerCase()
+      if (tagName === 'button') {
+        return 'button'
+      }
+
+      if (tagName === 'a' && candidate.hasAttribute('href')) {
+        return 'link'
+      }
+
+      if (tagName === 'textarea') {
+        return 'textbox'
+      }
+
+      if (tagName === 'select') {
+        return 'combobox'
+      }
+
+      if (tagName === 'img') {
+        return 'img'
+      }
+
+      if (tagName === 'input') {
+        const type = (candidate.getAttribute('type') || 'text').toLowerCase()
+        if (['button', 'submit', 'reset'].includes(type)) {
+          return 'button'
+        }
+
+        if (type === 'checkbox') {
+          return 'checkbox'
+        }
+
+        if (type === 'radio') {
+          return 'radio'
+        }
+
+        return 'textbox'
+      }
+
+      return ''
+    }
+
+    const role = getRole(element)
+    const accessibleName = getAccessibleName(element)
+
+    let roleNameMatchCount = 0
+    if (role && accessibleName) {
+      for (const candidate of Array.from(document.querySelectorAll('*'))) {
+        if (getRole(candidate) !== role) {
+          continue
+        }
+
+        if (getAccessibleName(candidate) !== accessibleName) {
+          continue
+        }
+
+        roleNameMatchCount += 1
+        if (roleNameMatchCount > 1) {
+          break
+        }
+      }
+    }
+
+    let testAttributeName = ''
+    let testAttributeValue = ''
+    for (const attributeName of ['data-testid', 'data-test', 'data-qa']) {
+      const value = element.getAttribute(attributeName)
+      if (isLikelyStableIdentifier(value)) {
+        testAttributeName = attributeName
+        testAttributeValue = value
+        break
+      }
+    }
+
+    return {
+      tagName: element.tagName.toLowerCase(),
+      text: normalizeText(element.textContent).slice(0, 240),
+      accessibleName,
+      labelText: getLabelText(element),
+      placeholder: normalizeText(element.getAttribute('placeholder')),
+      id: normalizeText(element.getAttribute('id')),
+      role,
+      roleNameMatchCount,
+      stableClasses: Array.from(element.classList || [])
+        .filter((className): className is string => isLikelyStableIdentifier(className))
+        .slice(0, 2),
+      nameAttribute: normalizeText(element.getAttribute('name')),
+      typeAttribute: normalizeText(element.getAttribute('type')),
+      ariaLabel: normalizeText(element.getAttribute('aria-label')),
+      testAttributeName,
+      testAttributeValue,
+    }
+  })
+}
+
+export async function generatePickedLocatorPayload(
+  page: Page,
+  elementHandle: ElementHandle,
+): Promise<CompanionPickedLocatorPayload> {
+  const snapshot = await getElementSnapshot(elementHandle)
+  const selection = buildPrimarySelector(snapshot)
+  const currentUrl = page.url()
+  const pageTitle = normalizeText(await page.title().catch(() => ''))
+
+  return {
+    selector: selection.selector,
+    strategy: selection.strategy,
+    currentUrl,
+    pathname: normalizeRoute(currentUrl),
+    pageTitle,
+    tagName: snapshot.tagName,
+    text: snapshot.text || undefined,
+    accessibleName: snapshot.accessibleName || undefined,
+  }
+}

package/templates/starter/packages/locator-picker-companion/src/session-file.ts

@@ -0,0 +1,226 @@
+import { randomUUID } from 'crypto'
+import { access, appendFile, mkdir, readFile, rename, rm, unlink, writeFile } from 'fs/promises'
+import path from 'path'
+import type { CompanionSessionFile } from './types.js'
+
+const sessionFileOperationQueue = new Map<string, Promise<unknown>>()
+
+function withTimestamp(
+  session: Omit<CompanionSessionFile, 'updatedAt'> & { updatedAt?: string },
+): CompanionSessionFile {
+  return {
+    ...session,
+    updatedAt: session.updatedAt ?? new Date().toISOString(),
+  }
+}
+
+export function getLocatorPickerRootDir(repoRoot = process.cwd()): string {
+  return path.join(repoRoot, '.tmp', 'locator-picker')
+}
+
+export function getLocatorPickerSessionsDir(repoRoot = process.cwd()): string {
+  return path.join(getLocatorPickerRootDir(repoRoot), 'sessions')
+}
+
+export function getLocatorPickerProfilesDir(repoRoot = process.cwd()): string {
+  return path.join(getLocatorPickerRootDir(repoRoot), 'profiles')
+}
+
+export function getLocatorPickerLogsDir(repoRoot = process.cwd()): string {
+  return path.join(getLocatorPickerRootDir(repoRoot), 'logs')
+}
+
+export function getLocatorPickerProfileDir(sessionId: string, repoRoot = process.cwd()): string {
+  return path.join(getLocatorPickerProfilesDir(repoRoot), sessionId)
+}
+
+export function getLocatorPickerRuntimeDir(repoRoot = process.cwd()): string {
+  return path.join(getLocatorPickerRootDir(repoRoot), 'runtime')
+}
+
+export function getLocatorPickerRuntimeHomeDir(repoRoot = process.cwd()): string {
+  return path.join(getLocatorPickerRuntimeDir(repoRoot), 'home')
+}
+
+export function getLocatorPickerRuntimeEnv(
+  repoRoot = process.cwd(),
+  baseEnv: NodeJS.ProcessEnv = process.env,
+): NodeJS.ProcessEnv {
+  const runtimeDir = getLocatorPickerRuntimeDir(repoRoot)
+  const runtimeHomeDir = getLocatorPickerRuntimeHomeDir(repoRoot)
+  const tempDir = path.join(runtimeDir, 'tmp')
+  const configDir = path.join(runtimeDir, 'config')
+  const cacheDir = path.join(runtimeDir, 'cache')
+  const appDataDir = path.join(runtimeDir, 'appdata')
+  const localAppDataDir = path.join(runtimeDir, 'localappdata')
+
+  return {
+    ...baseEnv,
+    HOME: runtimeHomeDir,
+    USERPROFILE: runtimeHomeDir,
+    APPDATA: appDataDir,
+    LOCALAPPDATA: localAppDataDir,
+    XDG_CONFIG_HOME: configDir,
+    XDG_CACHE_HOME: cacheDir,
+    TMPDIR: tempDir,
+    TMP: tempDir,
+    TEMP: tempDir,
+  }
+}
+
+export function getLocatorPickerSessionFilePath(sessionId: string, repoRoot = process.cwd()): string {
+  return path.join(getLocatorPickerSessionsDir(repoRoot), `${sessionId}.json`)
+}
+
+export function getLocatorPickerCrashLogPath(sessionId: string, repoRoot = process.cwd()): string {
+  return path.join(getLocatorPickerLogsDir(repoRoot), `${sessionId}.log`)
+}
+
+export async function removeLocatorPickerProfileDir(
+  sessionId: string,
+  repoRoot = process.cwd(),
+): Promise<void> {
+  await rm(getLocatorPickerProfileDir(sessionId, repoRoot), {
+    force: true,
+    recursive: true,
+  }).catch(() => undefined)
+}
+
+export async function removeLocatorPickerSessionFile(
+  sessionId: string,
+  repoRoot = process.cwd(),
+): Promise<void> {
+  await unlink(getLocatorPickerSessionFilePath(sessionId, repoRoot)).catch(() => undefined)
+}
+
+export async function clearLocatorPickerCrashLogs(repoRoot = process.cwd()): Promise<void> {
+  await rm(getLocatorPickerLogsDir(repoRoot), {
+    force: true,
+    recursive: true,
+  }).catch(() => console.error('Failed to clear locator picker crash logs.'))
+
+  await mkdir(getLocatorPickerLogsDir(repoRoot), { recursive: true })
+}
+
+export async function createLocatorPickerCrashLog(logFilePath: string): Promise<void> {
+  await mkdir(path.dirname(logFilePath), { recursive: true })
+  await writeFile(logFilePath, '', 'utf8')
+}
+
+export async function appendLocatorPickerCrashLog(logFilePath: string, message: string): Promise<void> {
+  try {
+    await access(logFilePath)
+  } catch {
+    return
+  }
+
+  await appendFile(logFilePath, `[${new Date().toISOString()}] ${message}\n`, 'utf8')
+}
+
+export async function ensureLocatorPickerDirectories(repoRoot = process.cwd()): Promise<void> {
+  const runtimeDir = getLocatorPickerRuntimeDir(repoRoot)
+  const runtimeHomeDir = getLocatorPickerRuntimeHomeDir(repoRoot)
+  const tempDir = path.join(runtimeDir, 'tmp')
+  const configDir = path.join(runtimeDir, 'config')
+  const cacheDir = path.join(runtimeDir, 'cache')
+  const appDataDir = path.join(runtimeDir, 'appdata')
+  const localAppDataDir = path.join(runtimeDir, 'localappdata')
+
+  await mkdir(getLocatorPickerSessionsDir(repoRoot), { recursive: true })
+  await mkdir(getLocatorPickerProfilesDir(repoRoot), { recursive: true })
+  await mkdir(getLocatorPickerLogsDir(repoRoot), { recursive: true })
+  await mkdir(runtimeHomeDir, { recursive: true })
+  await mkdir(tempDir, { recursive: true })
+  await mkdir(configDir, { recursive: true })
+  await mkdir(cacheDir, { recursive: true })
+  await mkdir(appDataDir, { recursive: true })
+  await mkdir(localAppDataDir, { recursive: true })
+}
+
+export async function readLocatorPickerSessionFile(
+  sessionFilePath: string,
+): Promise<CompanionSessionFile | null> {
+  try {
+    const raw = await readFile(sessionFilePath, 'utf8')
+    return JSON.parse(raw) as CompanionSessionFile
+  } catch {
+    return null
+  }
+}
+
+async function enqueueSessionFileOperation<T>(
+  sessionFilePath: string,
+  operation: () => Promise<T>,
+): Promise<T> {
+  const previousOperation = sessionFileOperationQueue.get(sessionFilePath) ?? Promise.resolve()
+  const nextOperation = previousOperation.catch(() => undefined).then(operation)
+
+  sessionFileOperationQueue.set(sessionFilePath, nextOperation)
+
+  try {
+    return await nextOperation
+  } finally {
+    if (sessionFileOperationQueue.get(sessionFilePath) === nextOperation) {
+      sessionFileOperationQueue.delete(sessionFilePath)
+    }
+  }
+}
+
+async function writeLocatorPickerSessionFileImmediate(
+  sessionFilePath: string,
+  session: Omit<CompanionSessionFile, 'updatedAt'> & { updatedAt?: string },
+): Promise<CompanionSessionFile> {
+  await mkdir(path.dirname(sessionFilePath), { recursive: true })
+
+  const normalized = withTimestamp(session)
+  const serialized = `${JSON.stringify(normalized, null, 2)}\n`
+  const tempFilePath = `${sessionFilePath}.${process.pid}.${randomUUID()}.tmp`
+
+  try {
+    await writeFile(tempFilePath, serialized, 'utf8')
+    await rename(tempFilePath, sessionFilePath)
+  } catch (error) {
+    await unlink(tempFilePath).catch(() => undefined)
+
+    const code = error instanceof Error && 'code' in error ? String(error.code) : ''
+    if (process.platform === 'win32' || code === 'EPERM' || code === 'EACCES' || code === 'ENOENT') {
+      await writeFile(sessionFilePath, serialized, 'utf8')
+    } else {
+      throw error
+    }
+  }
+
+  return normalized
+}
+
+export async function writeLocatorPickerSessionFile(
+  sessionFilePath: string,
+  session: Omit<CompanionSessionFile, 'updatedAt'> & { updatedAt?: string },
+): Promise<CompanionSessionFile> {
+  return enqueueSessionFileOperation(sessionFilePath, () =>
+    writeLocatorPickerSessionFileImmediate(sessionFilePath, session),
+  )
+}
+
+export async function patchLocatorPickerSessionFile(
+  sessionFilePath: string,
+  patch:
+    | Partial<CompanionSessionFile>
+    | ((current: CompanionSessionFile) => Partial<CompanionSessionFile> | CompanionSessionFile),
+): Promise<CompanionSessionFile | null> {
+  return enqueueSessionFileOperation(sessionFilePath, async () => {
+    const current = await readLocatorPickerSessionFile(sessionFilePath)
+    if (!current) {
+      return null
+    }
+
+    const nextPatch = typeof patch === 'function' ? patch(current) : patch
+    const nextSession = {
+      ...current,
+      ...nextPatch,
+      updatedAt: new Date().toISOString(),
+    }
+
+    return writeLocatorPickerSessionFileImmediate(sessionFilePath, nextSession)
+  })
+}

package/templates/starter/packages/locator-picker-companion/src/types.ts

@@ -0,0 +1,42 @@
+export type CompanionSessionStatus = 'starting' | 'ready' | 'picked' | 'saving' | 'closed' | 'error'
+
+export type CompanionPickedLocatorStrategy =
+  | 'test-id'
+  | 'role'
+  | 'label'
+  | 'placeholder'
+  | 'id'
+  | 'css'
+  | 'xpath'
+
+export interface CompanionLaunchSource {
+  environmentId?: string
+  environmentName?: string
+  url: string
+}
+
+export interface CompanionPickedLocatorPayload {
+  selector: string
+  currentUrl: string
+  pathname: string
+  pageTitle: string
+  tagName: string
+  text?: string
+  accessibleName?: string
+  strategy?: CompanionPickedLocatorStrategy
+}
+
+export interface CompanionSessionFile {
+  sessionId: string
+  status: CompanionSessionStatus
+  launchSource: CompanionLaunchSource
+  currentUrl: string
+  currentPathname: string
+  pageTitle: string
+  companionPid: number | null
+  crashLogPath?: string
+  pickedLocator?: CompanionPickedLocatorPayload
+  error?: string
+  startedAt: string
+  updatedAt: string
+}

package/templates/starter/packages/locator-picker-companion/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "dist",
+    "noEmit": false,
+    "declaration": true,
+    "emitDeclarationOnly": false,
+    "lib": ["dom", "esnext"],
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext"
+  },
+  "include": ["src/**/*.ts"]
+}

package/templates/starter/postcss.config.mjs

@@ -0,0 +1,8 @@
+/** @type {import('postcss-load-config').Config} */
+const config = {
+  plugins: {
+    tailwindcss: {},
+  },
+};
+
+export default config;