@pablovitasso/szkrabok 1.0.10 → 1.0.13

package/README.md

@@ -28,9 +28,10 @@ MCP server supplementing [microsoft/playwright-mcp](https://github.com/microsoft
 
 | Use Case | Command |
 | --- | --- |
-| **Scaffolding a new project** | `npx @pablovitasso/szkrabok init` |
-| **Claude Code** | `claude mcp add szkrabok -- npx -y @pablovitasso/szkrabok` |
+| **Claude Code — global (all projects)** | `claude mcp add --scope user szkrabok -- npx -y @pablovitasso/szkrabok` |
+| **Claude Code — this project only** | `claude mcp add szkrabok -- npx -y @pablovitasso/szkrabok` |
 | **Claude Desktop** | See config snippet below |
+| **Scaffold a new project** | `npx @pablovitasso/szkrabok init` |
 | **Development (from source)** | `npm ci && claude mcp add szkrabok node /path/to/szkrabok/src/index.js` |
 
 Claude Desktop — add to `claude_desktop_config.json`:
@@ -45,8 +46,7 @@ Claude Desktop — add to `claude_desktop_config.json`:
 }
 ```
 
-> **Browser not installed?** Run `npx @pablovitasso/szkrabok --setup` once in your terminal, then restart Claude.
-> Set `CI=true` or `SZKRABOK_SKIP_BROWSER_INSTALL=1` to suppress the auto-install in CI / Docker.
+> **Browser not found?** Run `szkrabok detect-browser` to find installed browsers, or `szkrabok install-browser` to install Playwright's Chromium. Requires **Node.js ≥ 20**.
 
 **2. Configure**
 
@@ -91,6 +91,9 @@ bebok session inspect <id>        # Dump cookie/localStorage counts
 bebok session delete <id>         # Delete a session
 bebok session cleanup --days 30   # Delete sessions unused for N days
 bebok endpoint <sessionName>      # Print CDP + WS endpoints
+
+szkrabok detect-browser           # List usable Chrome/Chromium installations
+szkrabok install-browser          # Install Playwright's Chromium
 ```
 
 ---

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pablovitasso/szkrabok",
-  "version": "1.0.10",
+  "version": "1.0.13",
   "description": "Production-grade MCP browser automation layer with persistent sessions and stealth capabilities",
   "type": "module",
   "main": "src/index.js",
@@ -18,11 +18,11 @@
     "README.md"
   ],
   "bin": {
-    "szkrabok": "./src/index.js",
-    "bebok": "./src/cli.js"
+    "szkrabok": "src/index.js",
+    "bebok": "src/cli.js"
   },
   "engines": {
-    "node": ">=18.0.0"
+    "node": ">=20.0.0"
   },
   "workspaces": [
     "packages/runtime"
@@ -37,10 +37,8 @@
     "format:check": "prettier --check \"{src,tests}/**/*.{js,json,md}\" \"*.{js,json,md}\"",
     "codegen:mcp": "node packages/runtime/mcp-client/codegen/generate-mcp-tools.mjs",
     "prepack": "git describe --exact-match --tags HEAD 2>/dev/null || (echo 'ERROR: HEAD is not tagged. Run npm run release:patch or release:minor first.' && exit 1)",
-    "pack:runtime": "npm pack --workspace=packages/runtime --pack-destination=dist/",
-    "pack": "mkdir -p dist && npm run pack:runtime",
-    "release:patch": "npm version patch --workspaces --include-workspace-root --ignore-scripts && npm run pack && node scripts/release-reminder.js",
-    "release:minor": "npm version minor --workspaces --include-workspace-root --ignore-scripts && npm run pack && node scripts/release-reminder.js",
+    "release:patch": "npm version patch --workspaces --include-workspace-root --ignore-scripts && node scripts/release-reminder.js",
+    "release:minor": "npm version minor --workspaces --include-workspace-root --ignore-scripts && node scripts/release-reminder.js",
     "release:publish": "node scripts/release-publish.js",
     "test": "npm run test:self && npm run test:auto",
     "test:node": "node --test tests/node/*.test.js",

package/packages/runtime/config.js

@@ -1,6 +1,5 @@
-import { homedir } from 'os';
 import { join, resolve, dirname } from 'path';
-import { readdirSync, existsSync, readFileSync } from 'fs';
+import { existsSync, readFileSync } from 'fs';
 import { fileURLToPath } from 'url';
 import { parse } from 'smol-toml';
 
@@ -134,40 +133,38 @@ export const TIMEZONE = defaults.timezone || 'America/New_York';
 
 // ── Chromium path resolution ────────────────────────────────────────────────
 
-export const findChromiumPath = () => {
-  if (tomlDefault.executablePath) {
-    return tomlDefault.executablePath;
-  }
-
-  const playwrightCache = join(homedir(), '.cache', 'ms-playwright');
-
-  if (existsSync(playwrightCache)) {
-    const dirs = readdirSync(playwrightCache)
-      .filter(d => d.startsWith('chromium-'))
-      .sort()
-      .reverse();
-
-    for (const dir of dirs) {
-      const paths = [
-        join(playwrightCache, dir, 'chrome-linux', 'chrome'),
-        join(playwrightCache, dir, 'chrome-linux64', 'chrome'),
-      ];
-
-      for (const path of paths) {
-        if (existsSync(path)) return path;
-      }
+// resolveBrowserPath — pure, injectable. Exported for testing.
+// finders: array of async () => string|null, tried in order.
+export const resolveBrowserPath = async (finders) => {
+  for (const finder of finders) {
+    try {
+      const path = await finder();
+      if (path) return path;
+    } catch {
+      // finder unavailable — try next
     }
   }
+  return null;
+};
 
-  const systemChromiums = [
-    '/usr/bin/chromium',
-    '/usr/bin/chromium-browser',
-    '/usr/bin/google-chrome',
-  ];
-
-  for (const path of systemChromiums) {
-    if (existsSync(path)) return path;
+export const findChromiumPath = async () => {
+  // 1. User-configured path (highest priority)
+  if (tomlDefault.executablePath) {
+    return tomlDefault.executablePath;
   }
 
-  return null;
+  return resolveBrowserPath([
+    // 2. System Chrome/Chromium/Brave/Edge via chrome-launcher
+    async () => {
+      const { Launcher } = await import('chrome-launcher');
+      const installs = await Launcher.getInstallations();
+      return installs[0] ?? null;
+    },
+    // 3. Playwright bundled browser
+    async () => {
+      const { chromium } = await import('playwright');
+      const pwPath = chromium.executablePath();
+      return pwPath && existsSync(pwPath) ? pwPath : null;
+    },
+  ]);
 };

package/packages/runtime/index.js

@@ -1,7 +1,7 @@
 // @szkrabok/runtime — public API
 // Do NOT expose: pool internals, storage internals, stealth utilities
 
-export { launch, connect } from './launch.js';
+export { launch, connect, checkBrowser } from './launch.js';
 export { closeSession, getSession, listSessions as listRuntimeSessions, listStoredSessions, updateSessionMeta, deleteStoredSession, updateSessionPage, closeAllSessions } from './sessions.js';
 export { resolvePreset, PRESETS } from './config.js';
 

package/packages/runtime/launch.js

@@ -30,7 +30,7 @@ const cdpPortForId = id => {
 const _launchPersistentContext = async (userDataDir, options = {}) => {
   const presetConfig = options.presetConfig ?? {};
   const pw = options.stealth ? enhanceWithStealth(chromium, presetConfig) : chromium;
-  const executablePath = findChromiumPath();
+  const executablePath = await findChromiumPath();
 
   if (executablePath) {
     log('Using existing Chromium for persistent context', { path: executablePath });
@@ -90,9 +90,25 @@ const _launchPersistentContext = async (userDataDir, options = {}) => {
  * @param {boolean} [options.reuse]     Return existing if profile already open (default: true)
  * @returns {Promise<{ browser: import('playwright').Browser, context: import('playwright').BrowserContext, cdpEndpoint: string, close(): Promise<void> }>}
  */
+export const checkBrowser = async () => {
+  const found = await findChromiumPath();
+  if (!found) {
+    throw new Error(
+      'Chromium browser not found.\n\n' +
+      'Run:\n' +
+      '  npx playwright install chromium\n\n' +
+      'Or:\n' +
+      '  szkrabok install-browser\n'
+    );
+  }
+  return found;
+};
+
 export const launch = async (options = {}) => {
   const { profile = 'default', preset: presetName, headless, stealth, userAgent, viewport, locale, timezone, reuse = true } = options;
 
+  await checkBrowser();
+
   // Idempotency: return existing handle when reuse=true and profile is open
   if (reuse && pool.has(profile)) {
     log(`Reusing existing session: ${profile}`);

package/packages/runtime/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@szkrabok/runtime",
-  "version": "1.0.10",
+  "version": "1.0.13",
   "description": "szkrabok — browser bootstrap, stealth, session pool, MCP client.",
   "type": "module",
   "main": "index.js",
@@ -14,8 +14,12 @@
   "scripts": {
     "postinstall": "node scripts/patch-playwright.js"
   },
+  "engines": {
+    "node": ">=20.0.0"
+  },
   "dependencies": {
     "@modelcontextprotocol/sdk": ">=1.0.0",
+    "chrome-launcher": "*",
     "playwright": "*",
     "playwright-core": "*",
     "playwright-extra": "*",

package/scripts/release-publish.js

@@ -1,19 +1,18 @@
-import { readFileSync } from 'node:fs';
 import { execSync } from 'node:child_process';
+import { readFileSync } from 'node:fs';
 import { resolve, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
 const pkg = JSON.parse(readFileSync(resolve(dirname(fileURLToPath(import.meta.url)), '../package.json'), 'utf8'));
 const v = pkg.version;
-const tarball = `dist/szkrabok-runtime-${v}.tgz`;
 
 try {
-  execSync(`gh auth status`, { stdio: 'pipe' });
+  execSync('npm whoami', { stdio: 'pipe' });
 } catch {
-  console.error('ERROR: gh auth failed. Run: gh auth login');
+  console.error('ERROR: not logged in to npm. Run: npm login');
   process.exit(1);
 }
 
-console.log(`Creating GitHub release v${v} and uploading ${tarball}...`);
-execSync(`gh release create v${v} ${tarball} --repo PabloVitasso/szkrabok --title v${v}`, { stdio: 'inherit' });
-console.log(`\nDone. Remember to update RUNTIME_RELEASES in src/tools/scaffold.js.`);
+console.log(`Publishing @pablovitasso/szkrabok@${v} to npm...`);
+execSync('npm publish --access public', { stdio: 'inherit' });
+console.log(`\nDone. https://www.npmjs.com/package/@pablovitasso/szkrabok`);

package/scripts/release-reminder.js

@@ -6,9 +6,8 @@ const pkg = JSON.parse(readFileSync(resolve(dirname(fileURLToPath(import.meta.ur
 const v = pkg.version;
 
 console.log(`
-Pack complete: dist/szkrabok-runtime-${v}.tgz
+Version bumped to ${v}.
 
 Next steps:
-  1. npm run release:publish
-  2. Update RUNTIME_RELEASES in src/tools/scaffold.js  (add '${v}' entry, bump CURRENT_RUNTIME_VERSION)
+  npm run release:publish
 `);

package/src/cli.js

@@ -163,4 +163,34 @@ program
     }
   });
 
+/* ---------- detect-browser command ---------- */
+
+program
+  .command('detect-browser')
+  .description('Detect usable Chrome/Chromium browsers')
+  .action(async () => {
+    const { findChromiumPath } = await import('#runtime');
+    const path = await findChromiumPath();
+    if (!path) {
+      console.log('No usable Chrome/Chromium browser found.\n');
+      console.log('  szkrabok install-browser');
+      console.log('  https://www.google.com/chrome/\n');
+      process.exit(1);
+    }
+    console.log(path);
+    console.log('\nRecommended configuration:\n\n[default]');
+    console.log(`executablePath = "${path}"`);
+  });
+
+/* ---------- install-browser command ---------- */
+
+program
+  .command('install-browser')
+  .description('Install Chromium browser via Playwright')
+  .action(async () => {
+    const { spawn } = await import('node:child_process');
+    const proc = spawn('npx', ['playwright', 'install', 'chromium'], { stdio: 'inherit' });
+    proc.on('close', code => process.exit(code ?? 0));
+  });
+
 program.parse();

package/src/tools/templates/szkrabok.config.local.toml.example

@@ -2,8 +2,7 @@
 # Machine-specific overrides. Copy to szkrabok.config.local.toml and edit.
 # This file is gitignored — never commit credentials or paths here.
 #
-# Run `bash node_modules/@szkrabok/runtime/scripts/detect_browsers.sh`
-# to find your Chrome/Chromium binary path.
+# Run `szkrabok detect-browser` to find Chrome/Chromium binary paths.
 
 [default]
 # executablePath = "/path/to/chrome"

package/scripts/detect_browsers.sh

@@ -1,147 +0,0 @@
-#!/usr/bin/env bash
-# detect_browsers.sh — find Chrome/Chromium binaries and echo szkrabok.config.toml lines
-#
-# Usage:
-#   bash scripts/detect_browsers.sh
-#
-# Output:
-#   For each detected browser: its version + the TOML executablePath line to use.
-#   If nothing useful is found: installation suggestions.
-#
-# Copy the executablePath line you want into szkrabok.config.toml [default] section.
-# Google Chrome stable is best for stealth (native brands). Ungoogled-chromium is a
-# good second choice. The Playwright bundled binary (Chrome for Testing) should be
-# avoided in production — it brands itself as automation tooling.
-
-set -euo pipefail
-
-FOUND=()
-
-# ── helpers ───────────────────────────────────────────────────────────────────
-
-get_version() {
-  # Run binary with --version, strip leading "Chromium ", "Google Chrome " etc.
-  timeout 5 "$1" --version 2>/dev/null | head -1 | sed 's/^[^0-9]*//' || true
-}
-
-check_binary() {
-  local label="$1" path="$2"
-  if [[ -x "$path" ]]; then
-    local ver
-    ver="$(get_version "$path")"
-    if [[ -n "$ver" ]]; then
-      echo "  FOUND  $label — $ver"
-      echo "         executablePath = \"$path\""
-      echo ""
-      FOUND+=("$label")
-    fi
-  fi
-}
-
-check_flatpak() {
-  local label="$1" app_id="$2"
-  if command -v flatpak >/dev/null 2>&1 && flatpak info "$app_id" >/dev/null 2>&1; then
-    local ver
-    ver="$(timeout 5 flatpak run "$app_id" --version 2>/dev/null | head -1 | sed 's/^[^0-9]*//' || true)"
-    if [[ -n "$ver" ]]; then
-      # Write a small wrapper path check — flatpak run is the executable path
-      local wrapper
-      wrapper="$(command -v flatpak)"
-      echo "  FOUND  $label — $ver"
-      echo "         # flatpak binary — use a wrapper script or the flatpak run command:"
-      echo "         executablePath = \"$HOME/.local/bin/$(echo "$app_id" | tr '.' '-' | tr '[:upper:]' '[:lower:]')\""
-      echo "         # (create that wrapper: echo '#!/bin/sh' > the path, then:"
-      echo "         #  echo 'exec flatpak run $app_id \"\$@\"' >> the path, chmod +x)"
-      echo ""
-      FOUND+=("$label")
-    fi
-  fi
-}
-
-check_snap() {
-  local label="$1" snap_name="$2" snap_bin="$3"
-  if [[ -x "$snap_bin" ]]; then
-    local ver
-    ver="$(get_version "$snap_bin")"
-    if [[ -n "$ver" ]]; then
-      echo "  FOUND  $label — $ver"
-      echo "         executablePath = \"$snap_bin\""
-      echo ""
-      FOUND+=("$label")
-    fi
-  fi
-}
-
-# ── scan ──────────────────────────────────────────────────────────────────────
-
-echo ""
-echo "=== szkrabok browser detection ==="
-echo ""
-echo "Scanning for usable Chrome/Chromium binaries..."
-echo ""
-
-# Google Chrome stable (best for stealth — native brands)
-check_binary "Google Chrome stable"       "/usr/bin/google-chrome"
-check_binary "Google Chrome stable"       "/usr/bin/google-chrome-stable"
-check_binary "Google Chrome stable"       "/opt/google/chrome/chrome"
-check_binary "Google Chrome stable"       "/opt/google/chrome/google-chrome"
-
-# Chromium (distro package)
-check_binary "Chromium (distro)"          "/usr/bin/chromium"
-check_binary "Chromium (distro)"          "/usr/bin/chromium-browser"
-
-# Ungoogled-chromium — common wrapper locations
-check_binary "Ungoogled-chromium"         "$HOME/.local/bin/ungoogled-chromium"
-check_binary "Ungoogled-chromium"         "/usr/bin/ungoogled-chromium"
-
-# Ungoogled-chromium via flatpak — only if no wrapper binary was found above
-if [[ ! -x "$HOME/.local/bin/ungoogled-chromium" && ! -x "/usr/bin/ungoogled-chromium" ]]; then
-  check_flatpak "Ungoogled-chromium (flatpak)" "io.github.ungoogled_software.ungoogled_chromium"
-fi
-
-# Chromium via snap
-check_snap "Chromium (snap)"              "chromium" "/snap/bin/chromium"
-
-# Brave
-check_binary "Brave"                      "/usr/bin/brave-browser"
-check_binary "Brave"                      "/usr/bin/brave-browser-stable"
-check_binary "Brave"                      "/opt/brave.com/brave/brave"
-
-# Microsoft Edge (Chromium-based)
-check_binary "Microsoft Edge"             "/usr/bin/microsoft-edge"
-check_binary "Microsoft Edge"             "/usr/bin/microsoft-edge-stable"
-check_binary "Microsoft Edge"             "/opt/microsoft/msedge/msedge"
-
-# ── results ───────────────────────────────────────────────────────────────────
-
-if [[ ${#FOUND[@]} -eq 0 ]]; then
-  echo "  NONE FOUND — no usable Chrome/Chromium binary detected."
-  echo ""
-  echo "  szkrabok will fall back to the Playwright bundled 'Chrome for Testing'."
-  echo "  This works but is detectable as automation tooling (brands itself as"
-  echo "  'Chrome for Testing' in navigator.userAgentData)."
-  echo ""
-  echo "  Recommended installations:"
-  echo ""
-  echo "  1. Google Chrome stable (best stealth — native brands):"
-  echo "       https://www.google.com/chrome/"
-  echo "       wget -qO- https://dl.google.com/linux/linux_signing_key.pub | sudo apt-key add -"
-  echo "       sudo sh -c 'echo \"deb [arch=amd64] http://dl.google.com/linux/chrome/deb/ stable main\" > /etc/apt/sources.list.d/google-chrome.list'"
-  echo "       sudo apt-get update && sudo apt-get install google-chrome-stable"
-  echo ""
-  echo "  2. Ungoogled-chromium via flatpak (no Google services, good stealth):"
-  echo "       flatpak install flathub io.github.ungoogled_software.ungoogled_chromium"
-  echo "       # then create a wrapper: ~/.local/bin/ungoogled-chromium"
-  echo "       # with: exec flatpak run io.github.ungoogled_software.ungoogled_chromium \"\$@\""
-  echo ""
-else
-  echo "  Copy one executablePath line above into szkrabok.config.toml [default]."
-  echo ""
-  echo "  Stealth ranking (best first):"
-  echo "    1. Google Chrome stable — native 'Google Chrome' brands, most trusted"
-  echo "    2. Ungoogled-chromium   — no Google services; needs greasy brands patch"
-  echo "    3. Chromium (distro)    — same as ungoogled; needs greasy brands patch"
-  echo "    4. Chrome for Testing   — avoid in production (automation-branded)"
-fi
-
-echo ""