create-appraisejs 0.3.0-alpha.0 → 0.3.0

package/templates/starter/packages/locator-picker-companion/dist/selector-generator.js

@@ -0,0 +1,257 @@
+function normalizeText(value) {
+    return (value !== null && value !== void 0 ? value : '').replace(/\s+/g, ' ').trim();
+}
+function normalizeRoute(value) {
+    if (!value) {
+        return '/';
+    }
+    try {
+        return new URL(value).pathname || '/';
+    }
+    catch (_a) {
+        return value.startsWith('/') ? value : `/${value}`;
+    }
+}
+function escapeForCss(value) {
+    return value.replace(/[^a-zA-Z0-9_-]/g, match => `\\${match}`);
+}
+function escapeForSelectorText(value) {
+    return value.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+}
+function isLikelyStableIdentifier(value) {
+    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) {
+    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) {
+    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) {
+    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) {
+    return elementHandle.evaluate(node => {
+        const element = node;
+        const normalizeText = (value) => (value !== null && value !== void 0 ? value : '').replace(/\s+/g, ' ').trim();
+        const isLikelyStableIdentifier = (value) => {
+            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) => {
+            if (!['input', 'textarea', 'select'].includes(candidate.tagName.toLowerCase())) {
+                return '';
+            }
+            const input = candidate;
+            if (input.labels && input.labels.length > 0) {
+                return normalizeText(Array.from(input.labels)
+                    .map(label => label.textContent || '')
+                    .join(' '));
+            }
+            return '';
+        };
+        const getAccessibleName = (candidate) => {
+            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 => { var _a; return ((_a = document.getElementById(id)) === null || _a === void 0 ? void 0 : _a.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) => {
+            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) => 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, elementHandle) {
+    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/dist/session-file.d.ts

@@ -0,0 +1,22 @@
+import type { CompanionSessionFile } from './types.js';
+export declare function getLocatorPickerRootDir(repoRoot?: string): string;
+export declare function getLocatorPickerSessionsDir(repoRoot?: string): string;
+export declare function getLocatorPickerProfilesDir(repoRoot?: string): string;
+export declare function getLocatorPickerLogsDir(repoRoot?: string): string;
+export declare function getLocatorPickerProfileDir(sessionId: string, repoRoot?: string): string;
+export declare function getLocatorPickerRuntimeDir(repoRoot?: string): string;
+export declare function getLocatorPickerRuntimeHomeDir(repoRoot?: string): string;
+export declare function getLocatorPickerRuntimeEnv(repoRoot?: string, baseEnv?: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
+export declare function getLocatorPickerSessionFilePath(sessionId: string, repoRoot?: string): string;
+export declare function getLocatorPickerCrashLogPath(sessionId: string, repoRoot?: string): string;
+export declare function removeLocatorPickerProfileDir(sessionId: string, repoRoot?: string): Promise<void>;
+export declare function removeLocatorPickerSessionFile(sessionId: string, repoRoot?: string): Promise<void>;
+export declare function clearLocatorPickerCrashLogs(repoRoot?: string): Promise<void>;
+export declare function createLocatorPickerCrashLog(logFilePath: string): Promise<void>;
+export declare function appendLocatorPickerCrashLog(logFilePath: string, message: string): Promise<void>;
+export declare function ensureLocatorPickerDirectories(repoRoot?: string): Promise<void>;
+export declare function readLocatorPickerSessionFile(sessionFilePath: string): Promise<CompanionSessionFile | null>;
+export declare function writeLocatorPickerSessionFile(sessionFilePath: string, session: Omit<CompanionSessionFile, 'updatedAt'> & {
+    updatedAt?: string;
+}): Promise<CompanionSessionFile>;
+export declare function patchLocatorPickerSessionFile(sessionFilePath: string, patch: Partial<CompanionSessionFile> | ((current: CompanionSessionFile) => Partial<CompanionSessionFile> | CompanionSessionFile)): Promise<CompanionSessionFile | null>;

package/templates/starter/packages/locator-picker-companion/dist/session-file.js

@@ -0,0 +1,150 @@
+import { randomUUID } from 'crypto';
+import { access, appendFile, mkdir, readFile, rename, rm, unlink, writeFile } from 'fs/promises';
+import path from 'path';
+const sessionFileOperationQueue = new Map();
+function withTimestamp(session) {
+    var _a;
+    return Object.assign(Object.assign({}, session), { updatedAt: (_a = session.updatedAt) !== null && _a !== void 0 ? _a : new Date().toISOString() });
+}
+export function getLocatorPickerRootDir(repoRoot = process.cwd()) {
+    return path.join(repoRoot, '.tmp', 'locator-picker');
+}
+export function getLocatorPickerSessionsDir(repoRoot = process.cwd()) {
+    return path.join(getLocatorPickerRootDir(repoRoot), 'sessions');
+}
+export function getLocatorPickerProfilesDir(repoRoot = process.cwd()) {
+    return path.join(getLocatorPickerRootDir(repoRoot), 'profiles');
+}
+export function getLocatorPickerLogsDir(repoRoot = process.cwd()) {
+    return path.join(getLocatorPickerRootDir(repoRoot), 'logs');
+}
+export function getLocatorPickerProfileDir(sessionId, repoRoot = process.cwd()) {
+    return path.join(getLocatorPickerProfilesDir(repoRoot), sessionId);
+}
+export function getLocatorPickerRuntimeDir(repoRoot = process.cwd()) {
+    return path.join(getLocatorPickerRootDir(repoRoot), 'runtime');
+}
+export function getLocatorPickerRuntimeHomeDir(repoRoot = process.cwd()) {
+    return path.join(getLocatorPickerRuntimeDir(repoRoot), 'home');
+}
+export function getLocatorPickerRuntimeEnv(repoRoot = process.cwd(), baseEnv = process.env) {
+    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 Object.assign(Object.assign({}, 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, repoRoot = process.cwd()) {
+    return path.join(getLocatorPickerSessionsDir(repoRoot), `${sessionId}.json`);
+}
+export function getLocatorPickerCrashLogPath(sessionId, repoRoot = process.cwd()) {
+    return path.join(getLocatorPickerLogsDir(repoRoot), `${sessionId}.log`);
+}
+export async function removeLocatorPickerProfileDir(sessionId, repoRoot = process.cwd()) {
+    await rm(getLocatorPickerProfileDir(sessionId, repoRoot), {
+        force: true,
+        recursive: true,
+    }).catch(() => undefined);
+}
+export async function removeLocatorPickerSessionFile(sessionId, repoRoot = process.cwd()) {
+    await unlink(getLocatorPickerSessionFilePath(sessionId, repoRoot)).catch(() => undefined);
+}
+export async function clearLocatorPickerCrashLogs(repoRoot = process.cwd()) {
+    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) {
+    await mkdir(path.dirname(logFilePath), { recursive: true });
+    await writeFile(logFilePath, '', 'utf8');
+}
+export async function appendLocatorPickerCrashLog(logFilePath, message) {
+    try {
+        await access(logFilePath);
+    }
+    catch (_a) {
+        return;
+    }
+    await appendFile(logFilePath, `[${new Date().toISOString()}] ${message}\n`, 'utf8');
+}
+export async function ensureLocatorPickerDirectories(repoRoot = process.cwd()) {
+    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) {
+    try {
+        const raw = await readFile(sessionFilePath, 'utf8');
+        return JSON.parse(raw);
+    }
+    catch (_a) {
+        return null;
+    }
+}
+async function enqueueSessionFileOperation(sessionFilePath, operation) {
+    var _a;
+    const previousOperation = (_a = sessionFileOperationQueue.get(sessionFilePath)) !== null && _a !== void 0 ? _a : 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, session) {
+    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, session) {
+    return enqueueSessionFileOperation(sessionFilePath, () => writeLocatorPickerSessionFileImmediate(sessionFilePath, session));
+}
+export async function patchLocatorPickerSessionFile(sessionFilePath, patch) {
+    return enqueueSessionFileOperation(sessionFilePath, async () => {
+        const current = await readLocatorPickerSessionFile(sessionFilePath);
+        if (!current) {
+            return null;
+        }
+        const nextPatch = typeof patch === 'function' ? patch(current) : patch;
+        const nextSession = Object.assign(Object.assign(Object.assign({}, current), nextPatch), { updatedAt: new Date().toISOString() });
+        return writeLocatorPickerSessionFileImmediate(sessionFilePath, nextSession);
+    });
+}

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

@@ -0,0 +1,31 @@
+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/dist/types.js

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,17 @@
+{
+  "name": "@appraise/locator-picker-companion",
+  "private": true,
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": "./dist/index.js",
+    "./launcher": "./dist/launcher.js",
+    "./session-file": "./dist/session-file.js",
+    "./types": "./dist/types.js"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "dev": "node --import tsx ./src/cli.ts"
+  }
+}