latchkey 0.2.0 → 1.0.1

package/dist/scripts/codegen/index.js

@@ -0,0 +1,189 @@
+/**
+ * Codegen module that records browser actions and generates TypeScript code:
+ * - Records user interactions (clicks, fills, navigations, etc.)
+ * - Always generates TypeScript code
+ * - Records all HTTP request metadata to a file
+ * - Includes a custom toolbar with additional buttons
+ *
+ * The session has two phases:
+ * - Pre-login: No recording, requests marked as pre-login
+ * - Post-login: User interactions are recorded, requests marked as post-login
+ */
+import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { chromium } from 'playwright';
+import { CodeGenerator } from './codeGenerator.js';
+import { createInjectedScript } from './injectedScript.js';
+import { RequestMetadataCollector } from './requestMetadataCollector.js';
+// Get the directory of this module
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+// Recordings directory relative to this module (scripts/recordings)
+const RECORDINGS_DIRECTORY = resolve(__dirname, '..', 'recordings');
+export { CodegenError } from './types.js';
+/**
+ * Generate the prompt.txt content for creating a service definition.
+ */
+function generatePromptContent(name) {
+    return `Create a new service definition for ${name} with browser login support.
+
+Typically, in a browser login session, the user will need to log in manually, and then the automation kicks in to generate an API key. The code needs to detect when the login stage has finished, and then use the Playwright API to perform automatic interactions, and finally retrieve the API key.
+
+To help you derive this logic, I have recorded a sample user session:
+
+The metadata of all requests during the session is recorded in scripts/recordings/${name}/requests.json. Each element contains a "phase" field that tells you whether this is before or after login.
+Note that because the phase is derived from the user clicking a button that says "I'm logged in", some requests immediately after logging in may be marked incorrectly as pre-login. Examine the difference between these two sets of data and try to derive the simplest possible criteria. Some good candidates are:
+
+- A request to the original URL with a difference in HTTP status code (the pre-login one will be a redirection, the post-login one will be 200). Note that the post-login request is likely to be marked incorrectly as pre-login because it's the very first request after login. Use the timestamp to figure out if that's the case.
+
+- The presence of some kind of "auth" or "user" header in the request header.
+
+The actions for generating an API key after the user has logged in is recorded in scripts/recordings/${name}/actions.js. For each element, think about how to derive a stable selector that doesn't depend on the user's language. Usually this means using readable IDs or CSS classes, which are unlikely to change. Some elements, such as submit buttons, may already be unique when matched by the type. If everything fails, fall back to using role + label.
+
+Reference other service implementations to understand which patterns we use.
+`;
+}
+/**
+ * Run the codegen which opens a browser with recording enabled.
+ * Injects a custom toolbar and records user actions and HTTP request metadata.
+ *
+ * Creates a scripts/recordings/$name/ directory with:
+ * - actions.js: Recorded user actions
+ * - requests.json: HTTP request metadata
+ * - prompt.txt: Instructions for creating a service definition
+ *
+ * @returns Result containing the API key ancestry if selected by the user
+ */
+export async function runCodegen(options) {
+    const { name, url } = options;
+    // Create recordings directory
+    const recordingsDirectory = join(RECORDINGS_DIRECTORY, name);
+    if (!existsSync(recordingsDirectory)) {
+        mkdirSync(recordingsDirectory, { recursive: true });
+    }
+    const actionsFile = join(recordingsDirectory, 'actions.js');
+    const requestsFile = join(recordingsDirectory, 'requests.json');
+    const promptFile = join(recordingsDirectory, 'prompt.txt');
+    // Write prompt.txt
+    writeFileSync(promptFile, generatePromptContent(name), 'utf-8');
+    const launchOptions = {
+        headless: false,
+    };
+    if (options.executablePath) {
+        launchOptions.executablePath = options.executablePath;
+    }
+    const browser = await chromium.launch(launchOptions);
+    const context = await browser.newContext();
+    const requestCollector = new RequestMetadataCollector(requestsFile);
+    const codeGenerator = new CodeGenerator(actionsFile);
+    // Session state
+    let currentPhase = 'pre-login';
+    let apiKeyAncestry;
+    // Track HTTP requests and responses
+    context.on('response', (response) => {
+        const request = response.request();
+        requestCollector.addRequest(request, response);
+    });
+    context.on('requestfailed', (request) => {
+        requestCollector.addRequest(request, null);
+    });
+    // Inject our combined recorder and toolbar script into every page
+    const injectedScript = createInjectedScript();
+    await context.addInitScript(injectedScript);
+    // Expose function to receive recorded actions from the page
+    // Only records actions during post-login phase
+    await context.exposeFunction('__latchkeyRecordAction', (action) => {
+        // Only record actions during post-login phase
+        if (currentPhase !== 'post-login') {
+            return;
+        }
+        codeGenerator.addAction({
+            type: action.type,
+            ancestry: action.ancestry,
+            value: action.value,
+            key: action.key,
+            url: action.url,
+            timestamp: Date.now(),
+        });
+    });
+    // Expose function to get current phase (called by toolbar)
+    await context.exposeFunction('__latchkeyGetPhase', () => {
+        return currentPhase;
+    });
+    // Expose function called when "I've logged in" button is clicked
+    await context.exposeFunction('__latchkeyTransitionToPostLogin', () => {
+        console.log('[Latchkey] Transitioning to post-login phase');
+        currentPhase = 'post-login';
+        requestCollector.setPhase('post-login');
+    });
+    // Expose function called when API key element is selected
+    await context.exposeFunction('__latchkeyApiKeyElementSelected', (ancestry) => {
+        console.log(`[Latchkey] API key element selected with ${String(ancestry.length)} ancestors`);
+        apiKeyAncestry = ancestry;
+        codeGenerator.setApiKeyAncestry(ancestry);
+    });
+    const page = await context.newPage();
+    // Helper function to inject script after page load (needed because addInitScript
+    // runs before DOM exists, so toolbar won't appear without this)
+    async function injectScriptIfNeeded(targetPage) {
+        try {
+            await targetPage.evaluate(injectedScript);
+        }
+        catch {
+            // Ignore errors (e.g., if page is closed or navigating)
+        }
+    }
+    // Navigate to initial URL
+    codeGenerator.setInitialUrl(url);
+    await page.goto(url);
+    // Inject script after page loads
+    await injectScriptIfNeeded(page);
+    // Re-inject script after navigations
+    page.on('load', () => {
+        void injectScriptIfNeeded(page);
+    });
+    // Track navigations (only during post-login phase)
+    page.on('framenavigated', (frame) => {
+        // Only track main frame navigations during post-login
+        if (frame === page.mainFrame() && currentPhase === 'post-login') {
+            const url = frame.url();
+            // Don't record about:blank
+            if (url && url !== 'about:blank') {
+                codeGenerator.addAction({
+                    type: 'navigate',
+                    url: url,
+                    timestamp: Date.now(),
+                });
+            }
+        }
+    });
+    // Wait for browser to close
+    await new Promise((resolve) => {
+        const cleanup = () => {
+            resolve();
+        };
+        browser.on('disconnected', cleanup);
+        context.on('close', cleanup);
+        page.on('close', cleanup);
+    });
+    // Ensure browser is fully closed
+    try {
+        await browser.close();
+    }
+    catch {
+        // Browser may already be closed, ignore
+    }
+    // Final flush of collected data
+    requestCollector.flush();
+    codeGenerator.flush();
+    console.log(`\nRecording saved to ${recordingsDirectory}/`);
+    console.log(`  - actions.js: Recorded user actions`);
+    console.log(`  - requests.json: HTTP request metadata`);
+    console.log(`  - prompt.txt: Instructions for creating a service definition`);
+    if (apiKeyAncestry) {
+        console.log(`\nAPI key element ancestry captured with ${String(apiKeyAncestry.length)} elements`);
+    }
+    return { apiKeyAncestry };
+}
+//# sourceMappingURL=index.js.map

package/dist/scripts/codegen/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../scripts/codegen/index.ts"],"names":[],"mappings":"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"}

package/dist/scripts/codegen/injectedScript.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Creates the combined script injected into pages.
+ * Contains both the interaction recorder and the toolbar UI.
+ */
+export declare function createInjectedScript(): string;
+//# sourceMappingURL=injectedScript.d.ts.map

package/dist/scripts/codegen/injectedScript.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"injectedScript.d.ts","sourceRoot":"","sources":["../../../scripts/codegen/injectedScript.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,wBAAgB,oBAAoB,IAAI,MAAM,CA2oB7C"}