@mearl/provider 2.13.0

package/README.md

@@ -0,0 +1,130 @@
+# @mearl/provider
+
+External browser providers use this package to register themselves with Mearl, publish their
+available browsers, and handle Mearl browser actions over a local socket.
+
+## Installation
+
+Provider packages should declare `@mearl/provider` as a runtime dependency:
+
+```bash
+pnpm add @mearl/provider
+```
+
+Provider implementations import the package root. The `/host` and `/runtime` subpaths are for
+Mearl's setup, discovery, and routing processes rather than Provider business code.
+
+## Provider lifecycle
+
+1. The provider package declares its protocol entry in `package.json#mearl.provider`.
+2. `npx @mearl/setup provider install <package>` installs the package and registers its metadata.
+3. `mearl browser_list` starts an `on-demand` provider when necessary.
+4. The provider starts `createProviderServer()` and publishes browsers with `updateBrowsers()`.
+5. Mearl reads browser discovery from the shared registry and routes each supported browser action
+   to the provider socket with the provider-local browser id.
+6. The provider removes its live browser records when it stops.
+
+Mearl discovers only explicit manifests in `~/.mearl/providers/installed`. It does not scan or
+execute arbitrary global packages.
+
+## Package metadata
+
+Provider packages do not need a user-facing binary or lifecycle scripts. Their `package.json`
+declares an internal Node.js entry owned by the package:
+
+```json
+{
+  "name": "@example/mearl-provider-device",
+  "version": "1.0.0",
+  "type": "module",
+  "mearl": {
+    "provider": {
+      "providerId": "example-device",
+      "name": "Example device provider",
+      "protocolVersion": 1,
+      "entry": "./dist/runtime.js",
+      "browserType": {
+        "name": "Device",
+        "parameters": [
+          { "key": "code", "label": "Pairing code", "placeholder": "Generated by default" }
+        ]
+      }
+    }
+  }
+}
+```
+
+The entry must be a relative path to a file inside the installed package. Mearl launches registered
+providers on demand with the current Node.js runtime; packages cannot register arbitrary commands,
+arguments, working directories, or environment overrides.
+
+## Minimal runtime
+
+```ts
+import { createProviderServer } from '@mearl/provider';
+
+const server = createProviderServer({
+  descriptor: { providerId: 'example', name: 'Example provider', version: '1.0.0' },
+  handleAction: async ({ browserId, action, data }) => {
+    // Translate Mearl actions to the external browser-control backend.
+    return { browserId, action, data };
+  },
+  createBrowser: async parameters => createDevice(parameters),
+  deleteBrowser: async browserId => deleteDevice(browserId),
+});
+
+await server.start();
+server.updateBrowsers([
+  {
+    browserId: 'device-1',
+    name: 'Example device',
+    capabilities: {
+      actions: ['tab_list', 'page_snapshot', 'page_click'],
+      screenshot: 'none',
+    },
+  },
+]);
+```
+
+`createBrowser` returns the Provider-local `browserId`, display `name`, and initial `status`.
+When the initial status is `pairing`, it also returns the same `pairing` metadata published during
+discovery, so `browser_launch` callers can present the QR URL without an extra `browser_list` call.
+Mearl converts that local id into the same global id shape returned by `browser_list`.
+
+A device provider can remain discoverable before its hardware is online by publishing a pairing
+browser. Mearl keeps it out of implicit action routing and can render its QR URL:
+
+```ts
+const pairing = {
+  kind: 'qr' as const,
+  url: 'https://example.test/pair?id=device-pairing',
+  code: 'device-pairing',
+};
+
+const createBrowser = async () => ({
+  browserId: 'device-pairing',
+  name: 'Pair a device',
+  status: 'pairing' as const,
+  pairing,
+});
+
+server.updateBrowsers([
+  {
+    browserId: 'device-pairing',
+    name: 'Pair a device',
+    status: 'pairing',
+    pairing,
+    capabilities: { actions: [], screenshot: 'none' },
+  },
+]);
+```
+
+Screenshot capability is declared as `native`, `reconstructed`, or `none`, so callers can retain
+the image while distinguishing real pixels from an HTML reconstruction.
+
+Capabilities stay in Mearl's internal routing registry and are returned by `get_versions` for a
+selected provider browser. They are intentionally omitted from `browser_list`; use
+`mearl check --browser <id>` to inspect them. The package accepts only declared browser-targeted Mearl
+actions. Mearl owns discovery, while `browser_launch` and `browser_close` are routed to the
+Provider's `createBrowser` and `deleteBrowser` handlers. Requests for undeclared actions are
+rejected before reaching the provider.

package/dist/generated-provider-actions.d.ts

@@ -0,0 +1,3 @@
+export declare const PROVIDER_ACTIONS: readonly ["tab_checkpoint", "capture_checkpoint", "get_requests", "get_logs", "get_events", "get_api_schema", "set_mock", "get_mocks", "set_rule", "get_rules", "send_request", "send_mtop_request", "tdbank_account", "browser_release", "page_screenshot", "page_selected_element", "tab_open", "tab_close", "tab_list", "page_click", "page_drag", "page_type", "page_scroll", "page_hover", "page_eval", "page_snapshot", "page_press", "page_wait", "page_navigate", "page_upload", "page_frames", "set_device_emulation", "set_app_profile", "set_timezone", "get_cookie", "set_cookie", "record_start", "record_stop", "request_domain_permission", "get_user_info", "run_actions"];
+export type ProviderAction = (typeof PROVIDER_ACTIONS)[number];
+export declare function isProviderAction(value: unknown): value is ProviderAction;

package/dist/generated-provider-actions.js

@@ -0,0 +1,49 @@
+// Generated by scripts/generate-provider-actions.mjs.
+// Do not edit directly; update browser-core/src/browserActionProtocol.ts.
+export const PROVIDER_ACTIONS = [
+    'tab_checkpoint',
+    'capture_checkpoint',
+    'get_requests',
+    'get_logs',
+    'get_events',
+    'get_api_schema',
+    'set_mock',
+    'get_mocks',
+    'set_rule',
+    'get_rules',
+    'send_request',
+    'send_mtop_request',
+    'tdbank_account',
+    'browser_release',
+    'page_screenshot',
+    'page_selected_element',
+    'tab_open',
+    'tab_close',
+    'tab_list',
+    'page_click',
+    'page_drag',
+    'page_type',
+    'page_scroll',
+    'page_hover',
+    'page_eval',
+    'page_snapshot',
+    'page_press',
+    'page_wait',
+    'page_navigate',
+    'page_upload',
+    'page_frames',
+    'set_device_emulation',
+    'set_app_profile',
+    'set_timezone',
+    'get_cookie',
+    'set_cookie',
+    'record_start',
+    'record_stop',
+    'request_domain_permission',
+    'get_user_info',
+    'run_actions',
+];
+const providerActionSet = new Set(PROVIDER_ACTIONS);
+export function isProviderAction(value) {
+    return typeof value === 'string' && providerActionSet.has(value);
+}

package/dist/host.d.ts

@@ -0,0 +1,2 @@
+export { listInstalledProviders, registerProviderPackage, stopProvider, uninstallProvider, } from './registry.js';
+export type { InstalledProviderManifest, ProviderPackageMetadata } from './types.js';

package/dist/host.js

@@ -0,0 +1 @@
+export { listInstalledProviders, registerProviderPackage, stopProvider, uninstallProvider, } from './registry.js';

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export * from './types.js';
+export { PROVIDER_ACTIONS, isProviderAction } from './generated-provider-actions.js';
+export { providerDataDir } from './registry.js';
+export { createProviderServer } from './server.js';

package/dist/index.js

@@ -0,0 +1,4 @@
+export * from './types.js';
+export { PROVIDER_ACTIONS, isProviderAction } from './generated-provider-actions.js';
+export { providerDataDir } from './registry.js';
+export { createProviderServer } from './server.js';

package/dist/launcher.d.ts

@@ -0,0 +1,3 @@
+export declare const PROVIDER_LOGS_SUBDIR = "providers/logs";
+/** Start explicitly installed on-demand providers before browser discovery. */
+export declare function ensureInstalledProvidersRunning(): Promise<string[]>;

package/dist/launcher.js

@@ -0,0 +1,109 @@
+import { spawn } from 'node:child_process';
+import { randomUUID } from 'node:crypto';
+import { closeSync, existsSync, mkdirSync, openSync } from 'node:fs';
+import { join } from 'node:path';
+import { hashKey, keyedDir, rotateLogIfNeeded } from '@mearl/daemon-core';
+import { PROVIDER_START_TOKEN_ENV, claimProviderStart, listInstalledProviders, listLiveProviders, readLiveProvider, readProviderStart, releaseProviderStart, transferProviderStart, validateInstalledProviderManifest, } from './registry.js';
+export const PROVIDER_LOGS_SUBDIR = 'providers/logs';
+function providerLogFile(providerId) {
+    const hash = hashKey(providerId);
+    return join(keyedDir(PROVIDER_LOGS_SUBDIR), `${hash}.log`);
+}
+function liveProviderIds() {
+    return new Set(listLiveProviders().map(record => record.providerId));
+}
+function delay(ms) {
+    return new Promise(resolve => setTimeout(resolve, ms));
+}
+async function spawnProvider(manifest, logFile, startToken) {
+    mkdirSync(keyedDir(PROVIDER_LOGS_SUBDIR), { recursive: true, mode: 0o700 });
+    rotateLogIfNeeded(logFile);
+    const output = openSync(logFile, 'a');
+    try {
+        return await new Promise((resolve, reject) => {
+            const child = spawn(process.execPath, [manifest.entryPath], {
+                cwd: manifest.packageRoot,
+                env: {
+                    ...process.env,
+                    [PROVIDER_START_TOKEN_ENV]: startToken,
+                },
+                detached: true,
+                stdio: ['ignore', output, output],
+                windowsHide: true,
+            });
+            child.once('error', reject);
+            child.once('spawn', () => {
+                child.removeAllListeners('error');
+                child.on('error', () => { });
+                child.unref();
+                if (child.pid)
+                    resolve(child.pid);
+                else
+                    reject(new Error('spawned process has no pid'));
+            });
+        });
+    }
+    finally {
+        closeSync(output);
+    }
+}
+/** Start explicitly installed on-demand providers before browser discovery. */
+export async function ensureInstalledProvidersRunning() {
+    const warnings = [];
+    const installed = listInstalledProviders();
+    const live = liveProviderIds();
+    const starting = new Map();
+    for (const manifest of installed) {
+        if (live.has(manifest.providerId))
+            continue;
+        const invalid = validateInstalledProviderManifest(manifest);
+        if (invalid) {
+            warnings.push(`provider ${manifest.providerId || '(unknown)'}: ${invalid}`);
+            continue;
+        }
+        const startToken = randomUUID();
+        if (!claimProviderStart(manifest.providerId, startToken)) {
+            if (readLiveProvider(manifest.providerId))
+                continue;
+            if (readProviderStart(manifest.providerId))
+                starting.set(manifest.providerId, null);
+            else
+                warnings.push(`provider ${manifest.providerId}: failed to acquire startup ownership`);
+            continue;
+        }
+        if (readLiveProvider(manifest.providerId)) {
+            releaseProviderStart(manifest.providerId, startToken);
+            continue;
+        }
+        const logFile = providerLogFile(manifest.providerId);
+        try {
+            const childPid = await spawnProvider(manifest, logFile, startToken);
+            transferProviderStart(manifest.providerId, startToken, childPid);
+            starting.set(manifest.providerId, startToken);
+        }
+        catch (error) {
+            releaseProviderStart(manifest.providerId, startToken);
+            warnings.push(`provider ${manifest.providerId}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    if (starting.size === 0)
+        return warnings;
+    const deadline = Date.now() + 2_000;
+    let remaining = [...starting.keys()];
+    while (remaining.length > 0 && Date.now() < deadline) {
+        await delay(100);
+        const current = liveProviderIds();
+        remaining = remaining.filter(providerId => !current.has(providerId));
+    }
+    for (const [providerId, token] of starting) {
+        if (!remaining.includes(providerId) && token)
+            releaseProviderStart(providerId, token);
+    }
+    for (const providerId of remaining) {
+        const logFile = providerLogFile(providerId);
+        warnings.push(`provider ${providerId}: did not become ready within 2s${existsSync(logFile) ? `; see ${logFile}` : ''}`);
+    }
+    // A ready provider may still be publishing its first browser inventory.
+    await delay(100);
+    return warnings;
+}

package/dist/registry.d.ts

@@ -0,0 +1,85 @@
+import { type DaemonRecord } from '@mearl/daemon-core';
+import { type InstalledProviderManifest, type ProviderBrowser, type ProviderDescriptor } from './types.js';
+export declare const INSTALLED_PROVIDERS_SUBDIR = "providers/installed";
+export declare const LIVE_PROVIDERS_SUBDIR = "providers/live";
+export declare const STARTING_PROVIDERS_SUBDIR = "providers/starting";
+export declare const PROVIDER_SOCKETS_SUBDIR = "providers/sockets";
+export declare const PROVIDER_DATA_SUBDIR = "providers/data";
+export declare const BROWSERS_SUBDIR = "browsers";
+export declare const PROVIDER_START_TOKEN_ENV = "MEARL_PROVIDER_START_TOKEN";
+export interface LiveProviderRecord extends DaemonRecord {
+    providerId: string;
+    providerName: string;
+    providerVersion: string;
+    providerProtocolVersion: number;
+    socketPath: string;
+    startedAt: string;
+    updatedAt: number;
+}
+export interface ProviderStartRecord extends DaemonRecord {
+    providerId: string;
+    token: string;
+    startedAt: string;
+}
+export interface ProviderBrowserRecord extends DaemonRecord {
+    browserId: string;
+    providerBrowserId: string;
+    browserName: string;
+    socketPath: string;
+    transport: 'provider';
+    providerId: string;
+    providerName: string;
+    providerVersion: string;
+    providerProtocolVersion: number;
+    capabilities: ProviderBrowser['capabilities'];
+    status?: ProviderBrowser['status'];
+    pairing?: ProviderBrowser['pairing'];
+    startedAt: string;
+    updatedAt: number;
+    lastFocusedAt?: number;
+}
+export interface RegisteredBrowserRecord extends DaemonRecord {
+    browserId: string;
+    browserName: string;
+    socketPath: string;
+    transport: 'extension' | 'cdp' | 'provider';
+    extensionVersion?: string;
+    nativeHostVersion?: string;
+    providerId?: string;
+    providerName?: string;
+    providerVersion?: string;
+    providerProtocolVersion?: number;
+    capabilities?: ProviderBrowser['capabilities'];
+    status?: ProviderBrowser['status'];
+    pairing?: ProviderBrowser['pairing'];
+    startedAt?: string;
+    updatedAt?: number;
+    lastFocusedAt?: number;
+}
+export declare function providerBrowserKey(providerId: string, browserId: string): string;
+export declare function providerSocketPath(providerId: string): string;
+/** Persistent private data directory owned by one installed provider. */
+export declare function providerDataDir(providerId: string): string;
+export declare function installedProviderFile(providerId: string): string;
+export declare function liveProviderFile(providerId: string): string;
+export declare function startingProviderFile(providerId: string): string;
+export declare function claimProviderStart(providerId: string, token: string, pid?: number): boolean;
+export declare function readProviderStart(providerId: string): ProviderStartRecord | null;
+export declare function transferProviderStart(providerId: string, token: string, pid: number): boolean;
+export declare function releaseProviderStart(providerId: string, token: string): boolean;
+export declare function validateInstalledProviderManifest(manifest: InstalledProviderManifest): string | null;
+export declare function installProvider(manifest: InstalledProviderManifest): void;
+export declare function registerProviderPackage(packageRoot: string): InstalledProviderManifest;
+export declare function uninstallProvider(providerId: string): void;
+export declare function stopProvider(providerId: string): boolean;
+export declare function listInstalledProviders(): InstalledProviderManifest[];
+export declare function readLiveProvider(providerId: string): LiveProviderRecord | null;
+export declare function publishLiveProvider(descriptor: ProviderDescriptor, socketPath: string): LiveProviderRecord;
+export declare function unpublishLiveProvider(providerId: string, pid?: number): void;
+export declare function listLiveProviders(): LiveProviderRecord[];
+export declare function publishProviderBrowsers(descriptor: ProviderDescriptor, socketPath: string, browsers: ProviderBrowser[], previousIds: ReadonlySet<string>): Set<string>;
+export declare function touchProviderBrowser(browserId: string): void;
+export declare function unpublishProviderBrowsers(browserIds: Iterable<string>, pid?: number): void;
+export declare function listProviderBrowserRecords(): ProviderBrowserRecord[];
+export declare function listRegisteredBrowserRecords(): RegisteredBrowserRecord[];
+export declare function removeStaleProviderSocket(providerId: string, socketPath?: string): void;

package/dist/registry.js

@@ -0,0 +1,341 @@
+import { existsSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { randomUUID } from 'node:crypto';
+import { isAbsolute, join, relative, resolve, sep } from 'node:path';
+import { claimRecord, ensureDir, hashKey, isAlive, keyedConfigFile, keyedDir, listRecordFiles, readLiveRecords, readRecord, removeInvalidRecord, removeRecordIfPid, writeRecord, writeRecordIfPid, } from '@mearl/daemon-core';
+import { MEARL_PROVIDER_PROTOCOL_VERSION, } from './types.js';
+export const INSTALLED_PROVIDERS_SUBDIR = 'providers/installed';
+export const LIVE_PROVIDERS_SUBDIR = 'providers/live';
+export const STARTING_PROVIDERS_SUBDIR = 'providers/starting';
+export const PROVIDER_SOCKETS_SUBDIR = 'providers/sockets';
+export const PROVIDER_DATA_SUBDIR = 'providers/data';
+export const BROWSERS_SUBDIR = 'browsers';
+export const PROVIDER_START_TOKEN_ENV = 'MEARL_PROVIDER_START_TOKEN';
+export function providerBrowserKey(providerId, browserId) {
+    return `provider:${encodeURIComponent(providerId)}:${encodeURIComponent(browserId)}`;
+}
+export function providerSocketPath(providerId) {
+    const suffix = hashKey(providerId);
+    if (process.platform === 'win32')
+        return `\\\\.\\pipe\\mearl-provider-${suffix}`;
+    return join(keyedDir(PROVIDER_SOCKETS_SUBDIR), `${suffix}.sock`);
+}
+/** Persistent private data directory owned by one installed provider. */
+export function providerDataDir(providerId) {
+    return join(keyedDir(PROVIDER_DATA_SUBDIR), hashKey(providerId));
+}
+export function installedProviderFile(providerId) {
+    return keyedConfigFile(INSTALLED_PROVIDERS_SUBDIR, providerId);
+}
+export function liveProviderFile(providerId) {
+    return keyedConfigFile(LIVE_PROVIDERS_SUBDIR, providerId);
+}
+export function startingProviderFile(providerId) {
+    return keyedConfigFile(STARTING_PROVIDERS_SUBDIR, providerId);
+}
+export function claimProviderStart(providerId, token, pid = process.pid) {
+    const file = startingProviderFile(providerId);
+    const existing = readRecord(file);
+    if (existing && isAlive(existing.pid))
+        return existing.token === token;
+    if (existing)
+        removeRecordIfPid(file, existing.pid);
+    else
+        removeInvalidRecord(file);
+    return claimRecord(file, {
+        pid,
+        providerId,
+        token,
+        startedAt: new Date().toISOString(),
+    });
+}
+export function readProviderStart(providerId) {
+    const record = readRecord(startingProviderFile(providerId));
+    return record && isAlive(record.pid) ? record : null;
+}
+export function transferProviderStart(providerId, token, pid) {
+    const file = startingProviderFile(providerId);
+    const record = readRecord(file);
+    if (!record || record.token !== token)
+        return false;
+    return writeRecordIfPid(file, record.pid, { ...record, pid });
+}
+export function releaseProviderStart(providerId, token) {
+    const file = startingProviderFile(providerId);
+    const record = readRecord(file);
+    return record?.token === token ? removeRecordIfPid(file, record.pid) : false;
+}
+function writeManifest(file, manifest) {
+    ensureDir(keyedDir(INSTALLED_PROVIDERS_SUBDIR));
+    const temporary = `${file}.${process.pid}.${randomUUID()}.tmp`;
+    try {
+        writeFileSync(temporary, JSON.stringify(manifest), { mode: 0o600 });
+        renameSync(temporary, file);
+    }
+    catch (error) {
+        rmSync(temporary, { force: true });
+        throw error;
+    }
+}
+export function validateInstalledProviderManifest(manifest) {
+    if (!manifest ||
+        typeof manifest.providerId !== 'string' ||
+        !manifest.providerId.trim() ||
+        typeof manifest.name !== 'string' ||
+        !manifest.name.trim() ||
+        typeof manifest.version !== 'string' ||
+        !manifest.version.trim()) {
+        return 'manifest is incomplete';
+    }
+    if (manifest.protocolVersion !== MEARL_PROVIDER_PROTOCOL_VERSION) {
+        return `protocol ${manifest.protocolVersion} is unsupported`;
+    }
+    if (!isProviderBrowserType(manifest.browserType)) {
+        return 'browserType is invalid';
+    }
+    if (typeof manifest.packageName !== 'string' || !manifest.packageName.trim()) {
+        return 'packageName is required';
+    }
+    if (typeof manifest.packageRoot !== 'string' || !isAbsolute(manifest.packageRoot)) {
+        return 'packageRoot must be an absolute path';
+    }
+    if (typeof manifest.entryPath !== 'string' || !isAbsolute(manifest.entryPath)) {
+        return 'entryPath must be an absolute path';
+    }
+    const entryRelative = relative(manifest.packageRoot, manifest.entryPath);
+    if (entryRelative === '' ||
+        isAbsolute(entryRelative) ||
+        entryRelative === '..' ||
+        entryRelative.startsWith(`..${sep}`)) {
+        return 'entryPath must be a file inside packageRoot';
+    }
+    if (!isFile(manifest.entryPath))
+        return 'entryPath does not exist or is not a file';
+    return null;
+}
+export function installProvider(manifest) {
+    const invalid = validateInstalledProviderManifest(manifest);
+    if (invalid)
+        throw new Error(`Invalid provider manifest: ${invalid}`);
+    writeManifest(installedProviderFile(manifest.providerId), manifest);
+}
+function packageFile(packageRoot) {
+    return join(packageRoot, 'package.json');
+}
+function isFile(filePath) {
+    try {
+        return statSync(filePath).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+function isProviderBrowserType(value) {
+    if (!value || typeof value !== 'object')
+        return false;
+    const browserType = value;
+    if (typeof browserType.name !== 'string' || !browserType.name.trim())
+        return false;
+    if (!Array.isArray(browserType.parameters))
+        return false;
+    const keys = new Set();
+    for (const parameter of browserType.parameters) {
+        if (!parameter ||
+            typeof parameter !== 'object' ||
+            typeof parameter.key !== 'string' ||
+            !/^[A-Za-z][A-Za-z0-9_]*$/.test(parameter.key) ||
+            typeof parameter.label !== 'string' ||
+            !parameter.label.trim() ||
+            (parameter.required !== undefined && typeof parameter.required !== 'boolean') ||
+            (parameter.placeholder !== undefined && typeof parameter.placeholder !== 'string') ||
+            (parameter.description !== undefined && typeof parameter.description !== 'string') ||
+            keys.has(parameter.key)) {
+            return false;
+        }
+        keys.add(parameter.key);
+    }
+    return true;
+}
+export function registerProviderPackage(packageRoot) {
+    if (!isAbsolute(packageRoot))
+        throw new Error('Provider packageRoot must be an absolute path');
+    let packageJson;
+    try {
+        packageJson = JSON.parse(readFileSync(packageFile(packageRoot), 'utf8'));
+    }
+    catch (error) {
+        throw new Error(`Unable to read Provider package metadata from ${packageRoot}`, {
+            cause: error,
+        });
+    }
+    const metadata = packageJson.mearl?.provider;
+    if (typeof packageJson.name !== 'string' ||
+        !packageJson.name.trim() ||
+        typeof packageJson.version !== 'string' ||
+        !packageJson.version.trim() ||
+        typeof metadata?.providerId !== 'string' ||
+        !metadata.providerId.trim() ||
+        typeof metadata.name !== 'string' ||
+        !metadata.name.trim() ||
+        metadata.protocolVersion !== MEARL_PROVIDER_PROTOCOL_VERSION ||
+        typeof metadata.entry !== 'string' ||
+        !metadata.entry.trim() ||
+        !isProviderBrowserType(metadata.browserType)) {
+        throw new Error(`Invalid mearl.provider metadata in ${packageFile(packageRoot)}`);
+    }
+    if (isAbsolute(metadata.entry)) {
+        throw new Error(`Provider entry must be relative to ${packageFile(packageRoot)}`);
+    }
+    const normalizedRoot = resolve(packageRoot);
+    const entryPath = resolve(normalizedRoot, metadata.entry);
+    const entryRelative = relative(normalizedRoot, entryPath);
+    if (isAbsolute(entryRelative) ||
+        entryRelative === '..' ||
+        entryRelative.startsWith(`..${sep}`) ||
+        !isFile(entryPath)) {
+        throw new Error(`Provider entry must be an existing file inside ${normalizedRoot}`);
+    }
+    const installed = listInstalledProviders();
+    const idConflict = installed.find(provider => provider.providerId === metadata.providerId && provider.packageName !== packageJson.name);
+    if (idConflict) {
+        throw new Error(`Provider id ${metadata.providerId} is already registered by ${idConflict.packageName}`);
+    }
+    const packageConflict = installed.find(provider => provider.packageName === packageJson.name && provider.providerId !== metadata.providerId);
+    if (packageConflict) {
+        throw new Error(`Package ${packageJson.name} is already registered as Provider ${packageConflict.providerId}`);
+    }
+    const manifest = {
+        providerId: metadata.providerId,
+        name: metadata.name,
+        version: packageJson.version,
+        protocolVersion: metadata.protocolVersion,
+        browserType: metadata.browserType,
+        packageName: packageJson.name,
+        packageRoot: normalizedRoot,
+        entryPath,
+    };
+    installProvider(manifest);
+    return manifest;
+}
+export function uninstallProvider(providerId) {
+    rmSync(installedProviderFile(providerId), { force: true });
+}
+export function stopProvider(providerId) {
+    const live = readLiveProvider(providerId);
+    if (!live)
+        return false;
+    try {
+        process.kill(live.pid, 'SIGTERM');
+    }
+    catch (error) {
+        if (error.code !== 'ESRCH')
+            throw error;
+    }
+    return true;
+}
+export function listInstalledProviders() {
+    const manifests = [];
+    for (const file of listRecordFiles(keyedDir(INSTALLED_PROVIDERS_SUBDIR))) {
+        try {
+            const parsed = JSON.parse(readFileSync(file, 'utf8'));
+            if (parsed &&
+                typeof parsed.providerId === 'string' &&
+                typeof parsed.packageName === 'string') {
+                manifests.push(parsed);
+            }
+        }
+        catch {
+            // A broken third-party manifest must not break discovery of other providers.
+        }
+    }
+    return manifests.sort((a, b) => a.providerId.localeCompare(b.providerId));
+}
+export function readLiveProvider(providerId) {
+    const record = readRecord(liveProviderFile(providerId));
+    return record && isAlive(record.pid) ? record : null;
+}
+export function publishLiveProvider(descriptor, socketPath) {
+    const now = Date.now();
+    const record = {
+        pid: process.pid,
+        providerId: descriptor.providerId,
+        providerName: descriptor.name,
+        providerVersion: descriptor.version,
+        providerProtocolVersion: descriptor.protocolVersion ?? MEARL_PROVIDER_PROTOCOL_VERSION,
+        socketPath,
+        startedAt: new Date(now).toISOString(),
+        updatedAt: now,
+    };
+    writeRecord(liveProviderFile(descriptor.providerId), record);
+    return record;
+}
+export function unpublishLiveProvider(providerId, pid = process.pid) {
+    removeRecordIfPid(liveProviderFile(providerId), pid);
+}
+export function listLiveProviders() {
+    return readLiveRecords(keyedDir(LIVE_PROVIDERS_SUBDIR));
+}
+export function publishProviderBrowsers(descriptor, socketPath, browsers, previousIds) {
+    const nextIds = new Set();
+    const now = Date.now();
+    const startedAt = new Date(now).toISOString();
+    for (const browser of browsers) {
+        const browserId = providerBrowserKey(descriptor.providerId, browser.browserId);
+        nextIds.add(browserId);
+        const file = keyedConfigFile(BROWSERS_SUBDIR, browserId);
+        const previous = readRecord(file);
+        const record = {
+            pid: process.pid,
+            browserId,
+            providerBrowserId: browser.browserId,
+            browserName: browser.name,
+            socketPath,
+            transport: 'provider',
+            providerId: descriptor.providerId,
+            providerName: descriptor.name,
+            providerVersion: descriptor.version,
+            providerProtocolVersion: descriptor.protocolVersion ?? MEARL_PROVIDER_PROTOCOL_VERSION,
+            capabilities: browser.capabilities,
+            status: browser.status ?? 'connected',
+            pairing: browser.pairing,
+            startedAt: previous?.startedAt ?? startedAt,
+            updatedAt: now,
+            lastFocusedAt: Math.max(browser.lastFocusedAt ?? 0, previous?.lastFocusedAt ?? 0),
+        };
+        writeRecord(file, record);
+    }
+    for (const browserId of previousIds) {
+        if (!nextIds.has(browserId)) {
+            removeRecordIfPid(keyedConfigFile(BROWSERS_SUBDIR, browserId), process.pid);
+        }
+    }
+    return nextIds;
+}
+export function touchProviderBrowser(browserId) {
+    const file = keyedConfigFile(BROWSERS_SUBDIR, browserId);
+    const record = readRecord(file);
+    if (!record || record.pid !== process.pid)
+        return;
+    writeRecordIfPid(file, process.pid, {
+        ...record,
+        lastFocusedAt: Date.now(),
+        updatedAt: Date.now(),
+    });
+}
+export function unpublishProviderBrowsers(browserIds, pid = process.pid) {
+    for (const browserId of browserIds) {
+        removeRecordIfPid(keyedConfigFile(BROWSERS_SUBDIR, browserId), pid);
+    }
+}
+export function listProviderBrowserRecords() {
+    return listRegisteredBrowserRecords().filter((record) => record.transport === 'provider');
+}
+export function listRegisteredBrowserRecords() {
+    return readLiveRecords(keyedDir(BROWSERS_SUBDIR));
+}
+export function removeStaleProviderSocket(providerId, socketPath) {
+    if (process.platform === 'win32')
+        return;
+    const socket = socketPath ?? providerSocketPath(providerId);
+    if (existsSync(socket) && !readLiveProvider(providerId))
+        rmSync(socket, { force: true });
+}

package/dist/runtime.d.ts

@@ -0,0 +1,4 @@
+/** Mearl host integration; Provider implementations should use the package root API. */
+export { ensureInstalledProvidersRunning } from './launcher.js';
+export { providerBrowserKey, readLiveProvider } from './registry.js';
+export type { LiveProviderRecord } from './registry.js';

package/dist/runtime.js

@@ -0,0 +1,3 @@
+/** Mearl host integration; Provider implementations should use the package root API. */
+export { ensureInstalledProvidersRunning } from './launcher.js';
+export { providerBrowserKey, readLiveProvider } from './registry.js';

package/dist/server.d.ts

@@ -0,0 +1,2 @@
+import type { ProviderServer, ProviderServerOptions } from './types.js';
+export declare function createProviderServer(options: ProviderServerOptions): ProviderServer;

package/dist/server.js

@@ -0,0 +1,326 @@
+import net from 'node:net';
+import { randomUUID } from 'node:crypto';
+import { chmodSync, rmSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { ensureDir } from '@mearl/daemon-core';
+import { isProviderAction } from './generated-provider-actions.js';
+import { PROVIDER_START_TOKEN_ENV, claimProviderStart, providerBrowserKey, providerSocketPath, publishLiveProvider, publishProviderBrowsers, readLiveProvider, releaseProviderStart, removeStaleProviderSocket, touchProviderBrowser, unpublishLiveProvider, unpublishProviderBrowsers, } from './registry.js';
+import { MEARL_PROVIDER_PROTOCOL_VERSION } from './types.js';
+const MAX_REQUEST_BYTES = 16 * 1024 * 1024;
+const activeProviderIds = new Set();
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function isProviderActionRequest(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return false;
+    const request = value;
+    return (typeof request.id === 'string' &&
+        request.id.length > 0 &&
+        typeof request.action === 'string' &&
+        request.action.length > 0 &&
+        (request.data === undefined ||
+            (request.data !== null &&
+                typeof request.data === 'object' &&
+                !Array.isArray(request.data))) &&
+        (request.browserId === undefined || typeof request.browserId === 'string') &&
+        (request.version === undefined || typeof request.version === 'string') &&
+        (request.controlSource === undefined || typeof request.controlSource === 'string'));
+}
+export function createProviderServer(options) {
+    const socketPath = options.socketPath ?? providerSocketPath(options.descriptor.providerId);
+    let server = null;
+    let browserIds = new Set();
+    let browsers = [];
+    let state = 'idle';
+    let stopPromise = null;
+    const connections = new Set();
+    function assertDescriptor() {
+        const { providerId, name, version, protocolVersion } = options.descriptor;
+        if (typeof providerId !== 'string' || !providerId.trim()) {
+            throw new Error('providerId is required');
+        }
+        if (typeof name !== 'string' || !name.trim())
+            throw new Error('provider name is required');
+        if (typeof version !== 'string' || !version.trim()) {
+            throw new Error('provider version is required');
+        }
+        if (protocolVersion !== undefined && protocolVersion !== MEARL_PROVIDER_PROTOCOL_VERSION) {
+            throw new Error(`Unsupported provider protocol ${protocolVersion}; expected ${MEARL_PROVIDER_PROTOCOL_VERSION}`);
+        }
+    }
+    function assertBrowsers(nextBrowsers) {
+        const seen = new Set();
+        for (const browser of nextBrowsers) {
+            if (typeof browser.browserId !== 'string' || !browser.browserId.trim()) {
+                throw new Error('provider browserId is required');
+            }
+            if (typeof browser.name !== 'string' || !browser.name.trim()) {
+                throw new Error(`Provider browser ${browser.browserId} needs a name`);
+            }
+            if (seen.has(browser.browserId)) {
+                throw new Error(`Duplicate provider browserId: ${browser.browserId}`);
+            }
+            seen.add(browser.browserId);
+            if (!Array.isArray(browser.capabilities?.actions)) {
+                throw new Error(`Provider browser ${browser.browserId} needs an actions capability list`);
+            }
+            for (const action of browser.capabilities.actions) {
+                if (!isProviderAction(action)) {
+                    throw new Error(`Unsupported provider capability action: ${String(action)}`);
+                }
+            }
+            if (new Set(browser.capabilities.actions).size !== browser.capabilities.actions.length) {
+                throw new Error(`Provider browser ${browser.browserId} has duplicate capability actions`);
+            }
+            if (!['native', 'reconstructed', 'none'].includes(browser.capabilities.screenshot)) {
+                throw new Error(`Unsupported screenshot capability: ${browser.capabilities.screenshot}`);
+            }
+            const supportsScreenshot = browser.capabilities.actions.includes('page_screenshot');
+            if (supportsScreenshot === (browser.capabilities.screenshot === 'none')) {
+                throw new Error(`Provider browser ${browser.browserId} has inconsistent screenshot capabilities`);
+            }
+            if (browser.status !== undefined && !['connected', 'pairing'].includes(browser.status)) {
+                throw new Error(`Unsupported provider browser status: ${String(browser.status)}`);
+            }
+            assertPairing(browser.status, browser.pairing, browser.browserId);
+            if (browser.lastFocusedAt !== undefined &&
+                (!Number.isFinite(browser.lastFocusedAt) || browser.lastFocusedAt < 0)) {
+                throw new Error(`Provider browser ${browser.browserId} has invalid lastFocusedAt`);
+            }
+        }
+    }
+    function providerBrowserId(requested) {
+        if (requested)
+            return requested;
+        if (browsers.length === 1)
+            return browsers[0].browserId;
+        if (browsers.length === 0)
+            throw new Error('Provider has no connected browsers');
+        throw new Error('browserId is required when the provider has multiple browsers');
+    }
+    async function dispatch(request) {
+        if (request.action === 'browser_launch') {
+            if (request.browserId)
+                throw new Error('browser_launch does not accept browserId');
+            const parameters = request.data ?? {};
+            if (Object.values(parameters).some(value => typeof value !== 'string')) {
+                throw new Error('Provider browser parameters must be strings');
+            }
+            const created = await options.createBrowser(parameters);
+            if (!created ||
+                typeof created.browserId !== 'string' ||
+                !created.browserId.trim() ||
+                typeof created.name !== 'string' ||
+                !created.name.trim() ||
+                !['connected', 'pairing'].includes(created.status)) {
+                throw new Error('Provider returned an invalid browser creation result');
+            }
+            try {
+                assertPairing(created.status, created.pairing, created.browserId);
+            }
+            catch {
+                throw new Error('Provider returned an invalid browser creation result');
+            }
+            return created;
+        }
+        if (request.action !== 'get_versions' &&
+            request.action !== 'browser_close' &&
+            !isProviderAction(request.action)) {
+            throw new Error(`Unsupported provider action: ${String(request.action)}`);
+        }
+        const browserId = providerBrowserId(request.browserId);
+        const found = browsers.find(browser => browser.browserId === browserId);
+        if (!found)
+            throw new Error(`Provider browser not found: ${browserId}`);
+        if (request.action === 'browser_close') {
+            return options.deleteBrowser(browserId);
+        }
+        if (request.action === 'get_versions') {
+            return {
+                provider: {
+                    providerId: options.descriptor.providerId,
+                    name: options.descriptor.name,
+                    version: options.descriptor.version,
+                    protocolVersion: options.descriptor.protocolVersion ?? MEARL_PROVIDER_PROTOCOL_VERSION,
+                },
+                capabilities: found.capabilities,
+            };
+        }
+        if (found.status === 'pairing') {
+            throw new Error(`Provider browser ${browserId} is waiting for device pairing`);
+        }
+        if (!found.capabilities.actions.includes(request.action)) {
+            throw new Error(`Provider browser ${browserId} does not support ${request.action}`);
+        }
+        touchProviderBrowser(providerBrowserKey(options.descriptor.providerId, browserId));
+        return options.handleAction({
+            browserId,
+            action: request.action,
+            data: request.data ?? {},
+            controlSource: request.controlSource,
+        });
+    }
+    function assertPairing(status, pairing, browserId) {
+        if (status === 'pairing' &&
+            (pairing?.kind !== 'qr' || typeof pairing.url !== 'string' || !pairing.url.trim())) {
+            throw new Error(`Pairing browser ${browserId} needs a pairing URL`);
+        }
+        if (status !== 'pairing' && pairing) {
+            throw new Error(`Pairing metadata requires status "pairing": ${browserId}`);
+        }
+        if (pairing &&
+            ((pairing.code !== undefined && typeof pairing.code !== 'string') ||
+                (pairing.label !== undefined && typeof pairing.label !== 'string'))) {
+            throw new Error(`Provider browser ${browserId} has invalid pairing metadata`);
+        }
+    }
+    function handleConnection(socket) {
+        connections.add(socket);
+        socket.once('close', () => connections.delete(socket));
+        let buffer = '';
+        socket.setEncoding('utf8');
+        socket.on('data', chunk => {
+            buffer += chunk;
+            if (Buffer.byteLength(buffer, 'utf8') > MAX_REQUEST_BYTES) {
+                socket.destroy();
+                return;
+            }
+            const newline = buffer.indexOf('\n');
+            if (newline < 0)
+                return;
+            const line = buffer.slice(0, newline);
+            buffer = buffer.slice(newline + 1);
+            let parsed;
+            try {
+                parsed = JSON.parse(line);
+            }
+            catch {
+                socket.end(`${JSON.stringify({ id: '', success: false, error: 'Invalid JSON request' })}\n`);
+                return;
+            }
+            if (!isProviderActionRequest(parsed)) {
+                const id = parsed &&
+                    typeof parsed === 'object' &&
+                    typeof parsed.id === 'string'
+                    ? parsed.id
+                    : '';
+                socket.end(`${JSON.stringify({ id, success: false, error: 'Invalid request envelope' })}\n`);
+                return;
+            }
+            const request = parsed;
+            void dispatch(request)
+                .then(data => socket.end(`${JSON.stringify({ id: request.id, success: true, data })}\n`))
+                .catch(error => socket.end(`${JSON.stringify({ id: request.id, success: false, error: errorMessage(error) })}\n`));
+        });
+    }
+    return {
+        socketPath,
+        async start() {
+            if (state !== 'idle')
+                throw new Error(`Provider server is already ${state}`);
+            assertDescriptor();
+            const providerId = options.descriptor.providerId;
+            if (activeProviderIds.has(providerId)) {
+                throw new Error(`Provider ${providerId} is already running in this process`);
+            }
+            state = 'starting';
+            activeProviderIds.add(providerId);
+            const startToken = process.env[PROVIDER_START_TOKEN_ENV] || randomUUID();
+            const existing = readLiveProvider(options.descriptor.providerId);
+            if (existing) {
+                state = 'idle';
+                activeProviderIds.delete(providerId);
+                throw new Error(`Provider ${options.descriptor.providerId} is already running (pid ${existing.pid})`);
+            }
+            if (!claimProviderStart(providerId, startToken)) {
+                state = 'idle';
+                activeProviderIds.delete(providerId);
+                throw new Error(`Provider ${providerId} start is already in progress`);
+            }
+            try {
+                const competing = readLiveProvider(providerId);
+                if (competing) {
+                    throw new Error(`Provider ${providerId} is already running (pid ${competing.pid})`);
+                }
+                removeStaleProviderSocket(providerId, socketPath);
+                if (process.platform !== 'win32')
+                    ensureDir(dirname(socketPath));
+                server = net.createServer(handleConnection);
+                await new Promise((resolve, reject) => {
+                    server.once('error', reject);
+                    server.listen(socketPath, () => {
+                        server.off('error', reject);
+                        resolve();
+                    });
+                });
+                if (process.platform !== 'win32')
+                    chmodSync(socketPath, 0o600);
+                publishLiveProvider(options.descriptor, socketPath);
+                releaseProviderStart(providerId, startToken);
+                state = 'running';
+            }
+            catch (error) {
+                const active = server;
+                server = null;
+                for (const connection of connections)
+                    connection.destroy();
+                connections.clear();
+                if (active?.listening) {
+                    await new Promise(resolve => active.close(() => resolve()));
+                }
+                unpublishLiveProvider(providerId);
+                if (process.platform !== 'win32')
+                    rmSync(socketPath, { force: true });
+                releaseProviderStart(providerId, startToken);
+                activeProviderIds.delete(providerId);
+                state = 'idle';
+                throw error;
+            }
+        },
+        updateBrowsers(nextBrowsers) {
+            if (state !== 'running')
+                throw new Error('Provider server is not running');
+            assertBrowsers(nextBrowsers);
+            browsers = [...nextBrowsers];
+            browserIds = publishProviderBrowsers(options.descriptor, socketPath, browsers, browserIds);
+        },
+        touchBrowser(browserId) {
+            if (state !== 'running')
+                throw new Error('Provider server is not running');
+            if (!browsers.some(browser => browser.browserId === browserId)) {
+                throw new Error(`Provider browser not found: ${browserId}`);
+            }
+            touchProviderBrowser(providerBrowserKey(options.descriptor.providerId, browserId));
+        },
+        async stop() {
+            if (state === 'idle')
+                return;
+            if (state === 'starting')
+                throw new Error('Provider server is still starting');
+            if (state === 'stopping' && stopPromise)
+                return stopPromise;
+            state = 'stopping';
+            stopPromise = (async () => {
+                const active = server;
+                server = null;
+                for (const connection of connections)
+                    connection.destroy();
+                connections.clear();
+                if (active)
+                    await new Promise(resolve => active.close(() => resolve()));
+                unpublishProviderBrowsers(browserIds);
+                browserIds.clear();
+                browsers = [];
+                if (process.platform !== 'win32')
+                    rmSync(socketPath, { force: true });
+                unpublishLiveProvider(options.descriptor.providerId);
+            })().finally(() => {
+                activeProviderIds.delete(options.descriptor.providerId);
+                stopPromise = null;
+                state = 'idle';
+            });
+            return stopPromise;
+        },
+    };
+}

package/dist/types.d.ts

@@ -0,0 +1,98 @@
+import type { ProviderAction } from './generated-provider-actions.js';
+export declare const MEARL_PROVIDER_PROTOCOL_VERSION = 1;
+export type { ProviderAction } from './generated-provider-actions.js';
+export type ProviderScreenshotKind = 'native' | 'reconstructed' | 'none';
+export interface ProviderCapabilities {
+    actions: ProviderAction[];
+    screenshot: ProviderScreenshotKind;
+}
+export interface ProviderPairingInfo {
+    kind: 'qr';
+    url: string;
+    code?: string;
+    label?: string;
+}
+export interface ProviderDescriptor {
+    providerId: string;
+    name: string;
+    version: string;
+    protocolVersion?: number;
+}
+export interface ProviderBrowserParameter {
+    key: string;
+    label: string;
+    required?: boolean;
+    placeholder?: string;
+    description?: string;
+}
+export interface ProviderBrowserType {
+    name: string;
+    parameters: ProviderBrowserParameter[];
+}
+export interface ProviderBrowser {
+    /** Stable within this provider. Mearl prefixes it with the provider id globally. */
+    browserId: string;
+    name: string;
+    status?: 'connected' | 'pairing';
+    lastFocusedAt?: number;
+    capabilities: ProviderCapabilities;
+    /** Pairing metadata is valid only while status is pairing. */
+    pairing?: ProviderPairingInfo;
+}
+export interface InstalledProviderManifest extends ProviderDescriptor {
+    protocolVersion: number;
+    browserType: ProviderBrowserType;
+    packageName: string;
+    packageRoot: string;
+    entryPath: string;
+}
+export interface ProviderPackageMetadata {
+    providerId: string;
+    name: string;
+    protocolVersion: number;
+    entry: string;
+    browserType: ProviderBrowserType;
+}
+export interface ProviderActionRequest {
+    id: string;
+    action: string;
+    data?: Record<string, unknown>;
+    /** Provider-local browser id selected by the Mearl client. */
+    browserId?: string;
+    version?: string;
+    controlSource?: string;
+}
+export interface ProviderActionContext {
+    browserId: string;
+    action: ProviderAction;
+    data: Record<string, unknown>;
+    controlSource?: string;
+}
+export type ProviderActionHandler = (context: ProviderActionContext) => Promise<unknown>;
+interface ProviderBrowserCreateResultBase {
+    browserId: string;
+    name: string;
+}
+export type ProviderBrowserCreateResult = (ProviderBrowserCreateResultBase & {
+    status: 'connected';
+    pairing?: never;
+}) | (ProviderBrowserCreateResultBase & {
+    status: 'pairing';
+    pairing: ProviderPairingInfo;
+});
+export type ProviderBrowserCreateHandler = (parameters: Record<string, string>) => Promise<ProviderBrowserCreateResult>;
+export type ProviderBrowserDeleteHandler = (browserId: string) => Promise<unknown>;
+export interface ProviderServerOptions {
+    descriptor: ProviderDescriptor;
+    handleAction: ProviderActionHandler;
+    createBrowser: ProviderBrowserCreateHandler;
+    deleteBrowser: ProviderBrowserDeleteHandler;
+    socketPath?: string;
+}
+export interface ProviderServer {
+    readonly socketPath: string;
+    start(): Promise<void>;
+    updateBrowsers(browsers: ProviderBrowser[]): void;
+    touchBrowser(browserId: string): void;
+    stop(): Promise<void>;
+}

package/dist/types.js

@@ -0,0 +1 @@
+export const MEARL_PROVIDER_PROTOCOL_VERSION = 1;

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@mearl/provider",
+  "version": "2.13.0",
+  "description": "Contracts and runtime utilities for external Mearl browser-control providers",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./runtime": {
+      "types": "./dist/runtime.d.ts",
+      "import": "./dist/runtime.js"
+    },
+    "./host": {
+      "types": "./dist/host.d.ts",
+      "import": "./dist/host.js"
+    }
+  },
+  "files": [
+    "dist",
+    "!dist/**/*.map"
+  ],
+  "keywords": [
+    "mearl",
+    "browser-provider"
+  ],
+  "license": "ISC",
+  "engines": {
+    "node": ">=22.12.0"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org"
+  },
+  "dependencies": {
+    "@mearl/daemon-core": "2.13.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.9.1",
+    "typescript": "^5.8.3"
+  },
+  "scripts": {
+    "build": "node ../../scripts/generate-provider-actions.mjs --check && rm -rf dist/ && tsc",
+    "typecheck": "node ../../scripts/generate-provider-actions.mjs --check && tsc --noEmit",
+    "test": "vitest run"
+  }
+}