@farmslot/adapter-web 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,13 @@
+# Changelog
+
+All notable changes to `@farmslot/adapter-web` are tracked here.
+
+## Unreleased
+
+- Active-development baseline; add user-facing changes here before release or package publication.
+
+## 0.1.0 - 2026-10-04
+
+- Add the package with the browser process and CDP layer moved from `@deeeed/metamask-harness`, unchanged in behaviour: `browser-resolver` (Chrome for Testing vs branded Chrome, probe cache, `runCli` entry), `browser-cdp` (deadline-bound browser CDP client, CDP-port ownership proof, `Extensions.loadUnpacked`, extension isolation), `chrome-args` (remote-debugging flags, runtime identity nonce, launch quarantine), `extension-id`, `macos-focus`, `playwright-cdp` (LavaMoat-safe page evaluation), `validation-process-ownership` and `validation-launch-supervisor`. Process, on-disk and environment names are Farmslot's: `--farmslot-runtime-nonce=`, `.farmslot-detached-launch-unproven`, `/tmp/farmslot-browser-validation-<uid>`, `~/.cache/farmslot/browser-probe.json`, `farmslot-browser-probe-*`, `FARMSLOT_FOCUS_HOLD`, `FARMSLOT_FOCUS_BROWSER` and `FARMSLOT_VALIDATION_PORT_LEASE`; remediation hints name no product command.
+- Add `page-target` (`selectPageTarget`: the page on an origin, preferring one whose URL carries a hash) and `browser-cdp.placeWindow` (move a target's window over CDP; a visible window moves without activating the browser).
+- Every module's exports are named bindings Node's CommonJS export detection can read, so ESM named imports work (`import { probeLaunch } from '@farmslot/adapter-web/browser-resolver'`); a package test checks `import()` against `require()` for each export.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Arthur Breton
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,40 @@
+# @farmslot/adapter-web
+
+Web platform pieces for Farmslot recipes: pick and launch an isolated Chromium, prove which process owns a CDP port, load an unpacked extension, and give macOS focus back after a headed launch. A harness builds its `web` platform on these; the modules hold no product knowledge.
+
+```js
+const { resolveBrowser } = require('@farmslot/adapter-web/browser-resolver');
+const { connectBrowserCdp, waitForCdpOwner } = require('@farmslot/adapter-web/browser-cdp');
+const { activateMacAppByPid } = require('@farmslot/adapter-web/macos-focus');
+```
+
+Docs: https://farmslot.io/docs/reference/adapter-web
+
+## Source layout
+
+| module                         | owns                                                                                                           |
+| ------------------------------ | -------------------------------------------------------------------------------------------------------------- |
+| `browser-resolver`             | Chrome for Testing vs branded Chrome, probe-launch and its cache, extension loading method; CLI entry          |
+| `browser-cdp`                  | browser-level CDP client with deadlines, CDP-port ownership proof, `Extensions.loadUnpacked`, window placement |
+| `chrome-args`                  | remote-debugging flags, isolated profile flags, runtime identity nonce, launch quarantine markers              |
+| `extension-id`                 | Chromium extension id from a manifest key or an unpacked directory                                             |
+| `macos-focus`                  | capture the frontmost app before a headed launch and restore it if one of our browsers took it                 |
+| `page-target`                  | pick the page on an origin, preferring one whose URL carries a hash                                            |
+| `playwright-cdp`               | page evaluation over a raw CDP session (safe under LavaMoat scuttling)                                         |
+| `validation-process-ownership` | find and stop the processes that own a slot profile                                                            |
+| `validation-launch-supervisor` | supervised child for one validation launch: port lease, quarantine and cleanup                                 |
+
+Sources are CommonJS (`src/*.cjs`) and ship as is; `yarn build` emits `.d.cts` declarations. Every library subpath can be `require`d or `import`ed with named imports, except `validation-launch-supervisor`: it is a child-process entry (it runs when loaded), so hosts `require.resolve` it and fork it.
+
+## Maintenance rules
+
+1. No product knowledge. A product's build locks, titles, fixtures and wallet state stay in its harness and reach these modules as arguments.
+2. Process and on-disk identity strings (runtime nonce flag, launch markers, probe cache path) are how a launched browser and its profile are recognised. Changing one makes browsers started under the old name unrecognised; call that out in the release notes.
+3. Every CDP call has a deadline. Never add an unbounded wait.
+4. Never steal focus. A headed launch restores the previous frontmost app; window activation goes by pid, not by app name. `placeWindow` moves a visible window without activating it (restoring a minimized one can).
+
+## Local quality
+
+```bash
+yarn workspace @farmslot/adapter-web quality
+```

package/dist/browser-cdp.d.cts

@@ -0,0 +1,119 @@
+export const DEFAULT_COMMAND_TIMEOUT_MS: 15000;
+export const START_TIME_SLACK_MS: 2000;
+/**
+ * @param {number} port
+ * @param {string} profile
+ * @param {{ exec?: typeof defaultExec, timeoutMs?: number }} [options]
+ */
+export function assertCdpOwnedByProfile(port: number, profile: string, options?: {
+    exec?: typeof defaultExec;
+    timeoutMs?: number;
+}): {
+    pid: number;
+    startedAt: string;
+    profile: string;
+    cdpPort: number;
+};
+/**
+ * @param {{ pid: number, startedAt: string, profile: string, cdpPort: number }} owner
+ * @param {{ exec?: typeof defaultExec, timeoutMs?: number }} [options]
+ */
+export function assertSameOwner(owner: {
+    pid: number;
+    startedAt: string;
+    profile: string;
+    cdpPort: number;
+}, { exec, timeoutMs }?: {
+    exec?: typeof defaultExec;
+    timeoutMs?: number;
+}): {
+    pid: number;
+    startedAt: string;
+    profile: string;
+    cdpPort: number;
+};
+export function canonicalProfile(profile: any): string;
+export function cdpListenerPids(port: any, exec?: typeof defaultExec, { deadline }?: {
+    deadline?: number | undefined;
+}): number[];
+export function cdpOwner(port: any, profile: any, { exec, timeoutMs }?: {
+    exec?: typeof defaultExec | undefined;
+    timeoutMs?: number | undefined;
+}): {
+    pid: number;
+    startedAt: string;
+    profile: string;
+    cdpPort: number;
+};
+export function processStartTime(pid: any, exec?: typeof defaultExec, { timeoutMs }?: {
+    timeoutMs?: number | undefined;
+}): string | null;
+export function waitForCdpOwner(port: any, profile: any, { timeoutMs, exec }?: {
+    timeoutMs?: number | undefined;
+    exec?: typeof defaultExec | undefined;
+}): {
+    pid: number;
+    startedAt: string;
+    profile: string;
+    cdpPort: number;
+};
+export function connectBrowserCdp(port: any, { timeoutMs, commandTimeoutMs }?: {
+    timeoutMs?: number | undefined;
+    commandTimeoutMs?: number | undefined;
+}): Promise<{
+    send: (method: any, params: {} | undefined, sessionId: any, timeout?: number) => Promise<any>;
+    close: () => void;
+}>;
+export function expectedExtensionId(extensionDir: any): string | null;
+export function loadUnpackedExtension(send: any, extensionDir: any, { expectedId, timeoutMs }?: {
+    expectedId?: null | undefined;
+    timeoutMs?: number | undefined;
+}): Promise<{
+    id: any;
+}>;
+/**
+ * @param {number} port
+ * @param {string} extensionDir
+ * @param {{ profile: string, expectedId?: string | null, url?: string | null, timeoutMs?: number, exec?: typeof defaultExec }} options
+ */
+export function loadUnpackedOverPort(port: number, extensionDir: string, { profile, expectedId, url, timeoutMs, exec, }?: {
+    profile: string;
+    expectedId?: string | null;
+    url?: string | null;
+    timeoutMs?: number;
+    exec?: typeof defaultExec;
+}): Promise<{
+    otherExtensions: {
+        disabled: {
+            id: any;
+            name: any;
+            location: any;
+        }[];
+        policyPinned: any;
+    };
+    owner: {
+        pid: number;
+        startedAt: string;
+        profile: string;
+        cdpPort: number;
+    };
+    id: any;
+}>;
+export function ensureBackgroundWindow(send: any, remaining: any): Promise<void>;
+export function isolateExtension(send: any, extensionId: any, { timeoutMs }?: {
+    timeoutMs?: number | undefined;
+}): Promise<{
+    disabled: {
+        id: any;
+        name: any;
+        location: any;
+    }[];
+    policyPinned: any;
+}>;
+export function openBackgroundWindow(send: any, url: any, timeoutMs: any): Promise<any>;
+export function openUrl(send: any, url: any, remaining: any): Promise<void>;
+export function placeWindow(send: any, targetId: any, bounds: any, timeoutMs?: number): Promise<any>;
+declare function defaultExec(command: any, args: any, { timeoutMs }?: {
+    timeoutMs?: number | undefined;
+}): string;
+export {};

package/dist/browser-resolver.d.cts

@@ -0,0 +1,140 @@
+#!/usr/bin/env node
+export const BRANDED_CHROME_ARGS: string[];
+export const CDP_LOAD_UNPACKED: "cdp-load-unpacked";
+export const HEADFUL: "headful";
+export const HEADLESS: "headless";
+export const LAUNCH_SERVICES: "launch-services";
+export const LOAD_EXTENSION: "load-extension";
+export const SPAWN: "spawn";
+export const TRANSIENT_VERDICT_TTL_MS: number;
+export const UNLAUNCHABLE_MARKER: "BROWSER_UNLAUNCHABLE:";
+export const assertCdpOwnedByProfile: typeof cdp.assertCdpOwnedByProfile;
+export const cdpListenerPids: typeof cdp.cdpListenerPids;
+export const cdpOwner: typeof cdp.cdpOwner;
+export const waitForCdpOwner: typeof cdp.waitForCdpOwner;
+export function brandedChromeCandidates(env?: NodeJS.ProcessEnv, platform?: NodeJS.Platform, home?: string): string[];
+export function browserMode(env?: NodeJS.ProcessEnv): {
+    mode: string;
+    path?: undefined;
+} | {
+    mode: string;
+    path: string;
+};
+export function browserVersion(executable: any): string | null;
+export const connectBrowserCdp: typeof cdp.connectBrowserCdp;
+export function defaultCachePath(env?: NodeJS.ProcessEnv): string;
+export function describeBrowser(executable: any): {
+    bin: any;
+    browser: string;
+    version: string | null;
+    extensionLoading: string;
+};
+export function effectiveLaunchMethod(executable: any, launchMethod: any, platform?: NodeJS.Platform): "launch-services" | "spawn";
+export const expectedExtensionId: typeof cdp.expectedExtensionId;
+/**
+ * @param {string} extensionDir
+ * @param {string} extensionLoading
+ * @returns {string[]}
+ */
+export function extensionLaunchArgs(extensionDir: string, extensionLoading: string): string[];
+export function extensionLoadingFor(executable: any): "cdp-load-unpacked" | "load-extension";
+export function isBrandedChrome(executable: any): boolean;
+export const loadUnpackedExtension: typeof cdp.loadUnpackedExtension;
+export const loadUnpackedOverPort: typeof cdp.loadUnpackedOverPort;
+export function playwrightChromiumExecutable(target: any): {
+    error: string;
+    executable?: undefined;
+} | {
+    executable: string;
+    error?: undefined;
+};
+export function probeCacheKey(executable: any, version: any, launchMethod?: string, display?: string): string;
+export function probeLaunch(executable: any, { launchMethod, display, settleMs, startupMs, renderAttempts, }?: {
+    launchMethod?: string | undefined;
+    display?: string | undefined;
+    settleMs?: number | undefined;
+    startupMs?: number | undefined;
+    renderAttempts?: number | undefined;
+}): Promise<{
+    ok: any;
+    reason: any;
+    transient: boolean;
+    launchMethod: string;
+    display: string;
+    durationMs: number;
+}>;
+export function readProbeCache(cachePath: any): any;
+export function renderCheck(port: any): Promise<{
+    ok: boolean;
+    reason?: undefined;
+} | {
+    ok: boolean;
+    reason: any;
+}>;
+/**
+ * @param {{
+ *   env?: NodeJS.ProcessEnv,
+ *   cft?: () => { executable?: string, error?: string },
+ *   probe?: typeof probeLaunch,
+ *   cachePath?: string,
+ *   chromeCandidates?: string[],
+ *   exists?: (file: string) => boolean,
+ *   describe?: typeof describeBrowser,
+ *   now?: () => Date,
+ *   launchMethod?: string,
+ *   display?: string,
+ *   recorded?: string | null,
+ *   managedChrome?: typeof readManagedChromePolicy,
+ * }} [options]
+ */
+export function resolveBrowser({ env, cft, probe, cachePath, chromeCandidates, exists, describe, now, launchMethod, display, recorded, managedChrome, }?: {
+    env?: NodeJS.ProcessEnv;
+    cft?: () => {
+        executable?: string;
+        error?: string;
+    };
+    probe?: typeof probeLaunch;
+    cachePath?: string;
+    chromeCandidates?: string[];
+    exists?: (file: string) => boolean;
+    describe?: typeof describeBrowser;
+    now?: () => Date;
+    launchMethod?: string;
+    display?: string;
+    recorded?: string | null;
+    managedChrome?: typeof readManagedChromePolicy;
+}): Promise<{
+    source: any;
+    resolvedAt: string;
+    bin: any;
+    browser: string;
+    version: string | null;
+    extensionLoading: string;
+    schemaVersion: number;
+}>;
+export function withProbeLock(cachePath: any, key: any, fn: any, { waitMs, beforeClaim, readStartTime }?: {
+    waitMs?: number | undefined;
+    beforeClaim?: null | undefined;
+    readStartTime?: typeof startTimeOf | undefined;
+}): Promise<any>;
+export function readManagedChromePolicy({ platform, plists, exists, readKey, extensionName, }?: {
+    platform?: NodeJS.Platform | undefined;
+    plists?: string[] | undefined;
+    exists?: ((file: any) => boolean) | undefined;
+    readKey?: typeof readPolicyKey | undefined;
+    extensionName?: typeof installedExtensionName | undefined;
+}): {
+    forcedExtensions: {
+        id: any;
+        name: any;
+    }[];
+    signinForced: boolean;
+    sources: string[];
+} | null;
+export function managedChromePlists(env?: NodeJS.ProcessEnv): string[];
+export function runCli(argv?: string[]): void;
+import cdp = require("./browser-cdp.cjs");
+declare function startTimeOf(pid: any, timeoutMs: any): string | null;
+declare function readPolicyKey(file: any, key: any): any;
+declare function installedExtensionName(id: any, home?: string): any;
+export {};

package/dist/chrome-args.d.cts

@@ -0,0 +1,29 @@
+export const DETACHED_LAUNCH_UNPROVEN_FILENAME: ".farmslot-detached-launch-unproven";
+export const RUNTIME_IDENTITY_FILENAME: "extension-runtime-identity.json";
+export const RUNTIME_NONCE_PREFIX: "--farmslot-runtime-nonce=";
+export function automationRuntimeArgs(): string[];
+export function clearDetachedLaunchUnproven(profile: any): void;
+export function clearValidationPortQuarantine(port: any, profile: any, lease: any): void;
+export function createRuntimeIdentityNonce(): string;
+export function detachedLaunchUnprovenPath(profile: any): string;
+export function hasDetachedLaunchUnproven(profile: any): boolean;
+export function isolatedProfileArgs(platform?: NodeJS.Platform): string[];
+export function markDetachedLaunchUnproven(profile: any): string;
+export function markValidationPortLaunchUnproven(port: any, profile: any, lease: any): string;
+export function quarantineDetachedLaunch(profile: any, reason: any): string;
+export function quarantineValidationPort(port: any, profile: any, reason: any): string;
+export function readValidationPortQuarantine(port: any): {
+    path: string;
+} | {
+    lease?: any;
+    path: string;
+    profile: any;
+} | null;
+export function remoteDebuggingArgs(cdpPort: any): string[];
+export function removeRuntimeIdentity(runtimeDir: any): void;
+export function runtimeIdentityArgs(nonce: any): string[];
+export function runtimeIdentityPath(runtimeDir: any): string;
+export function shellQuote(value: any): string;
+export function validationLaunchQuarantineError(port: any, ownerProfile: any, requestedProfile: any): Error;
+export function validationPortQuarantinePath(port: any): string;
+export function writeRuntimeIdentity(runtimeDir: any, identity: any): void;

package/dist/extension-id.d.cts

@@ -0,0 +1,4 @@
+export const CHROMIUM_EXTENSION_ID_ALPHABET: "abcdefghijklmnop";
+export function extensionIdFromManifestKey(keyBase64: any): string;
+export function extensionIdFromManifestFile(manifestPath: any): string;
+export function extensionIdFromExtensionDir(extensionDir: any): string;

package/dist/macos-focus.d.cts

@@ -0,0 +1,10 @@
+export function activateMacAppByPid(pid: any): boolean;
+export function captureMacFrontmost(): {
+    pid: number;
+    bundlePath: any;
+    name: any;
+} | null;
+export function macBackgroundOpenArgs(application: any, chromeArgs: any): any[];
+export function macFocusDisabled(): boolean;
+export function macFrontmostPid(): number | null;
+export function restoreFrontmostIfOurs(previous: any, ourPids: any): "off" | "kept" | "restored";

package/dist/page-target.d.cts

@@ -0,0 +1,4 @@
+export function selectPageTarget(targets: any, { origin, hash }: {
+    origin: any;
+    hash?: string | undefined;
+}): any;

package/dist/playwright-cdp.d.cts

@@ -0,0 +1,8 @@
+export function buildEvaluationExpression(callbackOrExpression: any, argument: any): string;
+export function connectBrowserViaCdp(endpoint: any): Promise<any>;
+/**
+ * @param {any} page Playwright page
+ * @param {string | ((...args: any[]) => unknown)} callbackOrExpression
+ * @param {unknown} [argument]
+ */
+export function evaluatePageViaCdp(page: any, callbackOrExpression: string | ((...args: any[]) => unknown), argument?: unknown): Promise<any>;

package/dist/validation-launch-supervisor.d.cts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/validation-process-ownership.d.cts

@@ -0,0 +1,14 @@
+export function profileProcessPids(profile: any): number[];
+export function stopProfileProcesses(profile: any, { quietMs, timeoutMs }?: {
+    quietMs?: number | undefined;
+    timeoutMs?: number | undefined;
+}): Promise<void>;
+/**
+ * @param {string} profile
+ * @param {{ extraPids?: number[], timeoutMs?: number, waitForAppearanceMs?: number }} [options]
+ */
+export function stopProfileProcessesSync(profile: string, { extraPids, timeoutMs, waitForAppearanceMs }?: {
+    extraPids?: number[];
+    timeoutMs?: number;
+    waitForAppearanceMs?: number;
+}): void;

package/package.json

@@ -0,0 +1,97 @@
+{
+  "name": "@farmslot/adapter-web",
+  "version": "0.1.0",
+  "description": "Web platform adapter for Farmslot recipes: resolve and launch an isolated Chromium, own its CDP port, load unpacked extensions, and keep macOS focus.",
+  "type": "commonjs",
+  "exports": {
+    "./browser-cdp": {
+      "types": "./dist/browser-cdp.d.cts",
+      "default": "./src/browser-cdp.cjs"
+    },
+    "./browser-resolver": {
+      "types": "./dist/browser-resolver.d.cts",
+      "default": "./src/browser-resolver.cjs"
+    },
+    "./chrome-args": {
+      "types": "./dist/chrome-args.d.cts",
+      "default": "./src/chrome-args.cjs"
+    },
+    "./extension-id": {
+      "types": "./dist/extension-id.d.cts",
+      "default": "./src/extension-id.cjs"
+    },
+    "./macos-focus": {
+      "types": "./dist/macos-focus.d.cts",
+      "default": "./src/macos-focus.cjs"
+    },
+    "./page-target": {
+      "types": "./dist/page-target.d.cts",
+      "default": "./src/page-target.cjs"
+    },
+    "./playwright-cdp": {
+      "types": "./dist/playwright-cdp.d.cts",
+      "default": "./src/playwright-cdp.cjs"
+    },
+    "./validation-launch-supervisor": {
+      "types": "./dist/validation-launch-supervisor.d.cts",
+      "default": "./src/validation-launch-supervisor.cjs"
+    },
+    "./validation-process-ownership": {
+      "types": "./dist/validation-process-ownership.d.cts",
+      "default": "./src/validation-process-ownership.cjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit --project tsconfig.json && yarn build && tsc --project tsconfig.consumer.json",
+    "test": "node --test \"test/*.test.cjs\"",
+    "format": "prettier --write --ignore-path ../../.prettierignore .",
+    "format:check": "prettier --check --ignore-path ../../.prettierignore .",
+    "lint": "eslint \"src/**/*.cjs\" \"test/**/*.cjs\" \"test/**/*.ts\"",
+    "lint:fix": "eslint \"src/**/*.cjs\" \"test/**/*.cjs\" \"test/**/*.ts\" --fix",
+    "quality": "prettier --check --ignore-path ../../.prettierignore . && eslint \"src/**/*.cjs\" \"test/**/*.cjs\" \"test/**/*.ts\" && yarn typecheck && yarn test",
+    "build": "rm -rf dist && tsc --project tsconfig.build.json",
+    "prepack": "cd ../.. && node scripts/quality/check-farmslot-package-readiness.mjs --require-changelog --packages @farmslot/adapter-web && yarn workspace @farmslot/adapter-web build",
+    "prepublishOnly": "node ../../scripts/quality/check-farmslot-package-readiness.mjs --publish --packages @farmslot/adapter-web"
+  },
+  "dependencies": {
+    "ws": "^8.18.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "eslint": "^10.3.0",
+    "prettier": "^3.8.3",
+    "typescript": "^5.6.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/deeeed/farmslot.git",
+    "directory": "packages/adapter-web"
+  },
+  "bugs": {
+    "url": "https://github.com/deeeed/farmslot/issues"
+  },
+  "license": "MIT",
+  "homepage": "https://farmslot.io/docs/reference/adapter-web",
+  "keywords": [
+    "farmslot",
+    "recipe",
+    "adapter",
+    "chrome",
+    "cdp",
+    "agentic-engineering"
+  ],
+  "engines": {
+    "node": ">=22.12.0"
+  },
+  "files": [
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md",
+    "src/**/*.cjs",
+    "dist/**/*.d.cts"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}