latchkey 0.2.0 → 1.0.1

package/README.md

@@ -1,10 +1,14 @@
 # Latchkey
 
-Turn browser logins into usable credentials for local agents.
+Inject API credentials into local agent requests.
 
 ## Quick example
 
 ```
+# User stores the credentials.
+latchkey auth set slack -H "Authorization: Bearer xoxb-your-token"
+
+# Agent makes http calls.
 latchkey curl -X POST 'https://slack.com/api/conversations.create' \
   -H 'Content-Type: application/json' \
   -d '{"name":"something-urgent"}'
@@ -12,52 +16,64 @@ latchkey curl -X POST 'https://slack.com/api/conversations.create' \
 
 ## Overview
 
-Latchkey is a command-line tool that injects credentials to curl requests to known public APIs.
+Latchkey is a command-line tool that injects credentials into curl
+requests to known public APIs.
 
-- `latchkey services`
-	- Get a list of known and supported third-party services (Slack, Google Workspace, Linear, GitHub, etc.).
+- `latchkey services list`
+	- List supported third-party services (Slack, Google Workspace, Linear, GitHub, etc.).
 - `latchkey curl <arguments>`
 	- Automatically inject credentials to your otherwise standard curl calls to public APIs.
-	- (The first time you access a service, a browser pop-up with a login screen appears.)
-
-Latchkey is primarily designed for AI agents. By invoking Latchkey, agents can
-prompt the user to authenticate when needed, then continue interacting with
-third-party APIs using standard curl syntax - no custom integrations or embedded
-credentials required.
-
-Unlike OAuth-based flows or typical MCP-style integrations, Latchkey does not
-introduce an intermediary between the agent and the service. Requests are made
-directly on the user’s behalf, which enables greater flexibility at the cost of
-formal delegation: agents authenticate as the user.
-
-If a service you need isn’t supported yet, contributions are welcome. Adding
-support typically involves writing a small browser automation class that
-extracts API credentials after login. See the [development docs](docs/development.md)
-for details.
+	- Credentials must already exist (see below).
+- `latchkey auth set <service_name> <curl_arguments>`
+	- Manually store credentials for a service as arbitrary curl arguments.
+- `latchkey auth browser <service_name>`
+	- Open a browser login pop-up window and store the resulting API credentials.
+    - This also allows agents to prompt users for credentials.
+    - Only some services support this option.
+
+Latchkey is primarily designed for AI agents. By invoking
+Latchkey, agents can prompt the user to authenticate when needed,
+then continue interacting with third-party APIs using standard
+curl syntax - no custom integrations or embedded credentials
+required.
+
+Unlike OAuth-based flows or typical MCP-style integrations,
+Latchkey does not introduce an intermediary between the agent
+and the service. When `browser` is used, requests are made
+directly on the user’s behalf, which enables greater flexibility
+at the cost of formal delegation: agents authenticate as the
+user.
+
+If a service you need isn’t supported yet, contributions are welcome!
+See the [development docs](docs/development.md) for details.
 
 ## Installation
 
 ### Prerequisites
 
 - `curl`, `node` and `npm` need to be present on your system in reasonably recent versions.
-- The browser requires a graphical environment.
+- The `latchkey auth browser` subcommand requires a graphical environment.
 
 ### Steps
 
 ```
 npm install -g latchkey
+
+# Optionally, if you intend to use `latchkey auth browser`:
 latchkey ensure-browser
 ```
 
-The `ensure-browser` command discovers and configures a browser for Latchkey to use. It searches for Chrome, Chromium, or Edge on your system. If none is found, it downloads Chromium via Playwright.
-
-**nvm users**: Global packages are per node version. If you switch versions, reinstall with `npm install -g latchkey`
+The `ensure-browser` command discovers and configures a browser
+for Latchkey to use. It searches for Chrome, Chromium, or Edge
+on your system. If none is found, it downloads Chromium via
+Playwright.
 
 ## Integrations
 
-Warning: giving AI agents access to your API credentials is potentially
-dangerous. They will be able to perform most of the actions you can. Only do this if
-you're willing to accept the risks.
+Warning: giving AI agents access to your API credentials is
+potentially dangerous, especially when using the `auth browser`
+feature. They will be able to perform most of the actions you
+can. Only do this if you're willing to accept the risks.
 
 
 ### OpenCode
@@ -80,7 +96,9 @@ latchkey skill-md > ~/.codex/skills/latchkey/SKILL.md
 
 ### Passepartout
 
-Check out our [Passepartout demo app](https://github.com/imbue-ai/passepartout) for an idea of how to build AI assistants for non-technical users on top of Latchkey.
+Check out our [Passepartout demo app](https://github.com/imbue-ai/passepartout)
+for an idea of how to build AI assistants for non-technical
+users on top of Latchkey.
 
 
 ## Demo
@@ -98,31 +116,40 @@ latchkey curl -X POST 'https://slack.com/api/conversations.create' \
   -d '{"name":"something-urgent"}'
 ```
 
-Notice that `-H 'Authorization: Bearer ...'` is absent. This is because Latchkey:
+Notice that `-H 'Authorization: Bearer ...'` is absent. This is
+because Latchkey injects stored credentials automatically. To
+set up credentials for a service (Slack in this example), run:
 
-- Opens the browser with a login screen.
-- After the user logs in, Latchkey extracts the necessary API credentials from the browser session.
-- The browser is closed, the credentials are injected into the arguments, and `curl` is invoked.
-- The credentials are stored so that they can be reused the next time.
+```
+latchkey auth browser slack
+```
+
+This opens the browser with a login screen. After you log in, Latchkey extracts
+the necessary API credentials from the browser session, closes the browser, and
+stores the credentials so that they can be reused.
 
-Otherwise, `latchkey curl` passes your arguments straight
-through to `curl` so you can use the same interface you are used
-to. The return code, stdin and stdout are passed back from curl
-to the caller of `latchkey`.
+Alternatively, you can provide credentials manually:
+
+```
+latchkey auth set slack -H "Authorization: Bearer xoxb-your-token"
+```
+
+`latchkey curl` passes your arguments straight through to `curl`
+so you can use the same interface you are used to. The return
+code, stdout and stderr are passed back from curl to the caller
+of `latchkey`.
 
 ### Remembering API credentials
 
-Your API credentials and browser state are stored by default
-under `~/.latchkey`. When a functioning keyring is detected
-(which is the case on most systems), the data is properly
-encrypted.
+Your API credentials and browser state are encrypted and stored
+by default under `~/.latchkey`.
 
 
 ### Inspecting the status of stored credentials
 
-Calling `latchkey status <service_name>` will give you
-information about the status of remembered credentials for the
-given service. Possible results are:
+Calling `latchkey services info <service_name>` will show information
+about the service, including the credentials status. The
+credentials status line will show one of:
 
 - `missing`
 - `invalid`
@@ -132,30 +159,42 @@ given service. Possible results are:
 
 Remembered API credentials can expire. The caller of `latchkey
 curl` will typically notice this because the calls will start returning
-HTTP 401 or 403. To verify that, first call `latchkey status`, e.g.:
+HTTP 401 or 403. To verify that, first call `latchkey services info`, e.g.:
+
+```
+latchkey services info discord
+```
+
+If the credentials status is `invalid`, it means the Unauthorized/Forbidden
+responses are caused by invalid or expired credentials rather than insufficient
+permissions. In that case, log in again:
 
 ```
-latchkey status discord
+latchkey auth browser discord
 ```
 
-If the result is `invalid` , meaning the Unauthorized/Forbidden responses are
-caused by invalid or expired credentials rather than insufficient permissions,
-force a new login in the next `latchkey curl` call by clearing the remembered
-API credentials for the service in question, e.g.:
+Or alternatively:
 
 ```
-latchkey clear discord
+latchkey auth set discord -H "Authorization: ..."
 ```
 
-The next `latchkey curl` call will then trigger a new login flow.
 
-To clear all stored data (both the credentials store and browser
-state file), run:
+### Clearing credentials and logins
+
+In case you want to remove stored API credentials, use the `auth clear` subcommand.
 
 ```
-latchkey clear
+latchkey auth clear discord
 ```
 
+To clear all stored data (both the credential store and browser state file), run:
+
+```
+latchkey auth clear
+```
+
+
 ### Advanced configuration
 
 You can set these environment variables to override certain
@@ -166,17 +205,19 @@ containing stored API credentials
 - `LATCHKEY_BROWSER_STATE`: path to the (typically encrypted) file
 containing the state (cookies, local storage, etc.) of
 the browser used for the login popup
-- `LATCHKEY_CURL_PATH`: path to the curl binary
+- `LATCHKEY_CURL`: path to the curl binary
 - `LATCHKEY_CONFIG`: path to the configuration file
 (defaults to `~/.latchkey/config.json`)
 - `LATCHKEY_KEYRING_SERVICE_NAME`, `LATCHKEY_KEYRING_ACCOUNT_NAME`: identifiers that are used to store the encryption password in your keyring
+- `LATCHKEY_ENCRYPTION_KEY`: override the encryption key, e.g. when a keyring is not available. Example: `export LATCHKEY_ENCRYPTION_KEY="$(openssl rand -base64 32)"`
+- `LATCHKEY_DISABLE_BROWSER`: when set (to any non-empty value), disables the browser login flow; commands that would trigger a browser login (`auth browser`, `auth browser-prepare`) will fail with an error instead
 
 
 ## Disclaimers
 
 - This is still a work in progress.
 - Latchkey has been created with the help of AI-assisted coding tools with careful human curation.
-- Invoking `latchkey curl ...` can sometimes have side effects in the form of
+- Invoking `latchkey auth browser ...` can sometimes have side effects in the form of
   new API keys being created in your accounts (through browser automation).
 - Using agents for automated access may be prohibited by some services' ToS.
 - We reserve the right to change the license of future releases of Latchkey.

package/dist/integrations/SKILL.md

@@ -1,26 +1,26 @@
 ---
 name: latchkey
-description: Interact with third-party services (Slack, Google Workspace, Dropbox, GitHub, Linear...) on user's behalf using their public APIs.
-compatibility: Requires node.js, curl, latchkey (npm install -g latchkey) and a desktop/GUI environment.
+description: Interact with third-party services (Slack, Google Workspace, Dropbox, GitHub, Linear...) on the user's behalf using their public APIs.
+compatibility: Requires node.js, curl and latchkey (npm install -g latchkey). A desktop/GUI environment is required for the browser functionality.
 ---
 
 # Latchkey
 
 ## Instructions
 
-Latchkey is a CLI tool that automatically injects credentials into curl commands for supported public APIs. Instead of manually managing API tokens, latchkey opens a browser for login, extracts credentials from the session, and injects them into your curl requests.
+Latchkey is a CLI tool that automatically injects credentials into curl commands for supported public APIs. Credentials (mostly API tokens) can be either manually managed or, for some services, Latchkey can open a browser login pop-up window and extract API credentials from the session.
 
-Use this skill when the user asks you to work with third-party services like Slack, Discord, Dropbox, Github, Linear and others on their behalf.
+Use this skill when the user asks you to work with third-party services like Slack, Discord, Dropbox, GitHub, Linear and others on their behalf.
 
 Usage:
 
 1. **Use `latchkey curl`** instead of regular `curl` for supported services.
-2. **Use `latchkey info <service_name>`** to get developer notes about a specific service (API docs links, special requirements, etc.).
-3. **Look for the newest documentation of the desired public API online.** Avoid bot-only endpoints if such a distinction exists.
-4. **Pass through all regular curl arguments** - latchkey is a transparent wrapper.
-5. **Use `latchkey status <service_name>`** when you notice potentially expired credentials.
-6. When the status is `invalid`, **force a new login by calling `latchkey clear <service_name>`**, then retry the curl command.
-7. **Do not force a new login if the status is `valid`** - the user might just not have the necessary permissions.
+2. **Pass through all regular curl arguments** - latchkey is a transparent wrapper.
+3. **Use `latchkey services list`** to get a list of supported services.
+4. **Use `latchkey services info <service_name>`** to get information about a specific service (auth options, credentials status, API docs links, special requirements, etc.).
+5. **If necessary, get or renew credentials first.** Run `latchkey auth browser <service_name>` to open a browser login pop-up window if supported.
+6. **Look for the newest documentation of the desired public API online.** If using the `browser` auth command, avoid bot-only endpoints.
+7. **Do not initiate a new login if the credentials status is `valid`** - the user might just not have the necessary permissions for the action you're trying to do.
 
 
 ## Examples
@@ -44,28 +44,34 @@ latchkey curl -X POST 'https://slack.com/api/conversations.create' \
 latchkey curl 'https://discord.com/api/v10/users/@me'
 ```
 
-### Clear expired credentials and force a new login to Discord
+### Detect expired credentials and force a new login to Discord
 ```bash
-latchkey status discord  # Returns "invalid"
-latchkey clear discord
+latchkey services info discord  # Check the "credentialStatus" field - shows "invalid"
+latchkey auth browser discord
 latchkey curl 'https://discord.com/api/v10/users/@me'
 ```
 
-Only do this when you notice that your previous call ended up not being authenticated (HTTP 401 or 403). The next `latchkey curl` call will trigger a new login flow.
+Only do this when you notice that your previous call ended up not being authenticated (HTTP 401 or 403).
 
-### List supported services
+### List available services
 ```bash
-latchkey services
+latchkey services list
 ```
 
+Lists all services that latchkey knows about.
+
 ### Get service-specific info
 ```bash
-latchkey info slack
+latchkey services info slack
 ```
 
-Returns developer notes about the service, including API documentation links and any special requirements.
+Returns auth options, credentials status, and developer notes
+about the service. If `browser` is not present in the
+`authOptions` field, the service requires the user to directly
+set API credentials via `latchkey auth set` before making
+requests.
 
 ## Notes
 
 - All curl arguments are passed through unchanged
-- Return codes, stdin, and stdout are passed back from curl
+- Return code, stdout and stderr are passed back from curl

package/dist/package.json

@@ -1,6 +1,6 @@
 {
     "name": "latchkey",
-    "version": "0.2.0",
+    "version": "1.0.1",
     "description": "A CLI tool that injects API credentials into curl requests for known third-party services",
     "author": "Imbue <hynek@imbue.com>",
     "repository": {
@@ -52,7 +52,7 @@
     "dependencies": {
         "@napi-rs/keyring": "^1.2.0",
         "commander": "^12.0.0",
-        "playwright": "^1.49.1",
+        "playwright": "^1.58.2",
         "zod": "^3.22.0"
     },
     "devDependencies": {

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

@@ -0,0 +1,27 @@
+/**
+ * Generates TypeScript code from recorded actions.
+ * Uses page.getByRole where possible and outputs element ancestry for AI post-processing.
+ */
+import type { ElementInfo, RecordedAction } from './types.js';
+export declare class CodeGenerator {
+    private readonly actions;
+    private readonly outputPath;
+    private actionCounter;
+    private initialUrl;
+    private apiKeyAncestry;
+    constructor(outputPath: string);
+    setInitialUrl(url: string): void;
+    addAction(action: RecordedAction): void;
+    setApiKeyAncestry(ancestry: ElementInfo[]): void;
+    private escapeString;
+    private generateGetByRole;
+    private generateGetByPlaceholder;
+    private generateGetByLabel;
+    private generateLocator;
+    private formatElementInfo;
+    private formatAncestryComments;
+    private generateActionCode;
+    generateCode(): string;
+    flush(): void;
+}
+//# sourceMappingURL=codeGenerator.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"codeGenerator.d.ts","sourceRoot":"","sources":["../../../scripts/codegen/codeGenerator.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,KAAK,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAE9D,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAwB;IAChD,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,aAAa,CAAK;IAC1B,OAAO,CAAC,UAAU,CAAqB;IACvC,OAAO,CAAC,cAAc,CAA4B;gBAEtC,UAAU,EAAE,MAAM;IAI9B,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAKhC,SAAS,CAAC,MAAM,EAAE,cAAc,GAAG,IAAI;IAKvC,iBAAiB,CAAC,QAAQ,EAAE,WAAW,EAAE,GAAG,IAAI;IAKhD,OAAO,CAAC,YAAY;IAQpB,OAAO,CAAC,iBAAiB;IAYzB,OAAO,CAAC,wBAAwB;IAKhC,OAAO,CAAC,kBAAkB;IAO1B,OAAO,CAAC,eAAe;IA8BvB,OAAO,CAAC,iBAAiB;IA4BzB,OAAO,CAAC,sBAAsB;IAkB9B,OAAO,CAAC,kBAAkB;IAuD1B,YAAY,IAAI,MAAM;IAwDtB,KAAK,IAAI,IAAI;CAGd"}

package/dist/scripts/codegen/codeGenerator.js

@@ -0,0 +1,220 @@
+/**
+ * Generates TypeScript code from recorded actions.
+ * Uses page.getByRole where possible and outputs element ancestry for AI post-processing.
+ */
+import { writeFileSync } from 'node:fs';
+export class CodeGenerator {
+    actions = [];
+    outputPath;
+    actionCounter = 0;
+    initialUrl;
+    apiKeyAncestry;
+    constructor(outputPath) {
+        this.outputPath = outputPath;
+    }
+    setInitialUrl(url) {
+        this.initialUrl = url;
+        this.flush();
+    }
+    addAction(action) {
+        this.actions.push(action);
+        this.flush();
+    }
+    setApiKeyAncestry(ancestry) {
+        this.apiKeyAncestry = ancestry;
+        this.flush();
+    }
+    escapeString(str) {
+        return str
+            .replace(/\\/g, '\\\\')
+            .replace(/'/g, "\\'")
+            .replace(/\n/g, '\\n')
+            .replace(/\r/g, '\\r');
+    }
+    generateGetByRole(element) {
+        if (!element.role)
+            return null;
+        const role = element.role;
+        const name = element.accessibleName;
+        if (name) {
+            return `page.getByRole('${role}', { name: '${this.escapeString(name)}' })`;
+        }
+        return `page.getByRole('${role}')`;
+    }
+    generateGetByPlaceholder(element) {
+        if (!element.placeholder)
+            return null;
+        return `page.getByPlaceholder('${this.escapeString(element.placeholder)}')`;
+    }
+    generateGetByLabel(element) {
+        if (!element.accessibleName)
+            return null;
+        if (element.tag !== 'input' && element.tag !== 'textarea' && element.tag !== 'select')
+            return null;
+        return `page.getByLabel('${this.escapeString(element.accessibleName)}')`;
+    }
+    generateLocator(target) {
+        // Try getByRole first (Playwright best practice)
+        let locator = this.generateGetByRole(target);
+        if (locator) {
+            return { locator, strategy: 'getByRole' };
+        }
+        // Try getByPlaceholder
+        locator = this.generateGetByPlaceholder(target);
+        if (locator) {
+            return { locator, strategy: 'getByPlaceholder' };
+        }
+        // Try getByLabel
+        locator = this.generateGetByLabel(target);
+        if (locator) {
+            return { locator, strategy: 'getByLabel' };
+        }
+        // Fallback to locator with a simple selector
+        if (target.id) {
+            return { locator: `page.locator('#${target.id}')`, strategy: 'id' };
+        }
+        if (target.className) {
+            const firstClass = target.className.split(/\s+/)[0] ?? '';
+            return { locator: `page.locator('.${firstClass}')`, strategy: 'class' };
+        }
+        return { locator: `page.locator('${target.tag}')`, strategy: 'tag' };
+    }
+    formatElementInfo(element) {
+        const parts = [`tag: ${element.tag}`];
+        if (element.id) {
+            parts.push(`id: "${element.id}"`);
+        }
+        if (element.className) {
+            parts.push(`class: "${element.className}"`);
+        }
+        if (element.name) {
+            parts.push(`name: "${element.name}"`);
+        }
+        if (element.role) {
+            parts.push(`role: ${element.role}`);
+        }
+        if (element.accessibleName) {
+            parts.push(`accessibleName: "${this.escapeString(element.accessibleName)}"`);
+        }
+        if (element.inputType) {
+            parts.push(`type: ${element.inputType}`);
+        }
+        if (element.placeholder) {
+            parts.push(`placeholder: "${this.escapeString(element.placeholder)}"`);
+        }
+        return `{ ${parts.join(', ')} }`;
+    }
+    formatAncestryComments(ancestry) {
+        const lines = [];
+        lines.push(`  // Element ancestry (root -> target):`);
+        // Output ancestry in reverse order (root first, target last)
+        for (let i = ancestry.length - 1; i >= 0; i--) {
+            const element = ancestry[i];
+            if (element) {
+                const depth = ancestry.length - 1 - i;
+                const indent = '  '.repeat(depth);
+                const marker = i === 0 ? ' [TARGET]' : '';
+                lines.push(`  //   ${indent}${this.formatElementInfo(element)}${marker}`);
+            }
+        }
+        return lines;
+    }
+    generateActionCode(action) {
+        // Navigation doesn't need ancestry
+        if (action.type === 'navigate') {
+            return `  await page.goto('${this.escapeString(action.url ?? '')}');`;
+        }
+        const ancestry = action.ancestry ?? [];
+        const target = ancestry[0];
+        if (!target) {
+            return `  // Action ${action.type} with no element info`;
+        }
+        this.actionCounter++;
+        const actionId = this.actionCounter;
+        // Determine the action method
+        let actionMethod;
+        switch (action.type) {
+            case 'click':
+                actionMethod = '.click()';
+                break;
+            case 'fill':
+                actionMethod = `.fill('${this.escapeString(action.value ?? '')}')`;
+                break;
+            case 'press':
+                actionMethod = `.press('${this.escapeString(action.key ?? '')}')`;
+                break;
+            case 'select':
+                actionMethod = `.selectOption('${this.escapeString(action.value ?? '')}')`;
+                break;
+            case 'check':
+                actionMethod = '.check()';
+                break;
+            case 'uncheck':
+                actionMethod = '.uncheck()';
+                break;
+            default: {
+                const unknownType = action.type;
+                return `  // Unknown action: ${String(unknownType)}`;
+            }
+        }
+        const { locator: primaryLocator, strategy: locatorType } = this.generateLocator(target);
+        // Build the output with ancestry information (root -> target order)
+        const lines = [];
+        lines.push(`  // ===== ACTION ${String(actionId)}: ${action.type} =====`);
+        lines.push(...this.formatAncestryComments(ancestry));
+        lines.push(`  // Locator strategy: ${locatorType}`);
+        lines.push(`  await ${primaryLocator}${actionMethod};`);
+        lines.push('');
+        return lines.join('\n');
+    }
+    generateCode() {
+        // Reset counter for consistent output
+        this.actionCounter = 0;
+        // Generate initial URL navigation if set
+        const initialUrlCode = this.initialUrl
+            ? `  await page.goto('${this.escapeString(this.initialUrl)}');\n\n`
+            : '';
+        const header = `// Generated by Latchkey Codegen
+// Each action includes element ancestry for AI post-processing to synthesize optimal selectors.
+// The active locator uses page.getByRole where possible (Playwright best practice).
+
+const { chromium } = require('playwright');
+
+(async () => {
+  const browser = await chromium.launch({ headless: false });
+  const context = await browser.newContext();
+  const page = await context.newPage();
+
+${initialUrlCode}`;
+        const footer = `  // ---------------------
+  await context.close();
+  await browser.close();
+})();
+`;
+        const actionLines = this.actions.map((action) => this.generateActionCode(action));
+        // Generate API key extraction code if ancestry was set
+        let apiKeyCode = '';
+        if (this.apiKeyAncestry && this.apiKeyAncestry.length > 0) {
+            const ancestry = this.apiKeyAncestry;
+            const target = ancestry[0];
+            if (target) {
+                const { locator: primaryLocator, strategy: locatorType } = this.generateLocator(target);
+                // Build ancestry information
+                const ancestryLines = [];
+                ancestryLines.push(`  // ===== API KEY EXTRACTION =====`);
+                ancestryLines.push(...this.formatAncestryComments(ancestry));
+                ancestryLines.push(`  // Locator strategy: ${locatorType}`);
+                ancestryLines.push(`  const apiKey = await ${primaryLocator}.textContent();`);
+                ancestryLines.push(`  console.log('API Key:', apiKey);`);
+                ancestryLines.push(`  // ===== END API KEY EXTRACTION =====`);
+                ancestryLines.push('');
+                apiKeyCode = '\n' + ancestryLines.join('\n') + '\n';
+            }
+        }
+        return header + actionLines.join('\n') + apiKeyCode + footer;
+    }
+    flush() {
+        writeFileSync(this.outputPath, this.generateCode(), 'utf-8');
+    }
+}
+//# sourceMappingURL=codeGenerator.js.map

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

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

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

@@ -0,0 +1,27 @@
+/**
+ * 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 type { CodegenOptions, CodegenResult } from './types.js';
+export type { CodegenOptions, CodegenResult, ElementInfo, RecordedAction, RecordingPhase, RequestMetadata, } from './types.js';
+export { CodegenError } from './types.js';
+/**
+ * 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 declare function runCodegen(options: CodegenOptions): Promise<CodegenResult>;
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../scripts/codegen/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAWH,OAAO,KAAK,EACV,cAAc,EACd,aAAa,EAId,MAAM,YAAY,CAAC;AAUpB,YAAY,EACV,cAAc,EACd,aAAa,EACb,WAAW,EACX,cAAc,EACd,cAAc,EACd,eAAe,GAChB,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAyB1C;;;;;;;;;;GAUG;AACH,wBAAsB,UAAU,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,aAAa,CAAC,CAuKhF"}