@kirkelabs/agent-readiness-scan 0.1.0 → 0.2.0

package/bin/cli.js

@@ -1,172 +1,175 @@
-#!/usr/bin/env node
-/**
- * bin/cli.js — command-line entry point.
- *
- * Usage:
- *   npx @kirkelabs/agent-readiness-scan https://example.com
- *   npx @kirkelabs/agent-readiness-scan https://example.com --out ./report
- *   npx @kirkelabs/agent-readiness-scan https://example.com --json
- */
-
-import { writeFile, mkdir } from 'node:fs/promises';
-import { resolve, join, dirname } from 'node:path';
-import { scan } from '../src/index.js';
-import { renderScorecard } from '../src/scorecard.js';
-
-const RESET = '\x1b[0m';
-const DIM = '\x1b[2m';
-const BOLD = '\x1b[1m';
-const GREEN = '\x1b[32m';
-const YELLOW = '\x1b[33m';
-const RED = '\x1b[31m';
-const CYAN = '\x1b[36m';
-
-function parseArgs(argv) {
-  const args = { url: null, out: './agent-readiness-out', json: false };
-  for (let i = 2; i < argv.length; i++) {
-    const a = argv[i];
-    if (a === '--out') args.out = argv[++i];
-    else if (a === '--json') args.json = true;
-    else if (a === '--help' || a === '-h') args.help = true;
-    else if (!a.startsWith('-')) args.url = a;
-  }
-  return args;
-}
-
-function help() {
-  console.log(`
-${BOLD}agent-readiness-scan${RESET} — is your brand ready for AI agents to act on it?
-
-${BOLD}Usage${RESET}
-  npx @kirkelabs/agent-readiness-scan <url> [options]
-
-${BOLD}Options${RESET}
-  --out <dir>      Output directory  (default: ./agent-readiness-out)
-  --json           Print machine-readable JSON to stdout (good for CI)
-  -h, --help       Show this help
-
-${BOLD}Outputs written to <dir>${RESET}
-  score.json                            Machine-readable result (CI-gateable)
-  report.md                             Human-readable report
-  scorecard.html                        Shareable static scorecard
-  customs-declaration/                  Drop-in policy files
-    robots.txt
-    .well-known/security.txt
-    .well-known/mcp/server-card.json
-    .well-known/acp/manifest.json
-
-MIT · Kirke Labs · www.kirkelabs.com
-`);
-}
-
-function color(level) {
-  return level === 'pass'
-    ? GREEN
-    : level === 'warn'
-      ? YELLOW
-      : level === 'fail'
-        ? RED
-        : DIM;
-}
-
-function bar(pct, width = 22) {
-  const fill = Math.round((pct / 100) * width);
-  return '█'.repeat(fill) + '░'.repeat(width - fill);
-}
-
-async function writeArtefact(outDir, relPath, content) {
-  const fullPath = join(outDir, relPath);
-  await mkdir(dirname(fullPath), { recursive: true });
-  await writeFile(fullPath, content);
-}
-
-async function main() {
-  const args = parseArgs(process.argv);
-  if (args.help || !args.url) {
-    help();
-    process.exit(args.url ? 0 : 1);
-  }
-
-  let url = args.url;
-  if (!/^https?:\/\//i.test(url)) url = 'https://' + url;
-
-  if (!args.json) {
-    console.log(`\n${CYAN}⟶  Scanning ${BOLD}${url}${RESET}${CYAN} for agent-readiness…${RESET}\n`);
-  }
-
-  const result = await scan(url);
-
-  if (args.json) {
-    process.stdout.write(JSON.stringify(result, null, 2) + '\n');
-    return;
-  }
-
-  if (!result.ok) {
-    console.error(`${RED}✗ Could not scan: ${result.error}${RESET}\n`);
-    process.exit(2);
-  }
-
-  const gColor =
-    result.grade === 'A' || result.grade === 'B'
-      ? GREEN
-      : result.grade === 'C'
-        ? YELLOW
-        : RED;
-
-  console.log(
-    `${BOLD}  Agent-Readiness Score: ${gColor}${result.score}/100  (${result.grade})${RESET}\n`,
-  );
-
-  for (const d of result.dimensions) {
-    const pct = Math.round((d.score / d.max) * 100);
-    const c = pct >= 70 ? GREEN : pct >= 40 ? YELLOW : RED;
-    console.log(
-      `  ${c}${bar(pct)}${RESET}  ${d.title} ${DIM}(${d.score}/${d.max}, weight ${d.weight})${RESET}`,
-    );
-    for (const f of d.findings) {
-      console.log(`     ${color(f.level)}•${RESET} ${f.msg}`);
-    }
-    console.log('');
-  }
-
-  // Write artefacts.
-  const outDir = resolve(args.out);
-  await mkdir(outDir, { recursive: true });
-  await writeFile(join(outDir, 'score.json'), JSON.stringify(result, null, 2));
-  await writeFile(join(outDir, 'report.md'), toMarkdown(result));
-  await writeFile(join(outDir, 'scorecard.html'), renderScorecard(result));
-
-  // Customs declaration files.
-  for (const [relPath, content] of Object.entries(result.generated)) {
-    await writeArtefact(join(outDir, 'customs-declaration'), relPath, content);
-  }
-
-  console.log(`${DIM}  Artefacts written to ${outDir}/${RESET}`);
-  console.log(
-    `${DIM}    score.json · report.md · scorecard.html · customs-declaration/${RESET}\n`,
-  );
-  console.log(
-    `${DIM}  Heuristic indicators, not a guarantee of agent action. See docs/METHODOLOGY.md${RESET}\n`,
-  );
-
-  process.exit(result.score >= 50 ? 0 : 3);
-}
-
-function toMarkdown(r) {
-  let md = `# Agent-Readiness Report\n\n`;
-  md += `**URL:** ${r.url}  \n**Score:** ${r.score}/100 (${r.grade})  \n`;
-  md += `**Scanned:** ${r.scannedAt}\n\n`;
-  md += `> Heuristic indicators of how ready this brand is for AI agents to discover, declare access to, and act on. Not a guarantee of agent uptake.\n\n`;
-  for (const d of r.dimensions) {
-    md += `## ${d.title} — ${d.score}/${d.max}\n\n_${d.why}_\n\n`;
-    for (const f of d.findings) md += `- **${f.level.toUpperCase()}** — ${f.msg}\n`;
-    md += `\n`;
-  }
-  md += `---\n\nGenerated by [\`@kirkelabs/agent-readiness-scan\`](https://github.com/KirkeLabs/agent-readiness-scan) — MIT. Built by Soleman El Gelawi (CTO, Kirke Labs), with Steve Kirton (www.kirkelabs.com) as a gift to the Algorand ecosystem.\n`;
-  return md;
-}
-
-main().catch((e) => {
-  console.error(`${RED}Unexpected error:${RESET}`, e);
-  process.exit(1);
-});
+#!/usr/bin/env node
+/**
+ * bin/cli.js — command-line entry point.
+ *
+ * Usage:
+ *   npx @kirkelabs/agent-readiness-scan https://example.com
+ *   npx @kirkelabs/agent-readiness-scan https://example.com --out ./report
+ *   npx @kirkelabs/agent-readiness-scan https://example.com --json
+ */
+
+import { writeFile, mkdir } from 'node:fs/promises';
+import { resolve, join, dirname } from 'node:path';
+import { scan } from '../src/index.js';
+import { renderScorecard } from '../src/scorecard.js';
+
+const RESET = '\x1b[0m';
+const DIM = '\x1b[2m';
+const BOLD = '\x1b[1m';
+const GREEN = '\x1b[32m';
+const YELLOW = '\x1b[33m';
+const RED = '\x1b[31m';
+const CYAN = '\x1b[36m';
+
+function parseArgs(argv) {
+  const args = { url: null, out: './agent-readiness-out', json: false };
+  for (let i = 2; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--out') args.out = argv[++i];
+    else if (a === '--json') args.json = true;
+    else if (a === '--help' || a === '-h') args.help = true;
+    else if (!a.startsWith('-')) args.url = a;
+  }
+  return args;
+}
+
+function help() {
+  console.log(`
+${BOLD}agent-readiness-scan${RESET} — is your brand ready for AI agents to act on it?
+
+${BOLD}Usage${RESET}
+  npx @kirkelabs/agent-readiness-scan <url> [options]
+
+${BOLD}Options${RESET}
+  --out <dir>      Output directory  (default: ./agent-readiness-out)
+  --json           Print machine-readable JSON to stdout (good for CI)
+  -h, --help       Show this help
+
+${BOLD}Outputs written to <dir>${RESET}
+  score.json                            Machine-readable result (CI-gateable)
+  report.md                             Human-readable report
+  scorecard.html                        Shareable static scorecard
+  customs-declaration/                  Drop-in policy files
+    robots.txt
+    .well-known/security.txt
+    .well-known/mcp/server-card.json
+    .well-known/acp/manifest.json
+    .well-known/agent-access.json
+
+MIT · Kirke Labs · www.kirkelabs.com
+`);
+}
+
+function color(level) {
+  return level === 'pass'
+    ? GREEN
+    : level === 'warn'
+      ? YELLOW
+      : level === 'fail'
+        ? RED
+        : DIM;
+}
+
+function bar(pct, width = 22) {
+  const fill = Math.round((pct / 100) * width);
+  return '█'.repeat(fill) + '░'.repeat(width - fill);
+}
+
+async function writeArtefact(outDir, relPath, content) {
+  const fullPath = join(outDir, relPath);
+  await mkdir(dirname(fullPath), { recursive: true });
+  await writeFile(fullPath, content);
+}
+
+async function main() {
+  const args = parseArgs(process.argv);
+  if (args.help || !args.url) {
+    help();
+    process.exit(args.url ? 0 : 1);
+  }
+
+  let url = args.url;
+  if (!/^https?:\/\//i.test(url)) url = 'https://' + url;
+
+  if (!args.json) {
+    console.log(
+      `\n${CYAN}⟶  Scanning ${BOLD}${url}${RESET}${CYAN} for agent-readiness…${RESET}\n`,
+    );
+  }
+
+  const result = await scan(url);
+
+  if (args.json) {
+    process.stdout.write(JSON.stringify(result, null, 2) + '\n');
+    return;
+  }
+
+  if (!result.ok) {
+    console.error(`${RED}✗ Could not scan: ${result.error}${RESET}\n`);
+    process.exit(2);
+  }
+
+  const gColor =
+    result.grade === 'A' || result.grade === 'B'
+      ? GREEN
+      : result.grade === 'C'
+        ? YELLOW
+        : RED;
+
+  console.log(
+    `${BOLD}  Agent-Readiness Score: ${gColor}${result.score}/100  (${result.grade})${RESET}\n`,
+  );
+
+  for (const d of result.dimensions) {
+    const pct = Math.round((d.score / d.max) * 100);
+    const c = pct >= 70 ? GREEN : pct >= 40 ? YELLOW : RED;
+    console.log(
+      `  ${c}${bar(pct)}${RESET}  ${d.title} ${DIM}(${d.score}/${d.max}, weight ${d.weight})${RESET}`,
+    );
+    for (const f of d.findings) {
+      console.log(`     ${color(f.level)}•${RESET} ${f.msg}`);
+    }
+    console.log('');
+  }
+
+  // Write artefacts.
+  const outDir = resolve(args.out);
+  await mkdir(outDir, { recursive: true });
+  await writeFile(join(outDir, 'score.json'), JSON.stringify(result, null, 2));
+  await writeFile(join(outDir, 'report.md'), toMarkdown(result));
+  await writeFile(join(outDir, 'scorecard.html'), renderScorecard(result));
+
+  // Customs declaration files.
+  for (const [relPath, content] of Object.entries(result.generated)) {
+    await writeArtefact(join(outDir, 'customs-declaration'), relPath, content);
+  }
+
+  console.log(`${DIM}  Artefacts written to ${outDir}/${RESET}`);
+  console.log(
+    `${DIM}    score.json · report.md · scorecard.html · customs-declaration/${RESET}\n`,
+  );
+  console.log(
+    `${DIM}  Heuristic indicators, not a guarantee of agent action. See docs/METHODOLOGY.md${RESET}\n`,
+  );
+
+  process.exit(result.score >= 50 ? 0 : 3);
+}
+
+function toMarkdown(r) {
+  let md = `# Agent-Readiness Report\n\n`;
+  md += `**URL:** ${r.url}  \n**Score:** ${r.score}/100 (${r.grade})  \n`;
+  md += `**Scanned:** ${r.scannedAt}\n\n`;
+  md += `> Heuristic indicators of how ready this brand is for AI agents to discover, declare access to, and act on. Not a guarantee of agent uptake.\n\n`;
+  for (const d of r.dimensions) {
+    md += `## ${d.title} — ${d.score}/${d.max}\n\n_${d.why}_\n\n`;
+    for (const f of d.findings) md += `- **${f.level.toUpperCase()}** — ${f.msg}\n`;
+    md += `\n`;
+  }
+  md += `---\n\nGenerated by [\`@kirkelabs/agent-readiness-scan\`](https://github.com/KirkeLabs/agent-readiness-scan) — MIT. Built by Soleman El Gelawi (CTO, Kirke Labs), with Steve Kirton (www.kirkelabs.com) as a gift to the Algorand ecosystem.\n`;
+  return md;
+}
+
+main().catch((e) => {
+  console.error(`${RED}Unexpected error:${RESET}`, e);
+  process.exit(1);
+});

package/package.json

@@ -1,64 +1,69 @@
-{
-  "name": "@kirkelabs/agent-readiness-scan",
-  "version": "0.1.0",
-  "description": "Audit a website's customs-house posture for AI agents. Scores 8 dimensions — crawler policy, bot auth, MCP/ACP exposure, agent-actionable Product/Offer, brand identity corroboration, regulatory transparency — and generates a drop-in customs declaration (robots.txt + .well-known/ manifests). A gift to the Algorand ecosystem from Kirke Labs.",
-  "type": "module",
-  "bin": {
-    "agent-readiness-scan": "bin/cli.js"
-  },
-  "exports": {
-    ".": "./src/index.js"
-  },
-  "files": [
-    "bin/",
-    "src/",
-    "LICENSE",
-    "README.md",
-    "AUTHORS",
-    "CITATION.cff"
-  ],
-  "scripts": {
-    "scan": "node bin/cli.js",
-    "test": "node --test \"test/*.test.js\"",
-    "lint": "eslint . --ext .js",
-    "format": "prettier --write \"**/*.{js,json,md}\""
-  },
-  "keywords": [
-    "ai-agents",
-    "mcp",
-    "acp",
-    "agentic-commerce",
-    "crawler-policy",
-    "web-bot-auth",
-    "content-signals",
-    "universal-cart",
-    "schema-org",
-    "structured-data",
-    "algorand",
-    "cli",
-    "nodejs"
-  ],
-  "author": "Soleman El Gelawi <soleman@kirkelabs.com> (https://www.kirkelabs.com)",
-  "contributors": [
-    "Steve Kirton <steve@kirkelabs.com> (https://www.kirkelabs.com)"
-  ],
-  "license": "MIT",
-  "homepage": "https://kirkelabs.github.io/agent-readiness-scan/",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/KirkeLabs/agent-readiness-scan.git"
-  },
-  "bugs": {
-    "url": "https://github.com/KirkeLabs/agent-readiness-scan/issues"
-  },
-  "engines": {
-    "node": ">=20"
-  },
-  "dependencies": {
-    "cheerio": "^1.0.0"
-  },
-  "devDependencies": {
-    "eslint": "^9.0.0",
-    "prettier": "^3.0.0"
-  }
-}
+{
+  "name": "@kirkelabs/agent-readiness-scan",
+  "version": "0.2.0",
+  "description": "Audit a website's customs-house posture for AI agents. Scores 8 dimensions — crawler policy, bot auth, MCP/ACP exposure, agent-actionable Product/Offer, brand identity corroboration, regulatory transparency — and generates a drop-in customs declaration (robots.txt + .well-known/ manifests). A gift to the Algorand ecosystem from Kirke Labs.",
+  "type": "module",
+  "bin": {
+    "agent-readiness-scan": "bin/cli.js"
+  },
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "LICENSE",
+    "README.md",
+    "CHANGELOG.md",
+    "AUTHORS",
+    "CITATION.cff"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "scan": "node bin/cli.js",
+    "test": "node --test \"test/*.test.js\"",
+    "lint": "eslint . --ext .js",
+    "format": "prettier --write \"**/*.{js,json,md}\"",
+    "prepublishOnly": "npm run lint && npm test"
+  },
+  "keywords": [
+    "ai-agents",
+    "mcp",
+    "acp",
+    "agentic-commerce",
+    "crawler-policy",
+    "web-bot-auth",
+    "content-signals",
+    "universal-cart",
+    "schema-org",
+    "structured-data",
+    "algorand",
+    "cli",
+    "nodejs"
+  ],
+  "author": "Soleman El Gelawi <soleman@kirkelabs.com> (https://www.kirkelabs.com)",
+  "contributors": [
+    "Steve Kirton <steve@kirkelabs.com> (https://www.kirkelabs.com)"
+  ],
+  "license": "MIT",
+  "homepage": "https://kirkelabs.github.io/agent-readiness-scan/",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/KirkeLabs/agent-readiness-scan.git"
+  },
+  "bugs": {
+    "url": "https://github.com/KirkeLabs/agent-readiness-scan/issues"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "cheerio": "^1.0.0"
+  },
+  "devDependencies": {
+    "eslint": "^9.0.0",
+    "prettier": "^3.0.0"
+  }
+}