@jshookmcp/jshook 0.2.5 → 0.2.6

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@jshookmcp/jshook",
-  "version": "0.2.5",
-  "description": "MCP server with 327 built-in tools across 23 domains for AI-assisted JavaScript analysis and security analysis — browser automation, CDP debugging, network monitoring, JS hooks, code analysis, and workflow orchestration",
+  "version": "0.2.6",
+  "description": "MCP server with 337 built-in tools across 24 domains for AI-assisted JavaScript analysis and security analysis — browser automation, CDP debugging, network monitoring, JS hooks, code analysis, and workflow orchestration",
   "keywords": [
     "ai",
     "anti-detection",
@@ -78,7 +78,7 @@
     "ajv-formats": "^3.0.1",
     "chalk": "^5.6.2",
     "commander": "^14.0.3",
-    "dotenv": "^17.3.1",
+    "dotenv": "^17.4.0",
     "koffi": "^2.15.1",
     "openai": "^6.25.0",
     "ora": "^9.3.0",
@@ -92,20 +92,19 @@
     "@types/babel__traverse": "^7.28.0",
     "@types/better-sqlite3": "^7.6.13",
     "@types/node": "^25.3.0",
-    "@vitest/coverage-v8": "^4.0.18",
+    "@vitest/coverage-v8": "^4.1.2",
     "cross-env": "^10.1.0",
     "estree-walker": "^2.0.2",
-    "lefthook": "^2.1.3",
+    "lefthook": "^2.1.4",
     "medium-zoom": "^1.1.0",
-    "nodemon": "^3.1.14",
-    "oxfmt": "^0.41.0",
-    "oxlint": "^1.56.0",
+    "oxfmt": "^0.43.0",
+    "oxlint": "^1.58.0",
     "tsc-alias": "^1.8.16",
     "tsx": "^4.21.0",
     "typescript": "^5.9.3",
-    "vite": "^6.0.0",
+    "vite": "^8.0.2",
     "vitepress": "1.6.4",
-    "vitest": "^4.0.18",
+    "vitest": "^4.1.2",
     "vue": "^3.5.30"
   },
   "optionalDependencies": {
@@ -115,7 +114,7 @@
     "webcrack": "^2.15.1"
   },
   "engines": {
-    "node": ">=20.0.0"
+    "node": "^20.19.0 || >=22.12.0"
   },
   "mcpName": "io.github.vmoranv/jshookmcp",
   "scripts": {
@@ -135,7 +134,7 @@
     "format:check": "oxfmt \"src/**\" \"tests/**\" \"!tests/tmp/**\" --check --no-error-on-unmatched-pattern",
     "test": "vitest run",
     "test:e2e": "cross-env E2E_TARGET_URL=https://vmoranv.github.io/jshookmcp/ vitest run --config tests/e2e/vitest.e2e.config.ts",
-    "test:coverage": "cross-env ENABLE_INJECTION_TOOLS=true vitest run --coverage",
+    "test:coverage": "node -e \"require('fs').mkdirSync('coverage/.tmp', { recursive: true })\" && cross-env ENABLE_INJECTION_TOOLS=true COVERAGE_FULL=true vitest run --coverage",
     "package:verify-bin": "node scripts/verify-packed-bin.mjs",
     "package:verify-install": "node scripts/verify-packed-install.mjs",
     "package:verify-release": "node scripts/verify-release-artifact.mjs",

package/scripts/postinstall.cjs

@@ -2,36 +2,63 @@ const fs = require('node:fs');
 const path = require('node:path');
 const { spawnSync } = require('node:child_process');
 
-const repoGitDir = path.join(process.cwd(), '.git');
-const localBin = path.join(
-  process.cwd(),
-  'node_modules',
-  '.bin',
-  process.platform === 'win32' ? 'lefthook.cmd' : 'lefthook'
-);
-
-if (!fs.existsSync(repoGitDir)) {
-  process.exit(0);
-}
+const repoGitDir = path.join(process.cwd(), '.git');
+const localBin = path.join(
+  process.cwd(),
+  'node_modules',
+  '.bin',
+  process.platform === 'win32' ? 'lefthook.cmd' : 'lefthook'
+);
+const isCi = process.env.CI === 'true' || process.env.GITHUB_ACTIONS === 'true';
+
+if (isCi || !fs.existsSync(repoGitDir)) {
+  process.exit(0);
+}
 
 if (!fs.existsSync(localBin)) {
   console.warn('[postinstall] lefthook not found locally; skipping git hook installation.');
   process.exit(0);
 }
 
-const result = spawnSync(localBin, ['install'], {
-  stdio: 'inherit',
-  shell: process.platform === 'win32',
-});
-
-if (result.error) {
-  console.warn(
-    `[postinstall] lefthook install failed to spawn: ${result.error.message}; skipping git hook installation.`
-  );
-} else if (result.status !== 0) {
-  console.warn(
-    `[postinstall] lefthook install exited with status ${result.status}; skipping git hook installation.`
-  );
-}
-
-process.exit(0);
+const hooksPathResult = spawnSync('git', ['config', '--local', '--get', 'core.hooksPath'], {
+  encoding: 'utf8',
+  shell: process.platform === 'win32',
+});
+
+const configuredHooksPath = hooksPathResult.status === 0 ? hooksPathResult.stdout.trim() : '';
+if (configuredHooksPath) {
+  const resolvedHooksPath = path.resolve(process.cwd(), configuredHooksPath);
+  const defaultHooksPath = path.resolve(repoGitDir, 'hooks');
+
+  if (resolvedHooksPath === defaultHooksPath) {
+    process.exit(0);
+  }
+
+  console.warn(
+    `[postinstall] core.hooksPath is already set to "${configuredHooksPath}"; skipping git hook installation.`
+  );
+  process.exit(0);
+}
+
+const result = spawnSync(localBin, ['install'], {
+  encoding: 'utf8',
+  stdio: ['ignore', 'pipe', 'pipe'],
+  shell: process.platform === 'win32',
+});
+
+if (result.error) {
+  console.warn(
+    `[postinstall] lefthook install failed to spawn: ${result.error.message}; skipping git hook installation.`
+  );
+} else if (result.status !== 0) {
+  const firstDetailLine = [result.stdout, result.stderr]
+    .join('\n')
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .find(Boolean);
+  console.warn(
+    `[postinstall] lefthook install exited with status ${result.status}; skipping git hook installation${firstDetailLine ? ` (${firstDetailLine})` : ''}.`
+  );
+}
+
+process.exit(0);

package/workflows/anti-bot-diagnoser/.jshook-install.json

@@ -0,0 +1,14 @@
+{
+  "version": 1,
+  "kind": "workflow",
+  "slug": "anti-bot-diagnoser",
+  "id": "workflow.anti-bot-diagnoser.v1",
+  "source": {
+    "type": "git",
+    "repo": "https://github.com/vmoranv/jshook_workflow_anti_bot_diagnoser",
+    "ref": "main",
+    "commit": "b7e270de2a0cbb90ed431bd9de4fcd101cc53439",
+    "subpath": ".",
+    "entry": "workflow.ts"
+  }
+}

package/workflows/anti-bot-diagnoser/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 vmoranv
+
+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/workflows/anti-bot-diagnoser/README.md

@@ -0,0 +1,105 @@
+# jshook_workflow_template
+
+TypeScript-first template repository for building a reusable `jshook` workflow.
+
+This template focuses on one thing:
+
+- codify an existing built-in tool chain into a reusable workflow contract
+- keep TypeScript source in Git and generated JavaScript out of Git
+
+## Included in the template
+
+- `workflow.ts`: workflow source entrypoint
+- `docs/agent-recipes.md`: recipes for orchestration, parallel reads, and subagent-assisted analysis
+- `dist/workflow.js`: generated locally by `pnpm run build` and ignored by Git
+
+## What the MVP workflow demonstrates
+
+The sample workflow runs this shape:
+
+1. `network_enable`
+2. `page_navigate`
+3. parallel surface collection
+   - `page_get_local_storage`
+   - `page_get_cookies`
+   - `network_get_requests`
+   - `page_get_all_links`
+   - optional `console_get_logs`
+4. `network_extract_auth`
+5. `console_execute` summary output
+
+## Dependency model
+
+This template uses the published npm package:
+
+```json
+{
+  "@jshookmcp/extension-sdk": "^0.1.3"
+}
+```
+
+## Install and build
+
+```bash
+pnpm install
+pnpm run build
+pnpm run check
+```
+
+## Loading behavior
+
+`jshook` discovers both `workflow.ts` and `dist/workflow.js`, but when both exist it prefers the generated JavaScript entry.
+
+Recommended workflow:
+
+1. edit `workflow.ts`
+2. run `pnpm run build`
+3. let `jshook` load `dist/workflow.js`
+
+Do **not** commit `dist/`.
+
+## Load the workflow into jshook
+
+Set:
+
+```bash
+MCP_WORKFLOW_ROOTS=<path-to-cloned-jshook_workflow_template>
+```
+
+Then run inside `jshook`:
+
+1. `extensions_reload`
+2. `extensions_list`
+3. `list_extension_workflows`
+4. `run_extension_workflow`
+
+## Configuration prefix
+
+The template uses:
+
+```text
+workflows.templateCapture.*
+```
+
+Rename that prefix early when adapting the template for real use.
+
+## Git hygiene
+
+Keep this repo focused on source and docs.
+Do not commit:
+
+- `dist/`
+- `node_modules/`
+- `.env`
+- runtime artifacts
+- screenshots
+- local sessions
+- host-specific temp output
+
+## What to change first
+
+1. replace `workflowId` and `displayName`
+2. rename the config prefix
+3. keep state-mutating steps serialized
+4. keep read-only collection steps parallel where safe
+5. validate the workflow through `extensions_reload` and `list_extension_workflows`

package/workflows/anti-bot-diagnoser/docs/agent-recipes.md

@@ -0,0 +1,44 @@
+# Agent Recipes for `jshook_workflow_template`
+
+## Core rule
+
+- parallelize reads, not shared page state mutations
+- let the main agent keep the active browser session
+- use subagents for sidecar analysis and report drafting
+
+## Recipe 1: run workflow, then delegate analysis
+
+Recommended split:
+
+- main agent
+  - `run_extension_workflow`
+  - optional `network_get_response_body`
+- subagent
+  - classify endpoints
+  - summarize auth and session artifacts
+  - draft report output
+
+## Recipe 2: main agent navigates, subagent reviews outputs
+
+Recommended split:
+
+- main agent
+  - `page_navigate`
+  - page actions
+  - `network_get_requests`
+- subagent
+  - endpoint matrix
+  - auth header and signature review
+  - next-step probing suggestions
+
+## Recipe 3: when to use parallel tool calls
+
+Good read-only candidates:
+
+- `extensions_list`
+- `search_tools`
+- `page_get_local_storage`
+- `page_get_cookies`
+- `console_get_logs`
+
+Avoid parallelizing any action that changes the current page state.

package/workflows/anti-bot-diagnoser/meta.yaml

@@ -0,0 +1,6 @@
+name: anti-bot-diagnoser
+description: JSHook workflow for anti-bot-diagnoser
+author: vmoranv
+tags:
+  - workflow
+  - anti-bot-diagnoser

package/workflows/anti-bot-diagnoser/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "jshook-workflow-template",
+  "private": true,
+  "version": "0.1.0",
+  "description": "Standalone template repository for building jshook workflows.",
+  "type": "module",
+  "packageManager": "pnpm@10.28.2",
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "check": "tsc -p tsconfig.json --noEmit"
+  },
+  "dependencies": {
+    "@jshookmcp/extension-sdk": "^0.3.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.3.0",
+    "typescript": "^5.9.3"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  }
+}

package/workflows/anti-bot-diagnoser/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "noEmit": false,
+    "outDir": "dist",
+    "rootDir": ".",
+    "strict": true,
+    "skipLibCheck": true,
+    "types": ["node"]
+  },
+  "include": ["workflow.ts"],
+  "exclude": ["dist", "node_modules"]
+}

package/workflows/anti-bot-diagnoser/workflow.ts

@@ -0,0 +1,224 @@
+import {
+  createWorkflow,
+  type WorkflowExecutionContext,
+  SequenceNodeBuilder,
+} from '@jshookmcp/extension-sdk/workflow';
+
+const workflowId = 'workflow.anti-bot-diagnoser.v1';
+
+/**
+ * Anti-Bot Diagnoser — Reverse Mission Workflow
+ *
+ * Differential analysis to detect bot-detection mechanisms:
+ *   1. Creates a baseline fingerprint (normal browser context)
+ *   2. Creates a stealth fingerprint (stealth executor)
+ *   3. Compares both against known detection probes
+ *   4. Identifies specific detection points (webdriver, CDP, timing, canvas, etc.)
+ *   5. Produces a detection map and remediation hints
+ *   6. Records evidence for the diagnostic session
+ */
+export default createWorkflow(workflowId, 'Anti-Bot Diagnoser')
+  .description(
+    'Compares normal vs stealth browser fingerprints, identifies bot-detection triggers (webdriver, CDP, canvas, WebRTC, timing), and produces a detection report with remediation hints.',
+  )
+  .tags([
+    'reverse',
+    'antibot',
+    'stealth',
+    'fingerprint',
+    'detection',
+    'webdriver',
+    'mission',
+  ])
+  .timeoutMs(12 * 60_000)
+  .defaultMaxConcurrency(2)
+  .buildGraph((ctx: WorkflowExecutionContext) => {
+    const prefix = 'workflows.antiBotDiagnoser';
+
+    // ── Config ──────────────────────────────────────────────────────
+    const url = String(ctx.getConfig(`${prefix}.url`, 'https://example.com'));
+    const waitUntil = String(ctx.getConfig(`${prefix}.waitUntil`, 'networkidle0'));
+    const probeCategories = String(
+      ctx.getConfig(
+        `${prefix}.probeCategories`,
+        'webdriver,navigator,timing,canvas,webgl,webrtc,audio,fonts,plugins,permissions',
+      ),
+    );
+    const maxConcurrency = Number(ctx.getConfig(`${prefix}.parallel.maxConcurrency`, 2));
+    const stealthMode = String(ctx.getConfig(`${prefix}.stealthMode`, 'patchright'));
+
+    const root = new SequenceNodeBuilder('anti-bot-diagnoser-root');
+
+    root
+      // ── Phase 1: Enable Network & Navigate ────────────────────────
+      .tool('enable-network', 'network_enable', {
+        input: { enableExceptions: true },
+      })
+      .tool('navigate', 'page_navigate', {
+        input: { url, waitUntil },
+      })
+
+      // ── Phase 2: Baseline Fingerprint (Normal) ────────────────────
+      .tool('fingerprint-baseline', 'page_evaluate', {
+        input: {
+          expression: `
+            (function() {
+              const probes = {};
+              // webdriver
+              probes.webdriver = navigator.webdriver;
+              probes.webdriverDefined = 'webdriver' in navigator;
+              // navigator properties
+              probes.userAgent = navigator.userAgent;
+              probes.platform = navigator.platform;
+              probes.languages = navigator.languages;
+              probes.hardwareConcurrency = navigator.hardwareConcurrency;
+              probes.deviceMemory = navigator.deviceMemory;
+              // timing
+              probes.timingResolution = (() => {
+                const t0 = performance.now();
+                for (let i = 0; i < 1000; i++) performance.now();
+                return performance.now() - t0;
+              })();
+              // canvas
+              probes.canvasFingerprint = (() => {
+                const c = document.createElement('canvas');
+                c.width = 200; c.height = 50;
+                const ctx = c.getContext('2d');
+                if (!ctx) return null;
+                ctx.textBaseline = 'top';
+                ctx.font = '14px Arial';
+                ctx.fillText('probe', 2, 2);
+                return c.toDataURL().slice(0, 100);
+              })();
+              // chrome
+              probes.chromeRuntime = typeof chrome !== 'undefined' && !!chrome.runtime;
+              // permissions
+              probes.permissionsQuery = typeof navigator.permissions !== 'undefined';
+              // plugins
+              probes.pluginCount = navigator.plugins ? navigator.plugins.length : -1;
+              return probes;
+            })()
+          `,
+        },
+      })
+
+      // ── Phase 3: Parallel Detection Checks ────────────────────────
+      .parallel('detection-checks', (p) => {
+        p.maxConcurrency(maxConcurrency)
+          .failFast(false)
+          // Check CDP leak
+          .tool('check-cdp-leak', 'stealth_check_cdp_leak', {
+            input: {},
+          })
+          // Check webdriver property
+          .tool('check-webdriver', 'stealth_check_webdriver', {
+            input: {},
+          })
+          // Check automation flags
+          .tool('check-automation-flags', 'stealth_check_automation', {
+            input: {},
+          })
+          // Run all stealth probes
+          .tool('run-stealth-probes', 'stealth_run_probes', {
+            input: { categories: probeCategories },
+          });
+      })
+
+      // ── Phase 4: Stealth Mode Fingerprint ─────────────────────────
+      .tool('switch-stealth', 'browser_set_stealth_mode', {
+        input: { mode: stealthMode },
+      })
+      .tool('navigate-stealth', 'page_navigate', {
+        input: { url, waitUntil },
+      })
+      .tool('fingerprint-stealth', 'page_evaluate', {
+        input: {
+          expression: `
+            (function() {
+              const probes = {};
+              probes.webdriver = navigator.webdriver;
+              probes.webdriverDefined = 'webdriver' in navigator;
+              probes.userAgent = navigator.userAgent;
+              probes.platform = navigator.platform;
+              probes.chromeRuntime = typeof chrome !== 'undefined' && !!chrome.runtime;
+              probes.pluginCount = navigator.plugins ? navigator.plugins.length : -1;
+              return probes;
+            })()
+          `,
+        },
+      })
+
+      // ── Phase 5: Differential Analysis ────────────────────────────
+      .tool('compute-diff', 'console_execute', {
+        input: {
+          expression: `
+            (function() {
+              return {
+                analysis: 'differential_fingerprint_complete',
+                hint: 'Compare baseline vs stealth results in evidence graph',
+              };
+            })()
+          `,
+        },
+      })
+
+      // ── Phase 6: Detection Report ─────────────────────────────────
+      .tool('generate-report', 'stealth_generate_report', {
+        input: {
+          includeRemediation: true,
+        },
+      })
+
+      // ── Phase 7: Evidence Recording ───────────────────────────────
+      .tool('create-evidence-session', 'instrumentation_session_create', {
+        input: {
+          name: `antibot-diagnosis-${new Date().toISOString().slice(0, 10)}`,
+          metadata: { url, workflowId, stealthMode },
+        },
+      })
+      .tool('record-artifact', 'instrumentation_artifact_record', {
+        input: {
+          type: 'antibot_report',
+          label: `Anti-bot diagnosis for ${url}`,
+          metadata: { url, probeCategories, stealthMode },
+        },
+      })
+
+      // ── Phase 8: Session Insight ──────────────────────────────────
+      .tool('emit-insight', 'append_session_insight', {
+        input: {
+          insight: JSON.stringify({
+            status: 'anti_bot_diagnoser_complete',
+            workflowId,
+            url,
+            probeCategories,
+            stealthMode,
+          }),
+        },
+      });
+
+    return root;
+  })
+  .onStart((ctx) => {
+    ctx.emitMetric('workflow_runs_total', 1, 'counter', {
+      workflowId,
+      mission: 'anti_bot_diagnoser',
+      stage: 'start',
+    });
+  })
+  .onFinish((ctx) => {
+    ctx.emitMetric('workflow_runs_total', 1, 'counter', {
+      workflowId,
+      mission: 'anti_bot_diagnoser',
+      stage: 'finish',
+    });
+  })
+  .onError((ctx, error) => {
+    ctx.emitMetric('workflow_errors_total', 1, 'counter', {
+      workflowId,
+      mission: 'anti_bot_diagnoser',
+      stage: 'error',
+      error: error.name,
+    });
+  })
+  .build();

package/workflows/api-openapi-probe/.jshook-install.json

@@ -0,0 +1,14 @@
+{
+  "version": 1,
+  "kind": "workflow",
+  "slug": "api-openapi-probe",
+  "id": "workflow.api-openapi-probe.v1",
+  "source": {
+    "type": "git",
+    "repo": "https://github.com/vmoranv/jshook_workflow_api_openapi_probe",
+    "ref": "main",
+    "commit": "94e1573fef500945d2da18f1cadda68b9187f22f",
+    "subpath": ".",
+    "entry": "workflow.ts"
+  }
+}

package/workflows/api-openapi-probe/meta.yaml

@@ -0,0 +1,6 @@
+name: api-openapi-probe
+description: JSHook workflow for api-openapi-probe
+author: vmoranv
+tags:
+  - workflow
+  - api-openapi-probe

package/workflows/api-openapi-probe/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "jshook-workflow-api-openapi-probe",
+  "private": true,
+  "version": "0.1.0",
+  "description": "jshookmcp workflow: api-openapi-probe",
+  "type": "module",
+  "packageManager": "pnpm@10.28.2",
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "check": "tsc -p tsconfig.json --noEmit"
+  },
+  "dependencies": {
+    "@jshookmcp/extension-sdk": "^0.3.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.3.0",
+    "typescript": "^5.9.3"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  }
+}