@jshookmcp/jshook 0.2.3 → 0.2.6

package/workflows/template/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/template/workflow.ts

@@ -0,0 +1,73 @@
+import {
+  createWorkflow,
+  type WorkflowExecutionContext,
+  SequenceNodeBuilder,
+  toolNode,
+} from '@jshookmcp/extension-sdk/workflow';
+
+const workflowId = 'workflow.template-capture.v1';
+
+export default createWorkflow(workflowId, 'Template Capture Workflow')
+  .description(
+    'TypeScript-first MVP workflow that enables network capture, navigates to a page, collects surface data in parallel, extracts auth, and emits a summary.',
+  )
+  .tags(['workflow', 'template', 'parallel', 'capture'])
+  .timeoutMs(10 * 60_000)
+  .defaultMaxConcurrency(4)
+  .buildGraph((ctx: WorkflowExecutionContext) => {
+    const prefix = 'workflows.templateCapture';
+    const url = String(ctx.getConfig(`${prefix}.url`, 'https://example.com'));
+    const waitUntil = String(ctx.getConfig(`${prefix}.waitUntil`, 'domcontentloaded'));
+    const requestTail = Number(ctx.getConfig(`${prefix}.requestTail`, 20));
+    const maxConcurrency = Number(ctx.getConfig(`${prefix}.parallel.maxConcurrency`, 4));
+    const collectConsoleLogs = Boolean(ctx.getConfig(`${prefix}.collectConsoleLogs`, true));
+    const logLimit = Number(ctx.getConfig(`${prefix}.consoleLogLimit`, 50));
+
+    const root = new SequenceNodeBuilder('template-capture-root');
+
+    root
+      .tool('enable-network', 'network_enable', { input: { enableExceptions: true } })
+      .tool('navigate', 'page_navigate', { input: { url, waitUntil } })
+      .parallel('collect-surface', (p) => {
+        p.maxConcurrency(maxConcurrency)
+          .failFast(false)
+          .tool('collect-local-storage', 'page_get_local_storage')
+          .tool('collect-cookies', 'page_get_cookies')
+          .tool('collect-requests', 'network_get_requests', { input: { tail: requestTail } })
+          .tool('collect-links', 'page_get_all_links');
+
+        if (collectConsoleLogs) {
+          p.tool('collect-console-logs', 'console_get_logs', { input: { limit: logLimit } });
+        }
+      })
+      .tool('extract-auth', 'network_extract_auth', { input: { minConfidence: 0.4 } })
+      .tool('emit-summary', 'console_execute', {
+        input: {
+          expression: `(${JSON.stringify({
+            status: 'template_capture_complete',
+            workflowId,
+            url,
+            waitUntil,
+            requestTail,
+            maxConcurrency,
+            collectConsoleLogs,
+          })})`,
+        },
+      });
+
+    return root;
+  })
+  .onStart((ctx) => {
+    ctx.emitMetric('workflow_runs_total', 1, 'counter', { workflowId, stage: 'start' });
+  })
+  .onFinish((ctx) => {
+    ctx.emitMetric('workflow_runs_total', 1, 'counter', { workflowId, stage: 'finish' });
+  })
+  .onError((ctx, error) => {
+    ctx.emitMetric('workflow_errors_total', 1, 'counter', {
+      workflowId,
+      stage: 'error',
+      error: error.name,
+    });
+  })
+  .build();

package/workflows/web-api-capture-session/.jshook-install.json

@@ -0,0 +1,14 @@
+{
+  "version": 1,
+  "kind": "workflow",
+  "slug": "web-api-capture-session",
+  "id": "workflow.web-api-capture-session.v1",
+  "source": {
+    "type": "git",
+    "repo": "https://github.com/vmoranv/jshook_workflow_web_api_capture_session",
+    "ref": "main",
+    "commit": "087d1ee8d1724b11df0a13b3efb699e8edf71fdd",
+    "subpath": ".",
+    "entry": "workflow.ts"
+  }
+}

package/workflows/web-api-capture-session/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/web-api-capture-session/README.md

@@ -0,0 +1,64 @@
+# web-api-capture-session workflow
+
+Declarative workflow for full-chain web API capture: navigate to a target page, optionally replay interaction steps, collect network activity, extract auth signals, and optionally export HAR output.
+
+## Entry File
+
+- `workflow.ts`
+
+## Workflow ID
+
+- `workflow.web-api-capture-session.v1`
+
+## Structure
+
+This workflow translates the built-in `handleWebApiCaptureSession` orchestration into a declarative graph:
+
+- `network_enable` to start request and exception capture
+- `console_inject_fetch_interceptor` and `console_inject_xhr_interceptor` to persist frontend traffic
+- `page_navigate` to load the target page
+- Optional action branches for `page_click`, `page_type`, and `page_evaluate`
+- `page_evaluate` delay step to let async requests settle
+- `network_get_stats` and `network_get_requests` for request collection
+- `network_extract_auth` for auth/token discovery
+- Optional `network_export_har` branch for artifact export
+- `console_execute` summary step for downstream runners
+
+## Tools Used
+
+- `network_enable`
+- `console_inject_fetch_interceptor`
+- `console_inject_xhr_interceptor`
+- `page_navigate`
+- `page_click`
+- `page_type`
+- `page_evaluate`
+- `network_get_stats`
+- `network_get_requests`
+- `network_extract_auth`
+- `network_export_har`
+- `console_execute`
+
+## Config
+
+- `workflows.webApiCapture.url`
+- `workflows.webApiCapture.waitUntil`
+- `workflows.webApiCapture.enableClickStep`
+- `workflows.webApiCapture.clickSelector`
+- `workflows.webApiCapture.enableTypeStep`
+- `workflows.webApiCapture.typeSelector`
+- `workflows.webApiCapture.typeText`
+- `workflows.webApiCapture.enableEvaluateStep`
+- `workflows.webApiCapture.evaluateExpression`
+- `workflows.webApiCapture.waitAfterActionsMs`
+- `workflows.webApiCapture.exportHar`
+- `workflows.webApiCapture.harOutputPath`
+
+## Local Validation
+
+1. Run `pnpm install`.
+2. Run `pnpm typecheck`.
+3. Put this repo under a configured `workflows/` extension root.
+4. Run `extensions_reload` in `jshookmcp`.
+5. Confirm the workflow appears in `extensions_list`.
+6. Execute the workflow with your runner and verify request capture, auth extraction, and optional HAR export.

package/workflows/web-api-capture-session/meta.yaml

@@ -0,0 +1,4 @@
+name: web-api-capture-session
+description: Declarative workflow for navigation, action replay, request capture, auth extraction, and HAR/report export.
+author: vmoranv
+source_repo: https://github.com/vmoranv/jshook_workflow_web_api_capture_session

package/workflows/web-api-capture-session/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "@jshookmcpextension/workflow-web-api-capture-session",
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc --noEmit -p tsconfig.json"
+  },
+  "type": "module",
+  "dependencies": {
+    "@jshookmcp/extension-sdk": "^0.3.0",
+    "@modelcontextprotocol/sdk": "^1.27.1",
+    "dotenv": "^17.3.1"
+  },
+  "version": "0.1.0",
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.3.0",
+    "typescript": "^5.9.3"
+  },
+  "private": true,
+  "packageManager": "pnpm@10.28.2"
+}

package/workflows/web-api-capture-session/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "lib": ["ES2022"],
+    "strict": true,
+    "skipLibCheck": true,
+    "esModuleInterop": true,
+    "resolveJsonModule": true,
+    "rootDir": ".",
+    "outDir": "dist"
+  },
+  "include": ["workflow.ts"],
+  "exclude": ["dist", "node_modules"]
+}

package/workflows/web-api-capture-session/workflow.ts

@@ -0,0 +1,124 @@
+import {
+  createWorkflow,
+  type WorkflowExecutionContext,
+  SequenceNodeBuilder,
+} from '@jshookmcp/extension-sdk/workflow';
+
+const workflowId = 'workflow.web-api-capture-session.v1';
+
+function isoTimestampForFile(): string {
+  return new Date().toISOString().replace(/[:.]/g, '-').slice(0, 19);
+}
+
+export default createWorkflow(workflowId, 'Web API Capture Session')
+  .description(
+    'Delegate to the built-in web_api_capture_session tool using only valid action types (click/type/wait/evaluate), then emit a concise summary.',
+  )
+  .tags(['workflow', 'capture', 'network', 'auth', 'har', 'reverse'])
+  .timeoutMs(10 * 60_000)
+  .defaultMaxConcurrency(1)
+  .buildGraph((ctx) => {
+    const prefix = 'workflows.webApiCapture';
+    const url = ctx.getConfig<string>(`${prefix}.url`, 'https://example.com');
+    const waitUntil = ctx.getConfig<string>(`${prefix}.waitUntil`, 'domcontentloaded');
+    const waitAfterActionsMs = ctx.getConfig<number>(`${prefix}.waitAfterActionsMs`, 1500);
+
+    const enableTypeStep = ctx.getConfig<boolean>(`${prefix}.enableTypeStep`, false);
+    const typeSelector = ctx.getConfig<string>(`${prefix}.typeSelector`, "input[name='query']");
+    const typeText = ctx.getConfig<string>(`${prefix}.typeText`, 'capture me');
+
+    const enableClickStep = ctx.getConfig<boolean>(`${prefix}.enableClickStep`, false);
+    const clickSelector = ctx.getConfig<string>(`${prefix}.clickSelector`, 'button[data-capture]');
+
+    const enableWaitStep = ctx.getConfig<boolean>(`${prefix}.enableWaitStep`, false);
+    const waitSelector = ctx.getConfig<string>(`${prefix}.waitSelector`, '');
+    const waitText = ctx.getConfig<string>(`${prefix}.waitText`, '');
+    const waitDelayMs = ctx.getConfig<number>(`${prefix}.waitDelayMs`, 0);
+
+    const enableEvaluateStep = ctx.getConfig<boolean>(`${prefix}.enableEvaluateStep`, false);
+    const evaluateExpression = ctx.getConfig<string>(
+      `${prefix}.evaluateExpression`,
+      'window.__captureProbe = true',
+    );
+
+    const exportHar = ctx.getConfig<boolean>(`${prefix}.exportHar`, true);
+    const exportReport = ctx.getConfig<boolean>(`${prefix}.exportReport`, false);
+    const harOutputPath = ctx.getConfig<string>(
+      `${prefix}.harOutputPath`,
+      `workflow-smoke-capture-${isoTimestampForFile()}.har`,
+    );
+    const reportOutputPath = ctx.getConfig<string>(
+      `${prefix}.reportOutputPath`,
+      `workflow-smoke-capture-report-${isoTimestampForFile()}.md`,
+    );
+
+    const actions: Array<Record<string, unknown>> = [];
+    if (enableTypeStep) {
+      actions.push({ type: 'type', selector: typeSelector, text: typeText });
+    }
+    if (enableClickStep) {
+      actions.push({ type: 'click', selector: clickSelector });
+    }
+    if (enableWaitStep) {
+      const waitAction: Record<string, unknown> = { type: 'wait' };
+      if (waitSelector) waitAction['selector'] = waitSelector;
+      if (waitText) waitAction['text'] = waitText;
+      if (waitDelayMs > 0) waitAction['delayMs'] = waitDelayMs;
+      actions.push(waitAction);
+    }
+    if (enableEvaluateStep) {
+      actions.push({ type: 'evaluate', expression: evaluateExpression });
+    }
+
+    const root = new SequenceNodeBuilder('web-api-capture-session-root');
+
+    root.tool('capture-session', 'web_api_capture_session', {
+      input: {
+        url,
+        waitUntil,
+        actions,
+        waitAfterActionsMs,
+        exportHar,
+        exportReport,
+        harOutputPath,
+        reportOutputPath,
+      },
+    });
+
+    root.tool('capture-summary', 'console_execute', {
+      input: {
+        expression: `(${JSON.stringify({
+          status: 'web_api_capture_sequence_complete',
+          workflowId,
+          url,
+          waitUntil,
+          actions,
+          exportHar,
+          exportReport,
+          harOutputPath,
+          reportOutputPath,
+        })})`,
+      },
+    });
+
+    return root;
+  })
+  .onStart((ctx) => {
+    ctx.emitMetric('workflow_runs_total', 1, 'counter', {
+      workflowId,
+      stage: 'start',
+    });
+  })
+  .onFinish((ctx) => {
+    ctx.emitMetric('workflow_runs_total', 1, 'counter', {
+      workflowId,
+      stage: 'finish',
+    });
+  })
+  .onError((ctx, error) => {
+    ctx.emitMetric('workflow_errors_total', 1, 'counter', {
+      workflowId,
+      error: error.name,
+    });
+  })
+  .build();

package/workflows/ws-protocol-lifter/.jshook-install.json

@@ -0,0 +1,14 @@
+{
+  "version": 1,
+  "kind": "workflow",
+  "slug": "ws-protocol-lifter",
+  "id": "workflow.ws-protocol-lifter.v1",
+  "source": {
+    "type": "git",
+    "repo": "https://github.com/vmoranv/jshook_workflow_ws_protocol_lifter",
+    "ref": "main",
+    "commit": "423d61d2b0f678e7a6cdffe39c73b2d9bbd385ad",
+    "subpath": ".",
+    "entry": "workflow.ts"
+  }
+}

package/workflows/ws-protocol-lifter/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/ws-protocol-lifter/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/ws-protocol-lifter/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/ws-protocol-lifter/meta.yaml

@@ -0,0 +1,6 @@
+name: ws-protocol-lifter
+description: JSHook workflow for ws-protocol-lifter
+author: vmoranv
+tags:
+  - workflow
+  - ws-protocol-lifter

package/workflows/ws-protocol-lifter/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/ws-protocol-lifter/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"]
+}