@pablovitasso/szkrabok 1.0.10

package/scripts/postinstall.js

@@ -0,0 +1,47 @@
+#!/usr/bin/env node
+// Smart Chromium installer — runs after npm install.
+// Skips if: CI env, SZKRABOK_SKIP_BROWSER_INSTALL set, or Chromium already found.
+
+import { execSync } from 'node:child_process';
+import { existsSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+
+if (process.env.CI || process.env.SZKRABOK_SKIP_BROWSER_INSTALL) {
+  console.log('szkrabok: skipping browser install (CI or SZKRABOK_SKIP_BROWSER_INSTALL set).');
+  process.exit(0);
+}
+
+const findChromium = () => {
+  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) {
+      for (const bin of ['chrome-linux/chrome', 'chrome-linux64/chrome']) {
+        const p = join(playwrightCache, dir, bin);
+        if (existsSync(p)) return p;
+      }
+    }
+  }
+  for (const p of ['/usr/bin/chromium', '/usr/bin/chromium-browser', '/usr/bin/google-chrome']) {
+    if (existsSync(p)) return p;
+  }
+  return null;
+};
+
+if (findChromium()) {
+  console.log('szkrabok: Chromium already available, skipping install.');
+  process.exit(0);
+}
+
+console.log('szkrabok: installing Playwright Chromium browser...');
+try {
+  execSync('npx playwright install chromium', { stdio: 'inherit' });
+} catch {
+  console.error(
+    'szkrabok: browser install failed. Run "szkrabok --setup" manually to retry.'
+  );
+}

package/scripts/release-publish.js

@@ -0,0 +1,19 @@
+import { readFileSync } from 'node:fs';
+import { execSync } from 'node:child_process';
+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' });
+} catch {
+  console.error('ERROR: gh auth failed. Run: gh auth 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.`);

package/scripts/release-reminder.js

@@ -0,0 +1,14 @@
+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;
+
+console.log(`
+Pack complete: dist/szkrabok-runtime-${v}.tgz
+
+Next steps:
+  1. npm run release:publish
+  2. Update RUNTIME_RELEASES in src/tools/scaffold.js  (add '${v}' entry, bump CURRENT_RUNTIME_VERSION)
+`);

package/scripts/setup.js

@@ -0,0 +1,17 @@
+import { mkdir } from 'fs/promises'
+import { existsSync } from 'fs'
+
+const dirs = ['sessions', 'logs']
+
+const setup = async () => {
+  for (const dir of dirs) {
+    if (!existsSync(dir)) {
+      await mkdir(dir, { recursive: true })
+      console.log(`Created ${dir}/`)
+    }
+  }
+
+  console.log('szkrabok installed. To install the Chromium browser, run: szkrabok --setup')
+}
+
+setup().catch(console.error)

package/src/cli.js

@@ -0,0 +1,166 @@
+#!/usr/bin/env node
+
+import { program } from 'commander';
+import path from 'node:path';
+import fs from 'node:fs/promises';
+import { list, deleteSession, endpoint } from './tools/szkrabok_session.js';
+
+const SESSIONS_DIR = path.join(process.cwd(), 'sessions');
+
+program
+  .name('bebok')
+  .description('szkrabok CLI')
+  .version('2.0.0');
+
+/* ---------- helpers ---------- */
+
+const readJson = async file => {
+  try {
+    return JSON.parse(await fs.readFile(file, 'utf8'));
+  } catch {
+    return null;
+  }
+};
+
+const shutdownHandler = handle => async () => {
+  try {
+    await handle.close();
+  } finally {
+    process.exit(0);
+  }
+};
+
+/* ---------- session command ---------- */
+
+program
+  .command('session')
+  .description('Session management')
+  .argument('<action>', 'list | inspect | delete | cleanup')
+  .argument('[id]', 'Session ID')
+  .option('--days <days>', 'For cleanup: delete sessions older than N days', '30')
+  .action(async (action, id, options) => {
+    const actions = {
+      list: async () => {
+        const { sessions } = await list();
+        console.table(
+          sessions.map(s => ({
+            ID: s.id,
+            Active: s.active ? 'yes' : 'no',
+            Preset: s.preset ?? 'N/A',
+            Label: s.label ?? 'N/A',
+          }))
+        );
+      },
+
+      inspect: async () => {
+        if (!id) throw new Error('Session ID required');
+
+        const dir = path.join(SESSIONS_DIR, id);
+        const [meta, state] = await Promise.all([
+          readJson(path.join(dir, 'meta.json')),
+          readJson(path.join(dir, 'state.json')),
+        ]);
+
+        if (!meta || !state) throw new Error(`Session ${id} not found or incomplete`);
+
+        console.log('=== METADATA ===');
+        console.log(JSON.stringify(meta, null, 2));
+        console.log('\n=== COOKIES ===');
+        console.log(state.cookies?.length ?? 0, 'cookies');
+        console.log('\n=== LOCALSTORAGE ===');
+        for (const origin of state.origins ?? []) {
+          console.log(origin.origin, ':', origin.localStorage?.length ?? 0, 'items');
+        }
+      },
+
+      delete: async () => {
+        if (!id) throw new Error('Session ID required');
+        await deleteSession({ sessionName: id });
+        console.log(`Session ${id} deleted`);
+      },
+
+      cleanup: async () => {
+        const days = Number(options.days) || 30;
+        const cutoff = Date.now() - days * 86400000;
+
+        let entries;
+        try {
+          entries = await fs.readdir(SESSIONS_DIR, { withFileTypes: true });
+        } catch {
+          console.log('No sessions directory found');
+          return;
+        }
+
+        await Promise.all(
+          entries
+            .filter(e => e.isDirectory())
+            .map(async e => {
+              const meta = await readJson(path.join(SESSIONS_DIR, e.name, 'meta.json'));
+              if (meta?.lastUsed && meta.lastUsed < cutoff) {
+                await deleteSession({ sessionName: e.name });
+                console.log(`Deleted old session: ${e.name}`);
+              }
+            })
+        );
+      },
+    };
+
+    const fn = actions[action];
+    if (!fn) {
+      console.error(`Unknown action: ${action}. Use: list | inspect | delete | cleanup`);
+      process.exit(1);
+    }
+
+    try {
+      await fn();
+    } catch (err) {
+      console.error(err.message);
+      process.exit(1);
+    }
+  });
+
+/* ---------- open command ---------- */
+
+program
+  .command('open <profile>')
+  .description(
+    'Launch a browser session with stealth + persistence. Prints CDP endpoint. Runs until Ctrl-C.'
+  )
+  .option('--preset <preset>', 'TOML preset name')
+  .option('--headless', 'Run headless')
+  .action(async (profile, options) => {
+    const { launch } = await import('#runtime');
+
+    const handle = await launch({
+      profile,
+      preset: options.preset,
+      headless: options.headless ?? undefined,
+      reuse: false,
+    });
+
+    console.log(handle.cdpEndpoint);
+
+    const shutdown = shutdownHandler(handle);
+    process.on('SIGINT', shutdown);
+    process.on('SIGTERM', shutdown);
+
+    await new Promise(() => {});
+  });
+
+/* ---------- endpoint command ---------- */
+
+program
+  .command('endpoint <sessionName>')
+  .description('Print CDP and WS endpoints for a running session')
+  .action(async sessionName => {
+    try {
+      const result = await endpoint({ sessionName });
+      console.log(`CDP: ${result.cdpEndpoint}`);
+      if (result.wsEndpoint) console.log(`WS:  ${result.wsEndpoint}`);
+    } catch (err) {
+      console.error(err.message);
+      process.exit(1);
+    }
+  });
+
+program.parse();

package/src/config.js

@@ -0,0 +1,36 @@
+// MCP-layer config — request timeouts and logging only.
+// Browser launch config (presets, stealth, headless, UA, viewport) lives in
+// @szkrabok/runtime. Do not re-add browser concerns here.
+
+import { join, resolve, dirname } from 'path';
+import { existsSync, readFileSync } from 'fs';
+import { fileURLToPath } from 'url';
+import { parse } from 'smol-toml';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const REPO_ROOT = resolve(__dirname, '..');
+
+const isPlainObject = v => v !== null && typeof v === 'object' && !Array.isArray(v);
+const deepMerge = (base, override) => {
+  const result = { ...base };
+  for (const key of Object.keys(override)) {
+    result[key] =
+      isPlainObject(base[key]) && isPlainObject(override[key])
+        ? deepMerge(base[key], override[key])
+        : override[key];
+  }
+  return result;
+};
+
+const TOML_PATH = join(REPO_ROOT, 'szkrabok.config.toml');
+const TOML_LOCAL_PATH = join(REPO_ROOT, 'szkrabok.config.local.toml');
+const tomlBase = existsSync(TOML_PATH) ? parse(readFileSync(TOML_PATH, 'utf8')) : {};
+const tomlLocal = existsSync(TOML_LOCAL_PATH) ? parse(readFileSync(TOML_LOCAL_PATH, 'utf8')) : {};
+const toml = deepMerge(tomlBase, tomlLocal);
+
+const tomlDefault = toml.default ?? {};
+
+export const DEFAULT_TIMEOUT = 30000;
+export const TIMEOUT = tomlDefault.timeout ?? DEFAULT_TIMEOUT;
+export const LOG_LEVEL = tomlDefault.log_level ?? 'info';
+export const DISABLE_WEBGL = tomlDefault.disable_webgl ?? false;

package/src/index.js

@@ -0,0 +1,53 @@
+#!/usr/bin/env node
+import 'dotenv/config';
+import { createServer } from './server.js';
+import { log, logError } from './utils/logger.js';
+
+// Parse CLI args
+const args = process.argv.slice(2);
+
+if (args.includes('init')) {
+  const { init } = await import('./tools/scaffold.js');
+  const result = await init({ dir: process.cwd(), preset: 'minimal', install: false });
+  if (result.created.length) console.error(`Created: ${result.created.join(', ')}`);
+  if (result.merged.length) console.error(`Merged: ${result.merged.join(', ')}`);
+  if (result.skipped.length) console.error(`Skipped (already exists): ${result.skipped.join(', ')}`);
+  if (result.warnings.length) result.warnings.forEach(w => console.error(`Warning: ${w}`));
+  console.error('Done. Run "szkrabok --setup" if Chromium is not yet installed.');
+  process.exit(0);
+}
+
+if (args.includes('--setup')) {
+  const { execSync } = await import('node:child_process');
+  console.log('Installing Playwright Chromium browser...');
+  try {
+    execSync('npx playwright install chromium', { stdio: 'inherit' });
+    console.log('Browser installed successfully.');
+  } catch {
+    console.error('Browser install failed. Run manually: npx playwright install chromium');
+    process.exit(1);
+  }
+  process.exit(0);
+}
+
+if (args.includes('--no-headless') || args.includes('--headful')) {
+  process.env.HEADLESS = 'false';
+}
+
+const server = createServer();
+
+process.on('SIGINT', async () => {
+  log('Shutting down gracefully...');
+  await server.close();
+  process.exit(0);
+});
+
+process.on('uncaughtException', err => {
+  logError('Uncaught exception', err);
+  process.exit(1);
+});
+
+server.connect().catch(err => {
+  logError('Failed to start server', err);
+  process.exit(1);
+});

package/src/server.js

@@ -0,0 +1,40 @@
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
+import { registerTools, handleToolCall } from './tools/registry.js';
+import { closeAllSessions } from '#runtime';
+import { log } from './utils/logger.js';
+
+export const createServer = () => {
+  const server = new Server(
+    {
+      name: 'szkrabok',
+      version: '2.0.0',
+    },
+    {
+      capabilities: {
+        tools: {},
+      },
+    }
+  );
+
+  server.setRequestHandler(ListToolsRequestSchema, async () => ({
+    tools: registerTools(),
+  }));
+
+  server.setRequestHandler(CallToolRequestSchema, async request =>
+    handleToolCall(request.params.name, request.params.arguments)
+  );
+
+  return {
+    async connect() {
+      const transport = new StdioServerTransport();
+      await server.connect(transport);
+      log('Server connected via stdio');
+    },
+    async close() {
+      await closeAllSessions();
+      log('Server closed');
+    },
+  };
+};

package/src/tools/registry.js

@@ -0,0 +1,171 @@
+import * as session from './szkrabok_session.js';
+import * as workflow from './workflow.js';
+import * as szkrabokBrowser from './szkrabok_browser.js';
+import * as scaffold from './scaffold.js';
+import { wrapError } from '../utils/errors.js';
+import { logError } from '../utils/logger.js';
+
+const SZKRABOK = '[szkrabok]';
+const PLAYWRIGHT_MCP = '[playwright-mcp]';
+
+const tools = {
+  'session_manage': {
+    handler: session.manage,
+    description: `${SZKRABOK} Manage browser sessions. action: open (launch/resume session), close (save+close), list (all stored), delete (remove data), endpoint (get CDP/WS URLs). open requires sessionName; list requires none; others require sessionName`,
+    inputSchema: {
+      type: 'object',
+      properties: {
+        action: {
+          type: 'string',
+          enum: ['open', 'close', 'list', 'delete', 'endpoint'],
+        },
+        sessionName: { type: 'string' },
+        url: { type: 'string' },
+        save: { type: 'boolean', default: true },
+        launchOptions: {
+          type: 'object',
+          description:
+            'open only. Use either preset OR individual fields (userAgent, viewport, locale, timezone). headless and stealth always allowed.',
+          properties: {
+            preset: { type: 'string', description: 'Preset name from szkrabok.config.toml' },
+            stealth: { type: 'boolean', default: true },
+            disableWebGL: { type: 'boolean', default: false },
+            headless: { type: 'boolean' },
+            userAgent: { type: 'string' },
+            viewport: {
+              type: 'object',
+              properties: { width: { type: 'number' }, height: { type: 'number' } },
+            },
+            locale: { type: 'string' },
+            timezone: { type: 'string' },
+          },
+        },
+      },
+      required: ['action'],
+    },
+  },
+
+  'workflow.scrape': {
+    handler: workflow.scrape,
+    description: `${SZKRABOK} Scrape current page into LLM-ready text. Returns raw blocks and llmFriendly string. selectors: optional CSS selectors to target specific areas; omit for auto (main/body)`,
+    inputSchema: {
+      type: 'object',
+      properties: {
+        sessionName: { type: 'string' },
+        selectors: {
+          type: 'array',
+          items: { type: 'string' },
+          description: 'CSS selectors to target. Omit for auto-mode (main or body).',
+        },
+      },
+      required: ['sessionName'],
+    },
+  },
+
+  'scaffold.init': {
+    handler: scaffold.init,
+    description: `${SZKRABOK} Init szkrabok project (idempotent). Prerequisite for browser runs. minimal (default): config/deps; full: automation fixtures and Playwright specs`,
+    inputSchema: {
+      type: 'object',
+      properties: {
+        dir: { type: 'string', description: 'Target directory. Defaults to cwd.' },
+        name: { type: 'string', description: 'Package name. Defaults to dirname.' },
+        preset: {
+          type: 'string',
+          enum: ['minimal', 'full'],
+          description: 'minimal (default): config files only. full: + automation/fixtures.js + automation/example.spec.js + automation/example.mcp.spec.js',
+        },
+        install: {
+          type: 'boolean',
+          description: 'Run npm install after writing files. Default false.',
+        },
+      },
+    },
+  },
+
+  'browser_run': {
+    handler: szkrabokBrowser.run,
+    description: `${PLAYWRIGHT_MCP} Execute Playwright JS on session page. Pass code (inline snippet) or path (named export from .mjs file with (page, args)). fn defaults to "default".`,
+    inputSchema: {
+      type: 'object',
+      properties: {
+        sessionName: { type: 'string' },
+        code: { type: 'string' },
+        path: { type: 'string', description: 'Absolute or relative path to an .mjs script file' },
+        fn: { type: 'string', description: 'Named export to call. Defaults to "default".' },
+        args: { type: 'object', description: 'Arguments passed as second parameter to the function' },
+      },
+      required: ['sessionName'],
+    },
+  },
+
+  'browser.run_test': {
+    handler: szkrabokBrowser.run_test,
+    description: `${PLAYWRIGHT_MCP} Run .spec.js tests via CDP (returns JSON). Requires session_manage(open) and scaffold.init`,
+    inputSchema: {
+      type: 'object',
+      properties: {
+        sessionName: { type: 'string' },
+        grep: { type: 'string', description: 'Filter tests by name (regex)' },
+        params: {
+          type: 'object',
+          description:
+            'Key/value params passed as TEST_* env vars to the spec (e.g. {url:"https://..."} → TEST_URL)',
+        },
+        config: {
+          type: 'string',
+          description: 'Config path relative to repo root. Defaults to playwright.config.js',
+        },
+        project: {
+          type: 'string',
+          description:
+            'Playwright project name to run (e.g. "automation"). Runs all projects if omitted.',
+        },
+        files: {
+          type: 'array',
+          items: { type: 'string' },
+          description:
+            'File or directory paths passed as positional args to playwright test (e.g. ["automation/rebrowser-check.spec.js"] or ["automation/"]). Relative to repo root.',
+        },
+        keepOpen: {
+          type: 'boolean',
+          description:
+            'After the test run, reconnect the session if the test subprocess invalidated the MCP context. Chrome stays alive; this restores the Playwright connection to it. Default false.',
+        },
+      },
+      required: ['sessionName'],
+    },
+  },
+
+};
+
+export const registerTools = () =>
+  Object.entries(tools).map(([name, tool]) => ({
+    name,
+    description: tool.description,
+    inputSchema: tool.inputSchema,
+  }));
+
+export const handleToolCall = async (name, args) => {
+  const tool = tools[name];
+
+  if (!tool) {
+    return {
+      content: [{ type: 'text', text: JSON.stringify({ error: `Unknown tool: ${name}` }) }],
+      isError: true,
+    };
+  }
+
+  try {
+    const result = await tool.handler(args);
+    return {
+      content: [{ type: 'text', text: JSON.stringify(result) }],
+    };
+  } catch (err) {
+    logError(`Tool ${name} failed`, err, { args });
+    return {
+      content: [{ type: 'text', text: JSON.stringify(wrapError(err)) }],
+      isError: true,
+    };
+  }
+};