feat(core): adapter ecosystem hardening

- Add minCoreVersion + AdapterRequirements to SiteAdapter interface
- Add version-check.ts: satisfies(), readCoreVersion(), readAdapterVersion(), parseSemver()
- Wire version check into loadAdapter (server.ts) and defineAdapter — clear error on mismatch
- Add browserkit doctor CLI command — version table, compat check, patchright check, requirements hints
- Update create-adapter scaffold: dynamic version injection, minCoreVersion in template, publishConfig, patchright dep
- Add .github/workflows/test-adapters.yml: matrix CI testing all 5 adapters after core publishes

Made-with: Cursor

Author: jonzarecki

.github/workflows/test-adapters.yml

@@ -0,0 +1,49 @@
+name: Test Adapters Against New Core
+
+# Runs automatically after a successful Release workflow (which publishes core to npm).
+# Also triggerable manually to check all adapters at any time.
+on:
+  workflow_run:
+    workflows: ["Release"]
+    types: [completed]
+  workflow_dispatch:
+
+jobs:
+  test-adapter:
+    # Only run if the Release workflow succeeded (or if triggered manually)
+    if: >
+      github.event_name == 'workflow_dispatch' ||
+      github.event.workflow_run.conclusion == 'success'
+    name: Test ${{ matrix.adapter }}
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false   # test all adapters even if one fails
+      matrix:
+        adapter:
+          - adapter-hackernews
+          - adapter-google-discover
+          - adapter-linkedin
+          - adapter-reddit
+          - adapter-booking
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          repository: browserkit-dev/${{ matrix.adapter }}
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+
+      - name: Install dependencies
+        run: npm install   # picks up the latest @browserkit-dev/core from npm
+
+      - name: Install Patchright Chromium
+        run: npx patchright install chromium --with-deps
+
+      - name: Build
+        run: npm run build
+
+      - name: Test
+        run: npm test
+        timeout-minutes: 10

packages/core/src/cli.ts

@@ -8,6 +8,7 @@ import { SessionManager, getDefaultDataDir } from "./session-manager.js";
 import { runLoginCommand } from "./human-handoff.js";import { createAdapter } from "./create-adapter.js";
 import type { FrameworkConfig, DaemonStatus, AdapterStatus } from "./types.js";
 import { getLogger } from "./logger.js";
+import { readCoreVersion, satisfies, readAdapterVersion } from "./version-check.js";
 
 const log = getLogger("cli");
 
@@ -28,6 +29,8 @@ async function main(): Promise<void> {
       return cmdStatus(args);
     case "config":
       return cmdConfig(args);
+    case "doctor":
+      return cmdDoctor(args);
     case "create-adapter": {
       const name = args[0];
       if (!name) {
@@ -386,6 +389,7 @@ Commands:
   status                Show daemon status
   config cursor         Generate Cursor MCP settings JSON
   create-adapter <name> Scaffold a new standalone adapter package
+  doctor                Check version compatibility for all configured adapters
 
 Options (start):
   --adapter <pkg>    Add an adapter by npm package name (repeatable)
@@ -398,11 +402,149 @@ Examples:
   browserkit logout linkedin
   browserkit reload google-discover
   browserkit status
+  browserkit doctor
   browserkit config cursor
   browserkit create-adapter my-site
 `);
 }
 
+// ─── doctor ──────────────────────────────────────────────────────────────────
+
+async function cmdDoctor(args: string[]): Promise<void> {
+  const config = await resolveConfig(args);
+  const coreVer = readCoreVersion();
+
+  const col = (s: string, w: number) => s.slice(0, w).padEnd(w);
+  const issues: string[] = [];
+
+  // ── Environment summary ───────────────────────────────────────────────────
+  console.log();
+  console.log(`  @browserkit-dev/core  ${coreVer}`);
+  const patchrightVer = getPatchrightVersion();
+  console.log(`  patchright            ${patchrightVer ?? "(not found)"}`);
+  console.log(`  node                  ${process.versions.node}`);
+  console.log();
+
+  // ── Adapter table ─────────────────────────────────────────────────────────
+  const adapterKeys = Object.keys(config.adapters ?? {});
+  if (adapterKeys.length === 0) {
+    console.log("  No adapters configured.");
+    console.log();
+    return;
+  }
+
+  console.log(
+    `  ${col("Adapter", 36)}${col("Version", 10)}${col("Core req", 12)}Status`
+  );
+  console.log(`  ${"-".repeat(72)}`);
+
+  for (const key of adapterKeys) {
+    const adapterConfig = config.adapters[key];
+    if (!adapterConfig) continue;
+
+    // Try to load the adapter module to read its metadata
+    let adapterVersion = readAdapterVersion(key) ?? "?";
+    let minCoreVer: string | undefined;
+    let reqs: Record<string, unknown> | undefined;
+    let loadError: string | undefined;
+
+    try {
+      const mod = await import(key).catch(() => null);
+      const adapter = mod?.default ?? mod;
+      if (adapter && typeof adapter === "object") {
+        minCoreVer = typeof adapter.minCoreVersion === "string" ? adapter.minCoreVersion : undefined;
+        reqs = adapter.requirements;
+      }
+    } catch (err) {
+      loadError = err instanceof Error ? err.message.split("\n")[0] : String(err);
+    }
+
+    // Short display name
+    const displayName = key.startsWith("/") || key.startsWith(".")
+      ? path.basename(path.dirname(key))
+      : key.replace("@browserkit-dev/", "");
+
+    let status: string;
+    if (loadError) {
+      status = `ERROR — ${loadError}`;
+      issues.push(`${displayName}: failed to load — ${loadError}`);
+    } else if (minCoreVer && !satisfies(coreVer, minCoreVer)) {
+      status = `MISMATCH — needs core >= ${minCoreVer} (have ${coreVer})`;
+      issues.push(`${displayName}: needs @browserkit-dev/core >= ${minCoreVer}`);
+    } else {
+      status = "OK";
+    }
+
+    const coreReq = minCoreVer ? `>= ${minCoreVer}` : "(any)";
+    console.log(`  ${col(displayName, 36)}${col(adapterVersion, 10)}${col(coreReq, 12)}${status}`);
+
+    // Requirements vs config mismatch hints
+    if (reqs && typeof reqs === "object") {
+      const r = reqs as {
+        chromeChannelRequired?: boolean;
+        deviceEmulation?: string;
+        useCloakBrowser?: boolean;
+        headedLoginRequired?: boolean;
+      };
+      if (r.chromeChannelRequired && !adapterConfig.channel) {
+        const msg = `  ${" ".repeat(36)}  hint: adapter recommends channel:"chrome" in config`;
+        console.log(msg);
+        issues.push(`${displayName}: missing channel:"chrome" in config`);
+      }
+      if (r.deviceEmulation && !adapterConfig.deviceEmulation) {
+        const msg = `  ${" ".repeat(36)}  hint: adapter recommends deviceEmulation:"${r.deviceEmulation}"`;
+        console.log(msg);
+        issues.push(`${displayName}: missing deviceEmulation:"${r.deviceEmulation}" in config`);
+      }
+      if (r.useCloakBrowser && !adapterConfig.antiDetection?.useCloakBrowser) {
+        const msg = `  ${" ".repeat(36)}  hint: adapter recommends antiDetection.useCloakBrowser:true`;
+        console.log(msg);
+        issues.push(`${displayName}: missing antiDetection.useCloakBrowser:true in config`);
+      }
+    }
+  }
+
+  // ── Patchright peer dep check ─────────────────────────────────────────────
+  console.log();
+  const patchrightOk = checkPatchrightPeer(patchrightVer);
+  if (patchrightOk) {
+    console.log(`  patchright: OK (${patchrightVer} satisfies peer dep ^1.51.0)`);
+  } else {
+    const msg = `patchright ${patchrightVer ?? "(not found)"} — expected ^1.51.0`;
+    console.log(`  patchright: WARN — ${msg}`);
+    issues.push(msg);
+  }
+
+  // ── Summary ───────────────────────────────────────────────────────────────
+  console.log();
+  if (issues.length === 0) {
+    console.log("  Everything looks good.");
+  } else {
+    console.log(`  ${issues.length} issue${issues.length > 1 ? "s" : ""} found.`);
+  }
+  console.log();
+
+  process.exit(issues.length > 0 ? 1 : 0);
+}
+
+function getPatchrightVersion(): string | null {
+  try {
+    const pkgPath = new URL("../node_modules/patchright/package.json", import.meta.url);
+    const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf8")) as { version?: string };
+    return pkg.version ?? null;
+  } catch {
+    return null;
+  }
+}
+
+function checkPatchrightPeer(version: string | null): boolean {
+  if (!version) return false;
+  // peer dep is ^1.51.0 — major must be 1, minor >= 51
+  const parts = version.split(".").map(Number);
+  if (parts.length < 2) return false;
+  return parts[0] === 1 && (parts[1] ?? 0) >= 51;
+}
+
 function readPackageVersion(): string {
   try {
     const pkgPath = new URL("../package.json", import.meta.url);

packages/core/src/create-adapter.ts

@@ -1,5 +1,6 @@
 import fs from "node:fs";
 import path from "node:path";
+import { readCoreVersion } from "./version-check.js";
 
 /**
  * Generate a standalone adapter project in the current directory.
@@ -50,9 +51,10 @@ function writeFile(filePath: string, content: string): void {
 }
 
 function packageJson(name: string): string {
+  const coreVersion = readCoreVersion();
   return JSON.stringify(
     {
-      name: `browserkit-adapter-${name}`,
+      name: `@browserkit-dev/adapter-${name}`,
       version: "0.1.0",
       description: `${name} adapter for browserkit`,
       type: "module",
@@ -64,13 +66,14 @@ function packageJson(name: string): string {
         test: "vitest run",
         lint: "tsc --noEmit",
       },
+      publishConfig: { access: "public" },
       peerDependencies: {
-        "@browserkit-dev/core": ">=0.1.0",
+        "@browserkit-dev/core": `>=${coreVersion}`,
       },
       devDependencies: {
-        "@browserkit-dev/core": "^0.1.0",
+        "@browserkit-dev/core": `^${coreVersion}`,
         "@types/node": "^22.0.0",
-        playwright: "^1.51.0",
+        patchright: "^1.51.0",
         tsx: "^4.0.0",
         typescript: "^5.7.0",
         vitest: "^3.0.0",
@@ -161,6 +164,7 @@ export const SELECTORS = {
 }
 
 function indexTs(name: string): string {
+  const coreVersion = readCoreVersion();
   const domain = `${name}.com`;
   const loginUrl = `https://www.${domain}/login`;
   return `import { defineAdapter } from "@browserkit-dev/core";
@@ -172,6 +176,7 @@ export default defineAdapter({
   site: "${name}",
   domain: "${domain}",
   loginUrl: "${loginUrl}",
+  minCoreVersion: "${coreVersion}",
   rateLimit: { minDelayMs: 2000 },
 
   async isLoggedIn(page: Page): Promise<boolean> {

packages/core/src/define-adapter.ts

@@ -1,4 +1,5 @@
 import type { SiteAdapter } from "./types.js";
+import { satisfies, readCoreVersion, parseSemver } from "./version-check.js";
 
 /**
  * Type-safe helper for defining adapters.
@@ -9,6 +10,17 @@ import type { SiteAdapter } from "./types.js";
  */
 export function defineAdapter(adapter: SiteAdapter): SiteAdapter {
   validateAdapter(adapter);
+  // Dev-time version check: catch mismatches immediately when the module loads
+  if (adapter.minCoreVersion) {
+    const coreVer = readCoreVersion();
+    if (!satisfies(coreVer, adapter.minCoreVersion)) {
+      throw new Error(
+        `Adapter "${adapter.site}" requires @browserkit-dev/core >= ${adapter.minCoreVersion}, ` +
+        `but the installed version is ${coreVer}.\n` +
+        `Run: pnpm add @browserkit-dev/core@latest`
+      );
+    }
+  }
   return adapter;
 }
 
@@ -45,6 +57,13 @@ function validateAdapter(adapter: SiteAdapter): void {
     }
   }
 
+  // Validate minCoreVersion format if provided
+  if (adapter.minCoreVersion !== undefined) {
+    if (parseSemver(adapter.minCoreVersion) === null) {
+      errors.push(`minCoreVersion: "${adapter.minCoreVersion}" is not a valid X.Y.Z version string`);
+    }
+  }
+
   if (errors.length > 0) {
     throw new Error(
       `Invalid adapter definition:\n${errors.map((e) => `  - ${e}`).join("\n")}`

packages/core/src/index.ts

@@ -28,6 +28,7 @@ export type {
   AuthErrorType,
   LoginOptions,
   PossibleLoginResults,
+  AdapterRequirements,
 } from "./types.js";
 export { LoginError } from "./types.js";
 
@@ -86,6 +87,9 @@ export {
 // ─── Login flow (opt-in automated login) ─────────────────────────────────────
 export { withLoginFlow } from "./login-flow.js";
 
+// ─── Version utilities ────────────────────────────────────────────────────────
+export { readCoreVersion, satisfies, parseSemver, readAdapterVersion } from "./version-check.js";
+
 // ─── Observability ────────────────────────────────────────────────────────────
 export { withObservability } from "./observability.js";
 export type { TraceEntry, ObservabilityOptions } from "./observability.js";

packages/core/src/server.ts

@@ -3,6 +3,7 @@ import type { FrameworkConfig, DaemonStatus } from "./types.js";
 import { SessionManager } from "./session-manager.js";
 import { createAdapterServer, type AdapterServerHandle } from "./adapter-server.js";
 import { getLogger } from "./logger.js";
+import { satisfies, readCoreVersion } from "./version-check.js";
 
 const log = getLogger("server");
 
@@ -23,6 +24,17 @@ async function loadAdapter(packageName: string) {
           `Make sure it uses defineAdapter() and has a default export.`
       );
     }
+    // Version compatibility check
+    if (typeof adapter.minCoreVersion === "string") {
+      const coreVer = readCoreVersion();
+      if (!satisfies(coreVer, adapter.minCoreVersion)) {
+        throw new Error(
+          `Adapter "${adapter.site}" requires @browserkit-dev/core >= ${adapter.minCoreVersion}, ` +
+          `but the running version is ${coreVer}.\n` +
+          `Run: pnpm add @browserkit-dev/core@latest`
+        );
+      }
+    }
     return adapter;
   } catch (err: unknown) {
     if (isModuleNotFoundError(err)) {