@jshookmcp/jshook 0.2.5 → 0.2.6

package/workflows/temp-mail-open-latest/workflow.ts

@@ -0,0 +1,136 @@
+import type { WorkflowContract } from '@jshookmcp/extension-sdk/workflow';
+import { toolNode, sequenceNode, branchNode } from '@jshookmcp/extension-sdk/workflow';
+
+const workflowId = 'workflow.temp-mail-open-latest.v1';
+
+const tempMailOpenLatestWorkflow: WorkflowContract = {
+  kind: 'workflow-contract',
+  version: 1,
+  id: workflowId,
+  displayName: 'Temp Mail Open Latest',
+  description:
+    'Navigate a temporary mailbox, optionally refresh it, and open the latest relevant message using configurable selectors and matching rules.',
+  tags: ['workflow', 'mailbox', 'email', 'temp-mail', 'automation'],
+  timeoutMs: 3 * 60_000,
+  defaultMaxConcurrency: 1,
+
+  build(ctx) {
+    const prefix = 'workflows.tempMailOpenLatest';
+    const mailboxUrl = ctx.getConfig<string>(`${prefix}.mailboxUrl`, 'https://example.com/mailbox');
+    const waitUntil = ctx.getConfig<string>(`${prefix}.waitUntil`, 'domcontentloaded');
+    const readySelector = ctx.getConfig<string>(`${prefix}.readySelector`, 'body');
+    const timeoutMs = ctx.getConfig<number>(`${prefix}.timeoutMs`, 60_000);
+    const refreshSelector = ctx.getConfig<string>(`${prefix}.refreshSelector`, '');
+    const refreshWaitMs = ctx.getConfig<number>(`${prefix}.refreshWaitMs`, 1500);
+    const itemSelector = ctx.getConfig<string>(`${prefix}.itemSelector`, 'a[href]');
+    const hrefIncludes = ctx.getConfig<string>(`${prefix}.hrefIncludes`, '/mail/view/');
+    const hrefRegex = ctx.getConfig<string>(`${prefix}.hrefRegex`, '');
+    const textIncludes = ctx.getConfig<string>(`${prefix}.textIncludes`, '');
+    const textRegex = ctx.getConfig<string>(`${prefix}.textRegex`, '');
+    const openOrder = ctx.getConfig<string>(`${prefix}.openOrder`, 'first');
+
+    return sequenceNode('temp-mail-open-latest-root')
+      .step(toolNode('navigate-mailbox', 'page_navigate').input({
+        url: mailboxUrl, waitUntil, timeout: timeoutMs, enableNetworkMonitoring: true,
+      }))
+      .step(toolNode('wait-mailbox-ready', 'page_wait_for_selector').input({
+        selector: readySelector, timeout: timeoutMs,
+      }))
+      .step(branchNode('maybe-refresh-mailbox', 'temp_mail_open_latest_enable_refresh')
+        .predicateFn(() => Boolean(refreshSelector))
+        .whenTrue(sequenceNode('refresh-sequence')
+          .step(toolNode('refresh-mailbox', 'page_evaluate').input({
+            code: `(function(){
+              const target = document.querySelector(${JSON.stringify(refreshSelector)});
+              if (!target) {
+                return { refreshed: false, reason: 'refresh_target_not_found', selector: ${JSON.stringify(refreshSelector)} };
+              }
+              if (typeof target.click === 'function') {
+                target.click();
+                return { refreshed: true, selector: ${JSON.stringify(refreshSelector)} };
+              }
+              return { refreshed: false, reason: 'refresh_target_not_clickable', selector: ${JSON.stringify(refreshSelector)} };
+            })()`,
+          }))
+          .step(toolNode('wait-after-refresh', 'page_evaluate')
+            .input({ code: `new Promise(resolve => setTimeout(() => resolve({ waitedMs: ${Math.max(0, refreshWaitMs)} }), ${Math.max(0, refreshWaitMs)}))` })
+            .timeout(Math.max(5_000, refreshWaitMs + 2_000))))
+        .whenFalse(toolNode('skip-refresh-mailbox', 'console_execute').input({
+          expression: '({ skipped: true, step: "refresh_mailbox", reason: "refreshSelector not configured" })',
+        })))
+      .step(toolNode('open-latest-relevant-mail', 'page_evaluate').input({
+        code: `(function(){
+          const anchors = Array.from(document.querySelectorAll(${JSON.stringify(itemSelector)}));
+          const hrefIncludes = ${JSON.stringify(hrefIncludes)};
+          const hrefRegexRaw = ${JSON.stringify(hrefRegex)};
+          const textIncludes = ${JSON.stringify(textIncludes)};
+          const textRegexRaw = ${JSON.stringify(textRegex)};
+          const order = ${JSON.stringify(openOrder)};
+
+          const hrefRegex = hrefRegexRaw ? new RegExp(hrefRegexRaw, 'i') : null;
+          const textRegex = textRegexRaw ? new RegExp(textRegexRaw, 'i') : null;
+
+          const matches = anchors.filter((anchor) => {
+            const href = anchor.href || anchor.getAttribute('href') || '';
+            const text = (anchor.textContent || '').trim();
+            if (hrefIncludes && !href.includes(hrefIncludes)) return false;
+            if (hrefRegex && !hrefRegex.test(href)) return false;
+            if (textIncludes && !text.toLowerCase().includes(textIncludes.toLowerCase())) return false;
+            if (textRegex && !textRegex.test(text)) return false;
+            return true;
+          });
+
+          if (matches.length === 0) {
+            return {
+              opened: false,
+              reason: 'matching_mail_item_not_found',
+              totalAnchors: anchors.length,
+              filters: { hrefIncludes, hrefRegexRaw, textIncludes, textRegexRaw, order }
+            };
+          }
+
+          const selected = order === 'last' ? matches[matches.length - 1] : matches[0];
+          const href = selected.href || selected.getAttribute('href') || '';
+          const text = (selected.textContent || '').trim();
+          if (!href) {
+            return {
+              opened: false,
+              reason: 'selected_item_missing_href',
+              text,
+              matchCount: matches.length
+            };
+          }
+
+          window.location.href = href;
+          return {
+            opened: true, href, text,
+            matchCount: matches.length,
+            totalAnchors: anchors.length,
+            order
+          };
+        })()`,
+      }))
+      .step(toolNode('emit-summary', 'console_execute').input({
+        expression: `(${JSON.stringify({
+          workflowId, mailboxUrl, readySelector, refreshSelector,
+          itemSelector, hrefIncludes, hrefRegex, textIncludes, textRegex, openOrder,
+          status: 'temp_mail_open_latest_complete',
+        })})`,
+      }))
+      .build();
+  },
+
+  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 });
+  },
+};
+
+export default tempMailOpenLatestWorkflow;

package/workflows/template/.jshook-install.json

@@ -0,0 +1,14 @@
+{
+  "version": 1,
+  "kind": "workflow",
+  "slug": "template",
+  "id": "workflow.template.v1",
+  "source": {
+    "type": "git",
+    "repo": "https://github.com/vmoranv/jshook_workflow_template",
+    "ref": "main",
+    "commit": "422db61",
+    "subpath": ".",
+    "entry": "workflow.ts"
+  }
+}

package/workflows/template/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/template/README.md

@@ -0,0 +1,45 @@
+# jshook Workflow Template
+
+A minimal template for building jshook MCP workflows.
+
+## What's Included
+
+- `workflow.ts` - Workflow definition
+- `meta.yaml` - Extension metadata for registry
+- `.gitignore` - Standard ignores for jshook projects
+
+## Quick Start
+
+```bash
+pnpm install
+pnpm run build
+pnpm run check
+```
+
+## Files Explained
+
+| File | Purpose |
+|------|---------|
+| `workflow.ts` | Workflow implementation |
+| `package.json` | Dependencies (uses @jshookmcp/extension-sdk) |
+| `tsconfig.json` | TypeScript configuration |
+| `meta.yaml` | Registry metadata (name, description, author, tags) |
+
+## Local Testing
+
+```bash
+export MCP_WORKFLOW_ROOTS=$(pwd)
+# In jshook: extensions_reload, then list_extension_workflows
+```
+
+## Publishing
+
+1. Push to GitHub (public repo)
+2. Ensure `meta.yaml` exists with valid metadata
+3. Create issue at vmoranv/jshookmcpextension (see docs/SKILL.md for agent usage)
+
+## See Also
+
+- [docs/SKILL.md](docs/SKILL.md) - Agent usage documentation
+- [jshookmcp](https://github.com/vmoranv/jshookmcp) - Main repository
+- [Extension Registry](https://github.com/vmoranv/jshookmcpextension) - Registry issues

package/workflows/template/docs/SKILL.md

@@ -0,0 +1,111 @@
+# jshook Workflow Template - Agent Skill Documentation
+
+## For Agents Using This Template
+
+This template provides a reusable workflow scaffold for jshook MCP.
+
+## Workflow ID
+
+```
+workflow.template.v1
+```
+
+## Available Configuration
+
+```yaml
+workflows.template.*
+```
+
+## Input Parameters
+
+```typescript
+{
+  targetUrl?: string,      // Target URL to analyze (default: current page)
+  collectAuth?: boolean,   // Extract auth credentials (default: true)
+  collectLinks?: boolean,  // Collect page links (default: true)
+}
+```
+
+## Output Structure
+
+```typescript
+{
+  url: string,             // Analyzed URL
+  timestamp: string,       // Analysis timestamp
+  auth: {                  // Extracted auth (if collectAuth=true)
+    tokens: array,
+    cookies: array,
+    headers: array
+  },
+  links: array,            // Page links (if collectLinks=true)
+  localStorage: object,    // LocalStorage contents
+  requests: array          // Network requests captured
+}
+```
+
+## SDK Functions Used
+
+```typescript
+import { defineWorkflow } from '@jshookmcp/extension-sdk';
+
+export default defineWorkflow({
+  id: 'workflow.template.v1',
+  name: 'Template Workflow',
+  description: 'A sample workflow',
+  
+  async execute(ctx, config) {
+    // Step 1: Enable network monitoring
+    await ctx.network_enable();
+    
+    // Step 2: Navigate
+    await ctx.page_navigate(config.targetUrl);
+    
+    // Step 3: Parallel collection
+    const [storage, cookies, requests] = await Promise.all([
+      ctx.page_get_local_storage(),
+      ctx.page_get_cookies(),
+      ctx.network_get_requests()
+    ]);
+    
+    // Step 4: Extract auth
+    const auth = await ctx.network_extract_auth();
+    
+    return { storage, cookies, requests, auth };
+  },
+});
+```
+
+## Parallel Read Pattern
+
+Safe to parallelize (Promise.all):
+- `page_get_local_storage`
+- `page_get_cookies`
+- `network_get_requests`
+- `page_get_all_links`
+
+Do NOT parallelize:
+- `page_click` + `page_type` (state mutations)
+- Multiple `page_navigate` calls
+
+## Build & Verify
+
+```bash
+pnpm install
+pnpm run build   # Outputs dist/workflow.js
+pnpm run check   # TypeScript type check
+```
+
+## Load Into jshook
+
+1. Set env: `MCP_WORKFLOW_ROOTS=/path/to/template`
+2. In jshook: `extensions_reload`
+3. Verify: `list_extension_workflows` shows the workflow
+4. Run: `run_extension_workflow --workflow-id workflow.template.v1`
+
+## Example Invocation
+
+```
+run_extension_workflow 
+  --workflow-id workflow.template.v1 
+  --config '{"targetUrl":"https://example.com","collectAuth":true}'
+```

package/workflows/template/meta.yaml

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

package/workflows/template/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"
+  }
+}