@wowok/agent-mcp 2.6.0 → 2.6.1

package/dist/tools/wip-deploy-assist.js

@@ -0,0 +1,278 @@
+export function classifyWipPath(path) {
+    if (!path || typeof path !== "string") {
+        return {
+            type: "unknown",
+            is_local: false,
+            is_network: false,
+            description: "Empty or invalid path",
+        };
+    }
+    if (path.startsWith("data:")) {
+        return {
+            type: "data_url",
+            is_local: false,
+            is_network: true,
+            description: "Data URL — embedded content, globally reachable",
+        };
+    }
+    if (path.startsWith("ipfs://")) {
+        return {
+            type: "ipfs",
+            is_local: false,
+            is_network: true,
+            description: "IPFS URI — resolve via any public gateway",
+        };
+    }
+    const ipfsGateways = [
+        /^https?:\/\/ipfs\.io\//i,
+        /^https?:\/\/cloudflare-ipfs\.com\//i,
+        /^https?:\/\/gateway\.pinata\.cloud\//i,
+        /^https?:\/\/dweb\.link\//i,
+        /^https?:\/\/[^/]*pinata\.cloud\//i,
+    ];
+    if (ipfsGateways.some((re) => re.test(path))) {
+        return {
+            type: "ipfs",
+            is_local: false,
+            is_network: true,
+            description: "IPFS HTTP gateway URL — globally reachable",
+        };
+    }
+    if (/^https?:\/\//i.test(path)) {
+        return {
+            type: "http_url",
+            is_local: false,
+            is_network: true,
+            description: "HTTP(S) URL — globally reachable if server returns 200",
+        };
+    }
+    if (/^[A-Za-z]:[\\/]/.test(path)) {
+        return {
+            type: "local_windows",
+            is_local: true,
+            is_network: false,
+            description: "Windows local path — NOT reachable by customers/AI",
+        };
+    }
+    if (path.startsWith("/")) {
+        return {
+            type: "local_unix",
+            is_local: true,
+            is_network: false,
+            description: "Unix local path — NOT reachable by customers/AI",
+        };
+    }
+    if (path.startsWith("./") || path.startsWith("../") || path === "." || path === "..") {
+        return {
+            type: "local_relative",
+            is_local: true,
+            is_network: false,
+            description: "Relative local path — NOT reachable by customers/AI",
+        };
+    }
+    if (!path.includes("://") && !path.startsWith("data:")) {
+        return {
+            type: "local_relative",
+            is_local: true,
+            is_network: false,
+            description: "Local file path (no scheme) — NOT reachable by customers/AI",
+        };
+    }
+    return {
+        type: "unknown",
+        is_local: false,
+        is_network: false,
+        description: "Unrecognized path format",
+    };
+}
+export function getDeployOptions(localFilePath) {
+    const safePath = localFilePath.replace(/'/g, "'\\''");
+    const basename = localFilePath.split(/[\\/]/).pop() || "file.wip";
+    return [
+        {
+            name: "GitHub Pages (Recommended)",
+            description: "Upload the .wip file to a GitHub repository and serve it via GitHub Pages. " +
+                "Free, stable, HTTPS-enabled, no expiration.",
+            difficulty: "easy",
+            free: true,
+            result_url_pattern: "https://<your-username>.github.io/<repo>/<file>.wip",
+            steps: [
+                "// 1. Create a new GitHub repository (e.g., 'wowok-wip') via https://github.com/new",
+                "// 2. Make it PUBLIC so the file is world-readable.",
+                `// 3. Copy your local WIP file into the repo:`,
+                `git clone https://github.com/<your-username>/wowok-wip.git`,
+                `cp '${safePath}' wowok-wip/${basename}`,
+                `cd wowok-wip`,
+                `git add ${basename}`,
+                `git commit -m "Add WIP file"`,
+                `git push origin main`,
+                "// 4. Enable GitHub Pages: repo → Settings → Pages → Source → 'main' branch → /(root) → Save",
+                "// 5. Wait 30-60 seconds for deployment, then verify the URL is reachable:",
+                `curl -I https://<your-username>.github.io/wowok-wip/${basename}`,
+                "// 6. Update your Service on-chain with the new public URL:",
+                "//    Call onchain_operations { operation_type: 'service', data: { object: '<service-id>', sales: { op: 'set', sales: [{ ..., wip_url: 'https://...', wip_hash: '<hash>' }] } } }",
+            ],
+            notes: [
+                "If the repo already has Pages enabled on the main branch, step 4 can be skipped.",
+                "GitHub Pages serves files up to 25 MB — well above typical WIP sizes (< 1 MB).",
+                "URL is case-sensitive; ensure the filename in the URL matches exactly.",
+            ],
+        },
+        {
+            name: "IPFS via Pinata (Free gateway)",
+            description: "Upload the .wip file to IPFS through Pinata's free gateway. " +
+                "Content-addressed — the CID hash also serves as an integrity check.",
+            difficulty: "medium",
+            free: true,
+            result_url_pattern: "https://gateway.pinata.cloud/ipfs/<CID>  (or  https://ipfs.io/ipfs/<CID>)",
+            steps: [
+                "// 1. Sign up for a free Pinata account at https://app.pinata.cloud/ (1 GB free storage).",
+                "// 2. Get your API key from https://app.pinata.cloud/keys (generate a new key with 'pinFileToIPFS' scope).",
+                `// 3. Upload your local WIP file via curl:`,
+                `curl -X POST https://api.pinata.cloud/pinning/pinFileToIPFS \\`,
+                `  -H "Authorization: Bearer <YOUR_PINATA_API_KEY>" \\`,
+                `  -F "file=@'${safePath}'"`,
+                "// 4. Pinata returns JSON with 'IpfsHash' (the CID). Extract it:",
+                `//    Example response: { "IpfsHash": "QmXYZ...", "PinSize": 12345, "Timestamp": "..." }`,
+                "// 5. Verify the file is reachable via the public gateway:",
+                `curl -I https://gateway.pinata.cloud/ipfs/<CID>`,
+                "// 6. (Optional) Use ipfs://<CID> as the wip_url — the SDK resolves it.",
+                "// 7. Update your Service on-chain with the IPFS URL or CID:",
+                "//    Call onchain_operations { operation_type: 'service', data: { object: '<service-id>', sales: { op: 'set', sales: [{ ..., wip_url: 'https://gateway.pinata.cloud/ipfs/<CID>', wip_hash: '<hash>' }] } } }",
+            ],
+            notes: [
+                "Pinata free tier: 1 GB storage, 100 uploads/day — sufficient for WIP files.",
+                "For long-term durability, also pin via another gateway (e.g., nft.storage).",
+                "IPFS CIDs are content-addressed — if the file changes, the CID changes. This is a feature, not a bug.",
+            ],
+        },
+        {
+            name: "User's own website / static host",
+            description: "If you already operate a website or static host (e.g., nginx, Vercel, Netlify, Cloudflare Pages), " +
+                "upload the .wip file there and use its public URL.",
+            difficulty: "medium",
+            free: true,
+            result_url_pattern: "https://<your-domain>/<path>/<file>.wip",
+            steps: [
+                `// 1. Copy your local WIP file to your web server's static directory:`,
+                `scp '${safePath}' user@your-server:/var/www/html/wowok/${basename}`,
+                "// 2. Ensure the server sets Content-Type: application/json (or application/octet-stream) for .wip files.",
+                "//    For nginx, add to your server block:",
+                "//        location ~ \\.wip$ { default_type application/json; }",
+                "// 3. Verify the file is reachable:",
+                `curl -I https://<your-domain>/wowok/${basename}`,
+                "// 4. Update your Service on-chain with the new public URL:",
+                "//    Call onchain_operations { operation_type: 'service', data: { object: '<service-id>', sales: { op: 'set', sales: [{ ..., wip_url: 'https://<your-domain>/wowok/<file>.wip', wip_hash: '<hash>' }] } } }",
+            ],
+            notes: [
+                "Make sure CORS is permissive if the verifier fetches via browser (Access-Control-Allow-Origin: *).",
+                "Ensure HTTPS is enabled — most verifiers reject plain HTTP.",
+            ],
+        },
+        {
+            name: "Data URL embedding (small files only)",
+            description: "Embed the entire WIP file as a base64 data URL directly in the wip_url field. " +
+                "No external hosting required, but on-chain storage cost grows with file size.",
+            difficulty: "easy",
+            free: true,
+            result_url_pattern: "data:application/json;base64,<base64-encoded-content>",
+            steps: [
+                `// 1. Encode your local WIP file as a base64 data URL:`,
+                `//    On Linux/macOS:`,
+                `echo "data:application/json;base64,$(base64 -w0 '${safePath}')"`,
+                `//    On Windows (PowerShell):`,
+                `$bytes = [System.IO.File]::ReadAllBytes('${localFilePath}'); $b64 = [System.Convert]::ToBase64String($bytes); Write-Output "data:application/json;base64,$b64"`,
+                "// 2. Use the resulting data URL as the wip_url field when updating the Service.",
+                "// 3. Note: data URLs are NOT recommended for files > 50 KB due to on-chain storage cost.",
+            ],
+            notes: [
+                "Only suitable for very small WIP files (typically < 10 KB).",
+                "Data URLs cannot be updated without an on-chain transaction — content is literally embedded.",
+                "Prefer GitHub Pages or IPFS for files > 10 KB.",
+            ],
+        },
+    ];
+}
+export function analyzeWipDeployment(path) {
+    const classification = classifyWipPath(path);
+    const needsDeployment = classification.is_local;
+    let reason;
+    let options = [];
+    if (needsDeployment) {
+        reason =
+            `The WIP path '${path}' is a LOCAL ${classification.type} path. ` +
+                "Local paths stored on-chain are unreachable by customers and verifiers. " +
+                "Deploy the .wip file to a public host (GitHub Pages, IPFS, or your own website) " +
+                "and update the Service's wip_url with the public URL.";
+        options = getDeployOptions(path);
+    }
+    else if (classification.type === "http_url") {
+        reason =
+            "The WIP path is an HTTP(S) URL — verify the server returns 200. " +
+                "If the URL returns 404/403, the file may have been moved or deleted.";
+        options = [];
+    }
+    else if (classification.type === "ipfs") {
+        reason =
+            "The WIP path is an IPFS URL — verify the gateway is responsive. " +
+                "If the CID is unreachable, the file may have been unpinned.";
+        options = [];
+    }
+    else if (classification.type === "data_url") {
+        reason = "The WIP path is a data URL — content is embedded, no deployment needed.";
+        options = [];
+    }
+    else {
+        reason = `Unrecognized WIP path format: '${path}'`;
+        options = [];
+    }
+    return {
+        path,
+        classification,
+        needs_deployment: needsDeployment,
+        reason,
+        options,
+        remind_update_hash: needsDeployment,
+    };
+}
+export function formatDeployHints(suggestion) {
+    if (!suggestion.needs_deployment && suggestion.options.length === 0) {
+        return "";
+    }
+    const lines = [];
+    lines.push("=== WIP Deployment Assistance ===");
+    lines.push("");
+    lines.push(`Path: ${suggestion.path}`);
+    lines.push(`Type: ${suggestion.classification.description}`);
+    lines.push(`Reason: ${suggestion.reason}`);
+    lines.push("");
+    if (suggestion.options.length > 0) {
+        lines.push("Recommended deployment options:");
+        lines.push("");
+        for (const opt of suggestion.options) {
+            lines.push(`▶ ${opt.name} (difficulty: ${opt.difficulty}, free: ${opt.free})`);
+            lines.push(`  ${opt.description}`);
+            lines.push(`  Resulting URL pattern: ${opt.result_url_pattern}`);
+            lines.push("  Steps:");
+            for (const step of opt.steps) {
+                lines.push(`    ${step}`);
+            }
+            if (opt.notes && opt.notes.length > 0) {
+                lines.push("  Notes:");
+                for (const note of opt.notes) {
+                    lines.push(`    - ${note}`);
+                }
+            }
+            lines.push("");
+        }
+    }
+    if (suggestion.remind_update_hash) {
+        lines.push("⚠️ After deploying, compute the new WIP hash and update the Service:");
+        lines.push("  1. Re-run wip_file { type: 'verify', wipFilePath: '<new-public-url>' } to confirm the file is reachable.");
+        lines.push("  2. Extract the meta.hash from the WIP file (or use wip_file { type: 'verify' } result).");
+        lines.push("  3. Update the Service on-chain: onchain_operations { operation_type: 'service', data: { object: '<service-id>', sales: { op: 'set', sales: [{ ..., wip_url: '<new-public-url>', wip_hash: '<hash>' }] } } }");
+        lines.push("");
+    }
+    lines.push("===============================");
+    return lines.join("\n");
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wowok/agent-mcp",
-  "version": "2.6.0",
+  "version": "2.6.1",
   "description": "Making It Easy for AI Agents to Communicate, Collaborate, Trade, and Trust.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -50,7 +50,7 @@
   "license": "Apache-2.0",
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
-    "@wowok/wowok": "2.6.0",
+    "@wowok/wowok": "2.6.1",
     "lodash": "^4.18.1",
     "zod": "^3.25.76",
     "zod-to-json-schema": "^3.25.2"

package/dist/schemas/guard-node-examples.md

@@ -1,199 +0,0 @@
-# GuardNode Usage Guide
-
-This document provides practical examples of GuardNode usage for AI agents.
-
-## Overview
-
-A GuardNode is a computational tree node that represents an operation returning a typed value. Nodes can be nested to build complex validation logic. The root node of a Guard MUST return a `Bool` value (pass/fail).
-
-## Common Patterns
-
-### Pattern 1: Verify Transaction Signer is Order Owner
-
-```json
-{
-  "type": "logic_equal",
-  "nodes": [
-    { "type": "context", "context": "Signer" },
-    {
-      "type": "query",
-      "query": 1562,
-      "object": { "identifier": 0 },
-      "parameters": []
-    }
-  ]
-}
-```
-
-**Explanation:**
-- `context: Signer` returns the transaction sender's address
-- `query: 1562` gets the order owner (order.owner query)
-- `logic_equal` compares the two addresses
-
-### Pattern 2: Verify Order Progress Node
-
-```json
-{
-  "type": "logic_equal",
-  "nodes": [
-    {
-      "type": "query",
-      "query": 1253,
-      "object": { "identifier": 0, "convert_witness": 100 },
-      "parameters": []
-    },
-    { "type": "identifier", "identifier": 1 }
-  ]
-}
-```
-
-**Explanation:**
-- `query: 1253` gets the current progress node name
-- `convert_witness: 100` (TypeOrderProgress) converts the object for progress query
-- Compares with the expected node name stored at identifier 1
-
-### Pattern 3: Verify Reward Not Claimed
-
-```json
-{
-  "type": "logic_not",
-  "node": {
-    "type": "query_reward_record_exists",
-    "object": { "identifier": 0 },
-    "recipient": { "identifier": 1 },
-    "where": {}
-  }
-}
-```
-
-**Explanation:**
-- `query_reward_record_exists` checks if a reward record exists for the recipient
-- `logic_not` inverts the result (returns true if NO record exists)
-- This verifies the reward has NOT been claimed
-
-### Pattern 4: Combined Validation (Reward Guard)
-
-```json
-{
-  "type": "logic_and",
-  "nodes": [
-    {
-      "type": "logic_equal",
-      "nodes": [
-        {
-          "type": "query",
-          "query": 1253,
-          "object": { "identifier": 0, "convert_witness": 100 },
-          "parameters": []
-        },
-        { "type": "identifier", "identifier": 1 }
-      ]
-    },
-    {
-      "type": "logic_equal",
-      "nodes": [
-        { "type": "context", "context": "Signer" },
-        {
-          "type": "query",
-          "query": 1562,
-          "object": { "identifier": 0 },
-          "parameters": []
-        }
-      ]
-    },
-    {
-      "type": "logic_not",
-      "node": {
-        "type": "query_reward_record_exists",
-        "object": { "identifier": 2 },
-        "recipient": { "identifier": 3 },
-        "where": {}
-      }
-    }
-  ]
-}
-```
-
-**Explanation:**
-This is a complete Reward Guard that verifies:
-1. Order is at expected progress node (e.g., "delivered")
-2. Transaction signer is the order owner
-3. Order has NOT claimed the reward yet
-
-## Query Instruction Reference
-
-| Query ID | Name | Description | Parameters | Returns |
-|----------|------|-------------|------------|---------|
-| 1253 | order.progress.node | Get current progress node name | None | String |
-| 1562 | order.owner | Get order owner address | None | Address |
-| 1563 | order.service | Get order service address | None | Address |
-| 1564 | order.payer | Get order payer address | None | Address |
-
-## Witness Types
-
-| Witness ID | Name | Description |
-|------------|------|-------------|
-| 100 | TypeOrderProgress | Access order progress data |
-| 200 | TypeOrder | Access order data |
-
-## Node Return Types
-
-### Logic Nodes (Return Bool)
-- `logic_and`, `logic_or`, `logic_not`
-- `logic_equal`, `logic_as_u256_equal`
-- `logic_as_u256_greater`, `logic_as_u256_lesser`
-- `logic_as_u256_greater_or_equal`, `logic_as_u256_lesser_or_equal`
-- `logic_string_contains`, `logic_string_nocase_contains`, `logic_string_nocase_equal`
-
-### Calculation Nodes (Return Numeric)
-- `calc_number_add`, `calc_number_subtract`, `calc_number_multiply`, `calc_number_divide`, `calc_number_mod` → U256
-- `calc_string_length` → U64
-- `calc_string_contains`, `calc_string_nocase_contains`, `calc_string_nocase_equal` → Bool
-- `calc_string_indexof`, `calc_string_nocase_indexof` → U64
-
-### Conversion Nodes
-- `convert_number_address` → Address
-- `convert_address_number` → U64
-- `convert_number_string` → String
-- `convert_string_number` → U256
-- `convert_safe_u8`, `convert_safe_u16`, `convert_safe_u32`, `convert_safe_u64`, `convert_safe_u128`, `convert_safe_u256` → Respective type
-
-### Query Nodes (Return Varies)
-- `query` → Depends on query instruction
-- `query_reward_record_find`, `query_reward_record_count` → U64
-- `query_reward_record_exists` → Bool
-- `query_progress_history_find`, `query_progress_history_session_find`, `query_progress_history_session_forward_find` → U64
-- `query_progress_history_session_count`, `query_progress_history_session_forward_count`, `query_progress_history_session_forward_retained_submission_count` → U64
-
-### Context Nodes
-- `context: Signer` → Address
-- `context: Clock` → U64 (timestamp)
-- `context: Guard` → Address
-
-### Vector Nodes
-- `vec_length` → U64
-- `vec_contains_bool`, `vec_contains_address`, `vec_contains_string`, `vec_contains_string_nocase`, `vec_contains_number` → Bool
-
-## Best Practices
-
-1. **Root node must return Bool**: Always use a logic node (logic_and, logic_or) as the root.
-
-2. **Use logic_and for multiple conditions**: Most common pattern for combining validations.
-
-3. **Check node return types**: Ensure child nodes return the expected type for the parent node.
-   - Logic nodes expect Bool children
-   - Calculation nodes expect numeric children
-   - Comparison nodes expect matching types
-
-4. **Use identifier references**: Store constants (addresses, strings, numbers) in the Guard table and reference them by identifier.
-
-5. **Query with convert_witness**: When querying object data, use the appropriate witness type to access the data you need.
-
-6. **Handle optional fields**: In where clauses, only include fields you want to filter by. Omitting a field means "don't filter by this field".
-
-## Common Errors
-
-1. **Type mismatch**: Trying to compare incompatible types (e.g., Address with String).
-2. **Missing identifier**: Referencing an identifier that doesn't exist in the Guard table.
-3. **Wrong return type**: Using a non-Bool node as the root or as a child of a logic node.
-4. **Invalid query ID**: Using a query instruction ID that doesn't exist.