agentgrade-cli 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Agentic Adventures
+
+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/README.md

@@ -0,0 +1,71 @@
+# agentgrade
+
+Scan any website for AI agent readiness.
+
+## Quick Start
+
+```bash
+npx agentgrade https://example.com
+```
+
+No install needed. Runs directly with `npx`.
+
+## What It Checks
+
+- **Payment protocols** -- x402 (Coinbase), MPP (Machine Payments Protocol), L402 (Lightning), Stripe SPT
+- **Discovery endpoints** -- `/.well-known/mpp.json`, `/.well-known/x402.json`, payment info headers
+- **Bazaar discovery** -- x402 service catalogs, probe endpoints, Link headers
+- **MCP servers** -- Model Context Protocol endpoints and tool counts
+- **Claude plugins** -- `/.well-known/claude-plugin.json`
+- **OpenAI plugins** -- `/.well-known/ai-plugin.json`
+- **OpenAPI specs** -- `/openapi.json`, `/swagger.json`
+- **llms.txt** -- LLM-friendly site descriptions
+- **agents.txt** -- Agent permission declarations
+- **robots.txt** -- AI agent-specific directives
+- **Homepage scan** -- Mentions of payment protocols in page content
+
+## Usage
+
+Scan a specific endpoint for 402 payment challenges plus all discovery:
+
+```bash
+agentgrade https://api.example.com/v1/submit POST '{"title":"test"}'
+```
+
+Run discovery checks only (skip the 402 probe):
+
+```bash
+agentgrade https://example.com --discover-only
+```
+
+Default method is POST. Pass GET explicitly for read endpoints:
+
+```bash
+agentgrade https://api.example.com/v1/feed GET
+```
+
+## Output
+
+The scanner prints color-coded terminal output organized into sections:
+
+- **402 Probe** -- Sends the request and inspects response headers for x402, MPP, and L402 challenges
+- **Discovery** -- Checks well-known endpoints for payment configuration files
+- **Bazaar Discovery** -- Looks for x402 service catalogs and probe endpoints
+- **Homepage Scan** -- Scans the homepage HTML for protocol mentions
+- **Agent Capabilities** -- Finds MCP servers, plugins, OpenAPI specs, llms.txt, and more
+- **Summary** -- Lists confirmed payment rails, documented protocols, and detected capabilities
+
+Green checkmarks indicate detected features. Dimmed X marks indicate features not found.
+
+## Web Scanner
+
+For a full web-based scan with a visual report, visit [agentgrade.com](https://agentgrade.com).
+
+## Links
+
+- [AgentGrade web scanner](https://agentgrade.com)
+- [Agentic Adventures](https://github.com/agentic-adventures)
+
+## License
+
+MIT

package/cli.mjs

@@ -0,0 +1,337 @@
+#!/usr/bin/env node
+
+/**
+ * agentgrade CLI — scan any site for agent capabilities and payment protocols
+ *
+ * Usage:
+ *   node cli.mjs <url> [method] [body]
+ *   node cli.mjs <url> --discover-only
+ *
+ * Examples:
+ *   node cli.mjs https://agentnews.xyz/api/v1/submit POST '{"title":"test"}'
+ *   node cli.mjs https://agentnews.xyz --discover-only
+ */
+
+import { probe402, probeDiscovery, probeBazaar, probeHomepage, probeCapabilities } from './lib/probe.mjs';
+
+const BOLD = '\x1b[1m';
+const DIM = '\x1b[2m';
+const GREEN = '\x1b[32m';
+const YELLOW = '\x1b[33m';
+const CYAN = '\x1b[36m';
+const RED = '\x1b[31m';
+const RESET = '\x1b[0m';
+
+const args = process.argv.slice(2).filter(a => !a.startsWith('--'));
+const flags = new Set(process.argv.slice(2).filter(a => a.startsWith('--')));
+const discoverOnly = flags.has('--discover-only');
+
+if (args.length === 0) {
+  console.log(`\n${BOLD}agentgrade${RESET} — scan any site for agent capabilities\n`);
+  console.log(`Usage:`);
+  console.log(`  node cli.mjs <url> [method] [body]`);
+  console.log(`  node cli.mjs <url> --discover-only\n`);
+  console.log(`Examples:`);
+  console.log(`  node cli.mjs https://agentnews.xyz/api/v1/submit POST '{"title":"test"}'`);
+  console.log(`  node cli.mjs https://agentnews.xyz --discover-only\n`);
+  process.exit(0);
+}
+
+const url = new URL(args[0]);
+const method = (args[1] || 'POST').toUpperCase();
+const body = args[2] || undefined;
+const origin = url.origin;
+const base = origin + url.pathname.replace(/\/$/, '');
+
+// ─── Formatting helpers ────────────────────────────────────────────────────
+
+function section(title) { console.log(`\n${BOLD}${title}${RESET}`); }
+function found(protocol, details) { console.log(`  ${GREEN}✓ ${protocol}${RESET}  ${details}`); }
+function notFound(protocol, reason) { console.log(`  ${DIM}✗ ${protocol}  ${reason}${RESET}`); }
+function info(label, value) { console.log(`  ${CYAN}${label}:${RESET} ${value}`); }
+function warn(msg) { console.log(`  ${YELLOW}${msg}${RESET}`); }
+
+// ─── 402 Probe ──────────────────────────────────────────────────────────────
+
+const rails = [];
+let cfBlocked = false;
+
+if (!discoverOnly) {
+  section(`Probing ${method} ${url.href}`);
+
+  const result = await probe402(url.href, method, body);
+  info('Status', `${result.status}${result.error ? ` (${result.error})` : ''}`);
+
+  if (result.status !== 402) {
+    if (result.cfBlocked) {
+      cfBlocked = true;
+      console.log(`  ${RED}Cloudflare blocked${RESET} — bot challenge intercepted the request. Agents cannot reach this endpoint.`);
+    } else if (result.status >= 200 && result.status < 300) {
+      warn(`No payment required (${result.status}) — may use quota-based 402`);
+    } else if (result.error) {
+      console.log(`  ${RED}Error:${RESET} ${result.error}`);
+    } else {
+      warn(`Got ${result.status} — not a 402. Try a different method or path.`);
+    }
+    if (result.bodyMentions.length > 0) {
+      found('Body scan', `mentions: ${result.bodyMentions.join(', ')}`);
+    }
+  } else {
+    // x402
+    if (result.x402) {
+      if (result.x402.decodeFailed) {
+        found('x402', `Payment-Required header present (could not decode)`);
+        info('  Raw', result.x402.raw);
+      } else {
+        found('x402', `V${result.x402.version} — ${result.x402.options.length} payment option(s)`);
+        if (result.x402.description) info('  Description', result.x402.description);
+        for (const opt of result.x402.options) {
+          info('  Network', opt.network);
+          info('  Amount', `${opt.amount}${opt.assetName ? ` (${opt.assetName})` : ''}`);
+          info('  Asset', opt.asset);
+          info('  Pay to', opt.payTo);
+          if (opt.scheme) info('  Scheme', opt.scheme);
+          if (opt.maxTimeoutSeconds) info('  Timeout', `${opt.maxTimeoutSeconds}s`);
+          console.log();
+        }
+        if (result.x402.extensions) {
+          info('  Extensions', Object.keys(result.x402.extensions).join(', '));
+          if (result.x402.bazaar) {
+            const bz = result.x402.bazaar;
+            found('  Bazaar', `discoverable=${bz.discoverable ?? '?'}`);
+            if (bz.description) info('    Description', bz.description);
+            if (bz.inputSchema) info('    Input schema', JSON.stringify(bz.inputSchema));
+            if (bz.outputSchema) info('    Output schema', JSON.stringify(bz.outputSchema));
+          }
+        }
+      }
+      rails.push('x402');
+    } else {
+      notFound('x402', 'no Payment-Required header');
+    }
+
+    // MPP
+    if (result.mpp) {
+      found('MPP', 'WWW-Authenticate: Payment');
+      for (const [k, v] of Object.entries(result.mpp.fields)) info(`  ${k}`, v);
+      rails.push('MPP');
+    } else {
+      notFound('MPP', 'no WWW-Authenticate: Payment header');
+    }
+
+    // L402
+    if (result.l402) {
+      found('L402', `WWW-Authenticate: ${result.l402.header}`);
+      if (result.l402.macaroon) info('  Macaroon', result.l402.macaroon.slice(0, 60) + '...');
+      if (result.l402.invoice) info('  Invoice', result.l402.invoice.slice(0, 60) + '...');
+      rails.push('L402');
+    } else {
+      notFound('L402', 'no L402/LSAT in WWW-Authenticate');
+    }
+
+    // Other headers
+    if (result.otherHeaders.length > 0) {
+      console.log(`\n  ${DIM}Other payment-related headers:${RESET}`);
+      for (const h of result.otherHeaders) info(`  ${h.name}`, h.value);
+    }
+  }
+}
+
+// ─── Discovery ──────────────────────────────────────────────────────────────
+
+section(`Discovery (${origin})`);
+
+const discovery = await probeDiscovery(origin);
+for (const ep of discovery.endpoints) {
+  if (ep.hasPayment || ep.mentions.length > 0) {
+    const detail = ep.mentions.length > 0 ? `mentions: ${ep.mentions.join(', ')}` : 'payment info found';
+    found(ep.path, `${ep.status} — ${detail}`);
+    if (ep.settlementRails) {
+      for (const rail of ep.settlementRails) {
+        info(`  ${rail.name}`, `${rail.protocol} — ${rail.currency} (${rail.status})`);
+        if (!rails.includes(rail.protocol)) rails.push(rail.protocol);
+      }
+    }
+    if (ep.paymentMode) info('  payment_mode', ep.paymentMode);
+    if (ep.paymentInfo) info('  payment_info', ep.paymentInfo);
+  } else {
+    info(ep.path, `${ep.status} (no payment info)`);
+  }
+}
+
+// ─── Bazaar Discovery ───────────────────────────────────────────────────────
+
+section(`Bazaar Discovery (${origin})`);
+
+const bazaar = await probeBazaar(origin);
+
+if (bazaar.x402Json) {
+  found('/.well-known/x402.json', 'x402 service catalog found');
+  const bf = bazaar.x402Json.fields || {};
+  const showField = (label, key) => {
+    const d = bf[key];
+    if (!d || d.status === 'ok') { if (bazaar.x402Json[key]) info(`  ${label}`, bazaar.x402Json[key]); return; }
+    if (d.status === 'misnamed') warn(`  ${label}: ${d.hint}`);
+    else if (d.status === 'empty') warn(`  ${label}: ${d.hint}`);
+    else warn(`  ${label}: ✗ ${d.hint}`);
+  };
+  showField('Provider', 'name');
+  showField('Network', 'network');
+  showField('Facilitator', 'facilitator');
+  showField('Pay to', 'payTo');
+  if (bazaar.x402Json.testnet) warn('  ⚠ Testnet mode');
+  if (bazaar.x402Json.services.length > 0) {
+    info('  Services', `${bazaar.x402Json.services.length} paid endpoint(s)`);
+    for (const svc of bazaar.x402Json.services) {
+      const bazaarTag = svc.bazaar?.discoverable ? ` ${GREEN}[Bazaar: discoverable]${RESET}` : '';
+      info(`    ${svc.method} ${svc.path}`, `${svc.amount}${bazaarTag}`);
+      if (svc.description) info('      ', svc.description);
+      if (svc.bazaar) {
+        if (svc.bazaar.inputSchema) info('      Input', JSON.stringify(svc.bazaar.inputSchema));
+        if (svc.bazaar.outputSchema) info('      Output', JSON.stringify(svc.bazaar.outputSchema));
+      }
+    }
+  }
+  if (bazaar.x402Json.freeEndpoints.length > 0) {
+    info('  Free endpoints', `${bazaar.x402Json.freeEndpoints.length}`);
+    for (const ep of bazaar.x402Json.freeEndpoints) {
+      info(`    ${ep.method} ${ep.path}`, ep.description);
+    }
+  }
+  if (!rails.includes('x402')) rails.push('x402');
+} else {
+  notFound('/.well-known/x402.json', 'not found');
+}
+
+if (bazaar.x402Probe) {
+  found('/.well-known/x402-probe', 'returns 402 — live challenges');
+  if (bazaar.x402Probe.version) info('  Payment-Required', `x402 V${bazaar.x402Probe.version}`);
+  if (bazaar.x402Probe.headerBazaar) found('  Bazaar in header', `discoverable=${bazaar.x402Probe.headerBazaar.discoverable}`);
+  if (bazaar.x402Probe.challenges.length > 0) {
+    info('  Challenges', `${bazaar.x402Probe.challenges.length} endpoint(s)`);
+    for (const ch of bazaar.x402Probe.challenges) {
+      const tag = ch.bazaar ? ` ${GREEN}[Bazaar]${RESET}` : '';
+      info(`    ${ch.endpoint}`, `${ch.amount} ${ch.assetName || ''}${tag}`);
+    }
+  }
+  if (!rails.includes('x402')) rails.push('x402');
+} else {
+  notFound('/.well-known/x402-probe', 'not found');
+}
+
+if (bazaar.linkHeader) {
+  found('Link header', bazaar.linkHeader);
+} else {
+  notFound('Link header', 'no x402 discovery link');
+}
+
+// ─── Homepage Scan ──────────────────────────────────────────────────────────
+
+if (url.pathname === '/' || discoverOnly) {
+  section(`Homepage scan (${origin})`);
+  const homepage = await probeHomepage(origin);
+  const keys = Object.keys(homepage.protocols);
+  if (keys.length > 0) {
+    for (const [proto, hints] of Object.entries(homepage.protocols)) {
+      const detail = hints.length > 0 ? ` (${hints.join(', ')})` : '';
+      found('Homepage', `mentions ${proto}${detail}`);
+      if (proto !== '402 flow' && !rails.includes(proto) && !rails.includes(`${proto} (documented)`)) {
+        rails.push(`${proto} (documented)`);
+      }
+    }
+  } else {
+    notFound('Homepage', 'no payment protocol mentions found');
+  }
+}
+
+// ─── Agent Capabilities ────────────────────────────────────────────────────
+
+section(`Agent Capabilities (${base})`);
+
+const rawCapabilities = await probeCapabilities(origin, base);
+const capabilities = rawCapabilities.filter(c => !c.cfBlocked);
+const cfBlockedCaps = rawCapabilities.filter(c => c.cfBlocked);
+const capTypes = new Set();
+
+for (const cap of cfBlockedCaps) {
+  console.log(`  ${RED}✗ ${cap.type}${RESET}  ${DIM}blocked by Cloudflare${RESET}`);
+}
+
+for (const cap of capabilities) {
+  capTypes.add(cap.type);
+  switch (cap.type) {
+    case 'MCP':
+      found('MCP', `${cap.path} — ${cap.name || cap.detail || 'endpoint found'}`);
+      if (cap.tools) info('  Tools', `${cap.tools} tool(s)`);
+      if (cap.name) info('  Name', cap.name);
+      if (cap.description) info('  Description', cap.description);
+      if (cap.transport) info('  Transport', cap.transport);
+      if (cap.protocolVersion) info('  Protocol', cap.protocolVersion);
+      if (cap.sseSupported) info('  SSE', 'supported');
+      if (cap.cors) info('  CORS', 'enabled');
+      break;
+    case 'Claude Plugin':
+      found('Claude Plugin', cap.path);
+      if (cap.name) info('  Name', cap.name);
+      if (cap.description) info('  Description', cap.description);
+      if (cap.version) info('  Version', cap.version);
+      if (cap.skills) info('  Skills', `${cap.skills} skill(s)`);
+      if (cap.tools) info('  Tools', `${cap.tools} tool(s)`);
+      break;
+    case 'AI Plugin':
+      found('AI Plugin', cap.path);
+      if (cap.name) info('  Name', cap.name);
+      if (cap.modelName) info('  Model name', cap.modelName);
+      if (cap.description) info('  Description', cap.description);
+      if (cap.apiUrl) info('  API spec', cap.apiUrl);
+      if (cap.auth) info('  Auth', cap.auth);
+      break;
+    case 'Skills':
+      found('Skills', `${cap.path} — ${cap.count ? cap.count + ' skill(s)' : cap.bytes + ' bytes'}`);
+      break;
+    case 'OpenAPI':
+      found('OpenAPI', `${cap.path} — ${cap.version} "${cap.title}" (${cap.paths} paths)`);
+      break;
+    case 'llms.txt':
+      found('llms.txt', `${cap.path} — ${cap.lines} lines`);
+      if (cap.preview) info('  ', cap.preview);
+      break;
+    case 'agents.txt':
+      found('agents.txt', `${cap.lines} lines`);
+      break;
+    case 'robots.txt (agent-aware)':
+      found('robots.txt', 'agent-relevant directives found');
+      for (const d of cap.directives) info('  ', d);
+      break;
+    default:
+      found(cap.type, cap.path);
+  }
+}
+
+// Not-found for types we checked but didn't find
+const cfBlockedCapTypes = new Set(cfBlockedCaps.map(c => c.type));
+for (const type of ['MCP', 'Claude Plugin', 'AI Plugin', 'Skills', 'OpenAPI', 'llms.txt', 'agents.txt']) {
+  if (!capTypes.has(type) && !cfBlockedCapTypes.has(type)) notFound(type, `no ${type.toLowerCase()} found`);
+}
+
+// ─── Summary ────────────────────────────────────────────────────────────────
+
+section('Summary');
+
+const confirmed = rails.filter(r => !r.includes('(documented)'));
+const documented = rails.filter(r => r.includes('(documented)'));
+if (confirmed.length > 0) console.log(`  ${GREEN}${BOLD}Confirmed (402 headers): ${confirmed.join(', ')}${RESET}`);
+if (documented.length > 0) console.log(`  ${YELLOW}${BOLD}Documented (mentioned in pages): ${documented.join(', ')}${RESET}`);
+if (bazaar.bazaarServices > 0) {
+  console.log(`  ${GREEN}${BOLD}Bazaar: ${bazaar.bazaarServices} discoverable service(s)${RESET}`);
+} else {
+  console.log(`  ${DIM}Bazaar: no discoverable services${RESET}`);
+}
+if (rails.length === 0 && !cfBlocked) console.log(`  ${YELLOW}No payment rails detected${RESET}`);
+if (rails.length === 0 && cfBlocked) console.log(`  ${RED}No payment rails detected — Cloudflare blocked all probes${RESET}`);
+if (capTypes.size > 0) {
+  console.log(`  ${GREEN}${BOLD}Agent capabilities: ${[...capTypes].join(', ')}${RESET}`);
+} else {
+  console.log(`  ${DIM}No agent capabilities detected${RESET}`);
+}
+console.log();