@foxygeo/audit 0.1.0

package/PUBLISHING.md

@@ -0,0 +1,73 @@
+# Launch `@foxygeo/audit`
+
+## Gate before any public launch
+
+1. Create the `@foxygeo` npm organization and authenticate the release account.
+2. Publish the package from this directory:
+
+   ```bash
+   npm publish --access public
+   ```
+
+3. From a directory outside this repository, prove the public package works:
+
+   ```bash
+   npx --yes @foxygeo/audit example.com
+   npx --yes @foxygeo/audit --ci --publish example.com
+   ```
+
+4. Create the public `github.com/foxygeo/audit` repository from this package
+   directory. Keep `action.yml` at its root, tag `v1.0.0`, then publish the
+   release as a GitHub Marketplace Action. The Marketplace requires a public
+   repository and a root action metadata file.
+
+The product link for general posts is
+[`foxygeo.com/tools/cli-audit`](https://foxygeo.com/tools/cli-audit). The
+GitHub repository is the better Show HN destination because readers can inspect
+and run the code immediately rather than arriving at a marketing page.
+
+## Distribution order
+
+| Priority | Channel | What to publish | Success signal |
+| --- | --- | --- | --- |
+| 1 | npm | `@foxygeo/audit` | Clean-room `npx` works. |
+| 2 | GitHub + Marketplace | Public source, `action.yml`, `v1` release and workflow example | `uses: foxygeo/audit@v1` is copyable. |
+| 3 | Show HN | A personally written launch post linking to the GitHub repository | Developers try the CLI and ask implementation questions. |
+| 4 | Dev.to / Hashnode | A technical walkthrough with canonical URL set to the tool landing page | Search discovery and workflow copies. |
+| 5 | Relevant communities | One useful, rule-compliant post in each community | Qualified runs, not impressions. |
+| 6 | X / LinkedIn | A real PR-comment screenshot plus a 15-second terminal recording | Clicks to the tool page and GitHub workflow copies. |
+
+## Channel guidance
+
+### GitHub Marketplace
+
+This is the strongest intent channel: people already looking for a CI action can
+install it directly. Keep the dedicated public repository limited to the Action
+and its docs. Pin the workflow snippet and tag the first release as `v1` after
+testing the immutable tag.
+
+### Show HN
+
+Do not submit until the package is publicly runnable. Show HN is for work that
+readers can try without a signup barrier; a landing page alone is not enough.
+Use the GitHub repository as the submitted URL and include the `npx` command,
+an actual public report and the GitHub Actions example in the project README.
+
+The maker should write the Show HN title and first comment personally. Hacker
+News currently asks submitters not to post AI-generated or AI-edited text, and
+the thread should be answered by the person who built the tool. Do not ask for
+upvotes or coordinated comments.
+
+### Communities worth testing after HN
+
+- `r/webdev`: a practical CI workflow, only if its current self-promotion
+  rules permit it.
+- `r/github`: GitHub Action angle, with the YAML example.
+- `r/SEO`: only the `llms.txt`/crawler-access audit angle; avoid pitching it
+  as a generic AI product.
+- Indie Hackers: build log and the report-generation architecture, not an ad.
+- Dev.to and Hashnode: one detailed implementation article with the canonical
+  URL pointing to the FoxyGEO tool page.
+
+Use one channel at a time. Measure clean-room installs, completed audits,
+`--publish` reports, GitHub workflow copies, and return usage—not likes.

package/README.md

@@ -0,0 +1,56 @@
+# `@foxygeo/audit`
+
+Free CI linter for AI crawler readiness. Checks `llms.txt`, GPTBot/ClaudeBot access, and JSON-LD in about two seconds, then comments the score on a pull request with a public report on [foxygeo.com](https://foxygeo.com/tools/cli-audit).
+
+```bash
+npx @foxygeo/audit
+npx @foxygeo/audit example.com
+npx @foxygeo/audit --ci --publish example.com
+```
+
+## GitHub Actions
+
+```yaml
+name: FoxyGEO
+on: [pull_request]
+jobs:
+  audit:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+      - run: npx --yes @foxygeo/audit --ci --publish example.com
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+```
+
+The PR comment looks like:
+
+> FoxyGEO AI Readiness: 94/100  
+> Public audit: https://foxygeo.com/report/example-com
+
+Preview hosts (`*.vercel.app`, `*.netlify.app`, and similar) are never published.
+
+## What it scores
+
+| Check | Weight |
+| --- | --- |
+| GPTBot / ClaudeBot not blocked at `/` | 40 |
+| `llms.txt` present and useful | 30 |
+| JSON-LD (`Organization` / `WebSite` / `FAQPage` / …) | 30 |
+
+Local mode reads files in the repo. Domain mode fetches `/robots.txt`, `/llms.txt`, and the homepage.
+
+## Publish later
+
+1. Create the npm org `@foxygeo` and run `npm publish --access public` from this directory.
+2. Point a public GitHub repo (or `foxygeo/audit-action`) at `action.yml`.
+3. Show HN title: `npx @foxygeo/audit — lint llms.txt, GPTBot access, and schema in CI`.
+
+See [PUBLISHING.md](./PUBLISHING.md) for the release gate, Marketplace setup,
+and channel order.

package/action.yml

@@ -0,0 +1,39 @@
+name: FoxyGEO Audit
+description: Lint llms.txt, GPTBot/ClaudeBot access, and schema. Comment AI Readiness on the PR with a public FoxyGEO report.
+author: FoxyGEO
+branding:
+  icon: search
+  color: blue
+inputs:
+  domain:
+    description: Production domain to publish as a public foxygeo.com report. Preview hosts are ignored.
+    required: false
+    default: ''
+  publish:
+    description: Set to "false" to lint without publishing a public report.
+    required: false
+    default: 'true'
+  fail-on:
+    description: error | warning | never
+    required: false
+    default: 'error'
+  github-token:
+    description: Token used to write the sticky PR comment.
+    required: false
+    default: ${{ github.token }}
+  working-directory:
+    description: Directory that contains robots.txt / llms.txt / HTML.
+    required: false
+    default: '.'
+runs:
+  using: composite
+  steps:
+    - name: Run FoxyGEO audit
+      working-directory: ${{ inputs.working-directory }}
+      shell: bash
+      env:
+        GITHUB_TOKEN: ${{ inputs.github-token }}
+        FOXYGEO_DOMAIN: ${{ inputs.domain }}
+        FOXYGEO_PUBLISH: ${{ inputs.publish }}
+        FOXYGEO_FAIL_ON: ${{ inputs.fail-on }}
+      run: node "$GITHUB_ACTION_PATH/bin/foxygeo-audit.js" --ci

package/bin/foxygeo-audit.js

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+import { run } from '../src/cli.js';
+
+run(process.argv.slice(2))
+  .then((code) => {
+    process.exit(code);
+  })
+  .catch((error) => {
+    console.error(error instanceof Error ? error.message : error);
+    process.exit(2);
+  });

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@foxygeo/audit",
+  "version": "0.1.0",
+  "description": "Lint llms.txt, GPTBot/ClaudeBot access, and schema in CI. Comments AI Readiness on the PR and publishes a public FoxyGEO report.",
+  "type": "module",
+  "bin": {
+    "foxygeo-audit": "bin/foxygeo-audit.js"
+  },
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "action.yml",
+    "README.md",
+    "PUBLISHING.md"
+  ],
+  "scripts": {
+    "test": "node --test tests/*.test.mjs",
+    "audit": "node bin/foxygeo-audit.js"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "license": "MIT",
+  "homepage": "https://foxygeo.com/tools/cli-audit",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/foxygeo/audit.git"
+  },
+  "keywords": [
+    "llms.txt",
+    "geo",
+    "gptbot",
+    "claudebot",
+    "schema",
+    "ci",
+    "github-actions",
+    "ai-search"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/ai-access.js

@@ -0,0 +1,174 @@
+export const AI_AGENTS = [
+  'gptbot',
+  'claudebot',
+  'chatgpt-user',
+  'oai-searchbot',
+  'claude-user',
+  'anthropic-ai',
+  'perplexitybot',
+  'google-extended',
+  'ccbot',
+  'applebot-extended',
+];
+
+export const PRIMARY_AGENTS = ['gptbot', 'claudebot'];
+export const SECONDARY_AGENTS = ['perplexitybot', 'google-extended', 'ccbot', 'anthropic-ai'];
+
+export const PREVIEW_SUFFIXES = [
+  '.vercel.app',
+  '.netlify.app',
+  '.github.io',
+  '.herokuapp.com',
+  '.railway.app',
+  '.onrender.com',
+  '.fly.dev',
+  '.web.app',
+  '.firebaseapp.com',
+  '.pages.dev',
+  '.ngrok.io',
+  '.ngrok-free.app',
+  '.trycloudflare.com',
+  '.amplifyapp.com',
+  '.azurewebsites.net',
+  '.cloudfront.net',
+  '.workers.dev',
+  '.localtest.me',
+  '.nip.io',
+  '.sslip.io',
+];
+
+const BRAND_SCHEMA_TYPES = new Set(['Organization', 'WebSite', 'LocalBusiness', 'Corporation', 'OnlineStore']);
+const RICH_SCHEMA_TYPES = new Set(['FAQPage', 'Article', 'NewsArticle', 'BlogPosting', 'Product', 'SoftwareApplication', 'Service']);
+
+export function isPreviewHost(host) {
+  let name = String(host || '').trim().toLowerCase().replace(/\.$/, '');
+  if (name.startsWith('www.')) name = name.slice(4);
+  if (!name) return true;
+  return PREVIEW_SUFFIXES.some((suffix) => name.endsWith(suffix));
+}
+
+function isRootRule(rule) {
+  const value = String(rule || '').trim();
+  return value === '/' || value === '/*';
+}
+
+export function parseRobots(text) {
+  if (!text || !String(text).trim()) {
+    return {
+      present: false,
+      blocksAi: false,
+      blocksAll: false,
+      agents: Object.fromEntries(AI_AGENTS.map((agent) => [agent, 'allow'])),
+      sitemaps: [],
+    };
+  }
+
+  const groups = [];
+  let current = null;
+  const sitemaps = [];
+
+  for (const rawLine of String(text).split(/\r?\n/)) {
+    const line = rawLine.split('#', 1)[0].trim();
+    if (!line || !line.includes(':')) continue;
+    const idx = line.indexOf(':');
+    const key = line.slice(0, idx).trim().toLowerCase();
+    const value = line.slice(idx + 1).trim();
+    if (key === 'user-agent') {
+      const agent = value.toLowerCase();
+      if (!current || current.hasDirective) {
+        current = { agents: new Set([agent]), allow: [], disallow: [], hasDirective: false };
+        groups.push(current);
+      } else {
+        current.agents.add(agent);
+      }
+    } else if (key === 'allow' && current) {
+      current.allow.push(value);
+      current.hasDirective = true;
+    } else if (key === 'disallow' && current) {
+      current.disallow.push(value);
+      current.hasDirective = true;
+    } else if (key === 'sitemap' && value) {
+      sitemaps.push(value);
+    }
+  }
+
+  function groupFor(agent) {
+    return groups.find((group) => group.agents.has(agent)) || groups.find((group) => group.agents.has('*')) || null;
+  }
+
+  function rootBlocked(group) {
+    if (!group) return false;
+    if (group.allow.some(isRootRule)) return false;
+    return group.disallow.some((rule) => String(rule || '').trim() && isRootRule(rule));
+  }
+
+  const blocksAll = rootBlocked(groupFor('*'));
+  const agents = {};
+  for (const agent of AI_AGENTS) {
+    agents[agent] = rootBlocked(groupFor(agent)) ? 'block' : 'allow';
+  }
+  const primaryBlocked = PRIMARY_AGENTS.some((agent) => agents[agent] === 'block');
+  return {
+    present: true,
+    blocksAi: blocksAll || primaryBlocked,
+    blocksAll,
+    agents,
+    sitemaps,
+  };
+}
+
+export function scoreLlms(text, exists) {
+  if (!exists) return { score: 0, ok: false, quality: 'missing' };
+  const body = String(text || '').trim();
+  if (body.length < 40) return { score: 10, ok: true, quality: 'thin' };
+  const lowered = body.toLowerCase();
+  const hasHeading = body.startsWith('#') || lowered.includes('llms');
+  const urlCount = (lowered.match(/https?:\/\//g) || []).length;
+  const hasOverview = body.includes('>') || body.includes('## ');
+  if (hasHeading && hasOverview && urlCount >= 2) return { score: 30, ok: true, quality: 'strong' };
+  if (hasHeading || urlCount >= 1) return { score: 20, ok: true, quality: 'basic' };
+  return { score: 10, ok: true, quality: 'thin' };
+}
+
+export function scoreSchema(schemaTypes) {
+  const types = new Set((schemaTypes || []).filter(Boolean));
+  let score = 0;
+  if (types.size) score += 10;
+  if ([...types].some((item) => BRAND_SCHEMA_TYPES.has(item))) score += 12;
+  if ([...types].some((item) => RICH_SCHEMA_TYPES.has(item))) score += 8;
+  return {
+    score,
+    ok: types.size > 0,
+    types: [...types].sort(),
+    hasBrand: [...types].some((item) => BRAND_SCHEMA_TYPES.has(item)),
+    hasRich: [...types].some((item) => RICH_SCHEMA_TYPES.has(item)),
+  };
+}
+
+export function scoreRobots(parsed) {
+  let score = 0;
+  if (parsed.agents.gptbot === 'allow') score += 14;
+  if (parsed.agents.claudebot === 'allow') score += 14;
+  if (SECONDARY_AGENTS.every((agent) => parsed.agents[agent] === 'allow')) score += 8;
+  if (parsed.present) score += 4;
+  return {
+    score,
+    ok: !parsed.blocksAi,
+    present: parsed.present,
+    blocksAi: parsed.blocksAi,
+    blocksAll: parsed.blocksAll,
+    agents: parsed.agents,
+  };
+}
+
+export function aiReadiness({ robots, llmsExists, llmsText, schemaTypes }) {
+  const robotsPart = scoreRobots(robots);
+  const llmsPart = scoreLlms(llmsText, llmsExists);
+  const schemaPart = scoreSchema(schemaTypes);
+  return {
+    score: Math.min(100, robotsPart.score + llmsPart.score + schemaPart.score),
+    robots: robotsPart,
+    llms: llmsPart,
+    schema: schemaPart,
+  };
+}

package/src/cli.js

@@ -0,0 +1,123 @@
+import path from 'node:path';
+import { isPreviewHost } from './ai-access.js';
+import { discoverLocal } from './discover.js';
+import { exitCode, findingsFromLive, findingsFromLocal } from './findings.js';
+import { githubAnnotations, jsonReport, markdownReport, textReport } from './report.js';
+import { pullRequestNumber, upsertPullRequestComment } from './github.js';
+import { liveSnapshot } from './live.js';
+import { publishAudit } from './publish.js';
+
+const HELP = `FoxyGEO AI Readiness linter
+
+Usage:
+  npx @foxygeo/audit
+  npx @foxygeo/audit .
+  npx @foxygeo/audit example.com
+  npx @foxygeo/audit --ci --publish example.com
+
+Options:
+  --publish <domain>  Create/update the public report on foxygeo.com
+  --no-publish        Skip publishing even when a domain is given
+  --ci                GitHub annotations + sticky PR comment
+  --format <name>     text | json | github   (default: text, github in --ci)
+  --fail-on <level>   error | warning | never
+  --root <dir>        Repo root for local file discovery
+  -h, --help          Show this help
+`;
+
+export function parseArgs(argv) {
+  const args = {
+    target: null,
+    publish: process.env.FOXYGEO_DOMAIN || '',
+    ci: false,
+    format: '',
+    failOn: process.env.FOXYGEO_FAIL_ON || 'error',
+    noPublish: process.env.FOXYGEO_PUBLISH === 'false',
+    root: process.cwd(),
+    help: false,
+  };
+  const positional = [];
+  for (let i = 0; i < argv.length; i += 1) {
+    const token = argv[i];
+    if (token === '--ci') args.ci = true;
+    else if (token === '--no-publish') args.noPublish = true;
+    else if (token === '--publish') args.publish = argv[++i] || '';
+    else if (token === '--format') args.format = argv[++i] || '';
+    else if (token === '--fail-on') args.failOn = argv[++i] || 'error';
+    else if (token === '--root') args.root = argv[++i] || args.root;
+    else if (token === '--help' || token === '-h') args.help = true;
+    else if (token.startsWith('-')) throw new Error(`Unknown option ${token}`);
+    else positional.push(token);
+  }
+  args.target = positional[0] || null;
+  if (!args.format) args.format = args.ci ? 'github' : 'text';
+  if (process.env.GITHUB_ACTIONS === 'true') args.ci = true;
+  return args;
+}
+
+export function looksLikeDomain(value) {
+  if (!value || value === '.' || value === './') return false;
+  if (value.includes('/') || value.includes('\\')) return false;
+  return /^[a-z0-9.-]+\.[a-z]{2,}$/i.test(value);
+}
+
+export async function run(argv, { stdout = process.stdout, stderr = process.stderr, env = process.env, fetchImpl = fetch } = {}) {
+  const args = parseArgs(argv);
+  if (args.help) {
+    stdout.write(`${HELP}\n`);
+    return 0;
+  }
+
+  const domainTarget = looksLikeDomain(args.target) ? args.target : (looksLikeDomain(args.publish) ? args.publish : '');
+  let result;
+  if (domainTarget) {
+    result = findingsFromLive(await liveSnapshot(domainTarget));
+  } else {
+    const local = await discoverLocal(path.resolve(args.root, args.target && !looksLikeDomain(args.target) ? args.target : '.'));
+    result = findingsFromLocal(local);
+    if (!local.robots && !local.llms && local.htmlFiles.length === 0) {
+      stderr.write('No robots.txt, llms.txt, or HTML files found. Pass a domain: npx @foxygeo/audit example.com\n');
+    }
+  }
+
+  let publicUrl = null;
+  const publishDomain = args.noPublish ? '' : (args.publish || domainTarget);
+  if (publishDomain && looksLikeDomain(publishDomain) && !isPreviewHost(publishDomain)) {
+    try {
+      const published = await publishAudit(publishDomain, { fetchImpl });
+      if (published.published) publicUrl = published.publicUrl;
+      else if (published.reason !== 'preview-host') {
+        stderr.write(`Publish skipped (${published.reason}). Local lint results still apply.\n`);
+      }
+    } catch (error) {
+      stderr.write(`Publish failed: ${error instanceof Error ? error.message : error}. Local lint results still apply.\n`);
+    }
+  }
+
+  if (args.format === 'json') {
+    stdout.write(`${JSON.stringify(jsonReport(result, { publicUrl }), null, 2)}\n`);
+  } else if (args.format === 'github') {
+    stdout.write(`${markdownReport(result, { publicUrl })}\n`);
+    for (const annotation of githubAnnotations(result)) stdout.write(`${annotation}\n`);
+  } else {
+    stdout.write(`${textReport(result, { publicUrl })}\n`);
+  }
+
+  if (args.ci && env.GITHUB_TOKEN && env.GITHUB_REPOSITORY) {
+    const number = await pullRequestNumber({ eventPath: env.GITHUB_EVENT_PATH, ref: env.GITHUB_REF });
+    if (number) {
+      const body = markdownReport(result, { publicUrl });
+      const posted = await upsertPullRequestComment({
+        token: env.GITHUB_TOKEN,
+        repository: env.GITHUB_REPOSITORY,
+        number,
+        body,
+        apiBase: env.GITHUB_API_URL,
+        fetchImpl,
+      });
+      if (!posted.posted) stderr.write(`PR comment skipped (${posted.reason}).\n`);
+    }
+  }
+
+  return exitCode(result, args.failOn);
+}

package/src/discover.js

@@ -0,0 +1,88 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+const IGNORE_DIRS = new Set([
+  '.git',
+  'node_modules',
+  'dist',
+  'build',
+  'coverage',
+  '.next',
+  '.nuxt',
+  '.output',
+  'vendor',
+  '.turbo',
+  '.cache',
+  'out',
+]);
+
+const TEXT_CANDIDATES = [
+  'robots.txt',
+  'public/robots.txt',
+  'static/robots.txt',
+  'app/robots.txt',
+  'src/robots.txt',
+  'llms.txt',
+  'public/llms.txt',
+  'static/llms.txt',
+  'llms-full.txt',
+  'public/llms-full.txt',
+];
+
+const HTML_EXT = new Set(['.html', '.htm', '.php']);
+
+export async function readIfExists(filePath) {
+  try {
+    return await fs.readFile(filePath, 'utf8');
+  } catch {
+    return null;
+  }
+}
+
+export async function findNamedFile(root, names) {
+  for (const relative of names) {
+    const full = path.join(root, relative);
+    const text = await readIfExists(full);
+    if (text !== null) return { path: full, relative, text };
+  }
+  return null;
+}
+
+export async function discoverLocal(root, { maxHtml = 40 } = {}) {
+  const robots = await findNamedFile(root, TEXT_CANDIDATES.filter((item) => item.endsWith('robots.txt')));
+  const llms = await findNamedFile(root, TEXT_CANDIDATES.filter((item) => item.includes('llms')));
+  const htmlFiles = [];
+  await walk(root, root, htmlFiles, maxHtml);
+  return { root, robots, llms, htmlFiles };
+}
+
+async function walk(root, current, htmlFiles, maxHtml) {
+  if (htmlFiles.length >= maxHtml) return;
+  let entries;
+  try {
+    entries = await fs.readdir(current, { withFileTypes: true });
+  } catch {
+    return;
+  }
+  for (const entry of entries) {
+    if (htmlFiles.length >= maxHtml) return;
+    if (entry.name.startsWith('.') && entry.name !== '.html') {
+      if (IGNORE_DIRS.has(entry.name)) continue;
+      if (entry.isDirectory()) continue;
+    }
+    const full = path.join(current, entry.name);
+    if (entry.isDirectory()) {
+      if (IGNORE_DIRS.has(entry.name)) continue;
+      await walk(root, full, htmlFiles, maxHtml);
+      continue;
+    }
+    if (!HTML_EXT.has(path.extname(entry.name).toLowerCase())) continue;
+    const text = await readIfExists(full);
+    if (text === null) continue;
+    htmlFiles.push({
+      path: full,
+      relative: path.relative(root, full),
+      text,
+    });
+  }
+}

package/src/findings.js

@@ -0,0 +1,97 @@
+import { PRIMARY_AGENTS, SECONDARY_AGENTS, aiReadiness, parseRobots } from './ai-access.js';
+import { extractSchemaTypes } from './schema.js';
+
+export function findingsFromLocal({ robots, llms, htmlFiles }) {
+  const robotsText = robots?.text || '';
+  const parsed = parseRobots(robots ? robotsText : null);
+  const schemaTypes = [...new Set((htmlFiles || []).flatMap((file) => extractSchemaTypes(file.text)))];
+  const readiness = aiReadiness({
+    robots: parsed,
+    llmsExists: Boolean(llms),
+    llmsText: llms?.text || '',
+    schemaTypes,
+  });
+  return buildResult({
+    mode: 'local',
+    robotsPath: robots?.relative || null,
+    llmsPath: llms?.relative || null,
+    parsed,
+    readiness,
+    schemaTypes,
+  });
+}
+
+export function findingsFromLive(snapshot) {
+  const readiness = aiReadiness({
+    robots: snapshot.robots.parsed,
+    llmsExists: snapshot.llms.exists,
+    llmsText: snapshot.llms.text,
+    schemaTypes: snapshot.homepage.schemaTypes,
+  });
+  return buildResult({
+    mode: 'live',
+    robotsPath: snapshot.robots.exists ? '/robots.txt' : null,
+    llmsPath: snapshot.llms.exists ? '/llms.txt' : null,
+    parsed: snapshot.robots.parsed,
+    readiness,
+    schemaTypes: snapshot.homepage.schemaTypes,
+    domain: snapshot.domain,
+  });
+}
+
+function buildResult({ mode, robotsPath, llmsPath, parsed, readiness, schemaTypes, domain = null }) {
+  const findings = [];
+  if (parsed.agents.gptbot === 'block') {
+    findings.push({ severity: 'error', id: 'gptbot-blocked', message: 'robots.txt blocks GPTBot at /' });
+  }
+  if (parsed.agents.claudebot === 'block') {
+    findings.push({ severity: 'error', id: 'claudebot-blocked', message: 'robots.txt blocks ClaudeBot at /' });
+  }
+  if (parsed.blocksAll) {
+    findings.push({ severity: 'error', id: 'robots-blocks-all', message: 'User-agent * disallows /' });
+  }
+  for (const agent of SECONDARY_AGENTS) {
+    if (parsed.agents[agent] === 'block') {
+      findings.push({ severity: 'warning', id: `${agent}-blocked`, message: `robots.txt blocks ${agent}` });
+    }
+  }
+  if (!readiness.llms.ok) {
+    findings.push({ severity: 'warning', id: 'llms-missing', message: 'llms.txt is missing' });
+  } else if (readiness.llms.quality === 'thin') {
+    findings.push({ severity: 'warning', id: 'llms-thin', message: 'llms.txt exists but is too thin to guide AI crawlers' });
+  }
+  if (!readiness.schema.ok) {
+    findings.push({ severity: 'warning', id: 'schema-missing', message: 'No JSON-LD schema types found' });
+  } else if (!readiness.schema.hasBrand) {
+    findings.push({ severity: 'info', id: 'schema-brand', message: 'Add Organization or WebSite JSON-LD' });
+  }
+  if (!parsed.present) {
+    findings.push({ severity: 'info', id: 'robots-missing', message: 'No robots.txt found; AI crawlers are allowed by default' });
+  }
+
+  const failed = findings.some((item) => item.severity === 'error');
+  const warned = findings.some((item) => item.severity === 'warning');
+  return {
+    mode,
+    domain,
+    score: readiness.score,
+    robotsPath,
+    llmsPath,
+    gptbot: parsed.agents.gptbot,
+    claudebot: parsed.agents.claudebot,
+    agents: parsed.agents,
+    schemaTypes,
+    readiness,
+    findings,
+    failed,
+    warned,
+    primaryOpen: PRIMARY_AGENTS.every((agent) => parsed.agents[agent] === 'allow'),
+  };
+}
+
+export function exitCode(result, failOn = 'error') {
+  if (failOn === 'never') return 0;
+  if (result.failed) return 1;
+  if (failOn === 'warning' && result.warned) return 1;
+  return 0;
+}

package/src/github.js

@@ -0,0 +1,48 @@
+import fs from 'node:fs/promises';
+import { MARKER } from './report.js';
+
+export async function pullRequestNumber({ eventPath = process.env.GITHUB_EVENT_PATH, ref = process.env.GITHUB_REF } = {}) {
+  if (eventPath) {
+    try {
+      const event = JSON.parse(await fs.readFile(eventPath, 'utf8'));
+      const number = event.pull_request?.number || event.number;
+      if (number) return Number(number);
+    } catch {
+      // Fall through to ref parsing.
+    }
+  }
+  const match = String(ref || '').match(/^refs\/pull\/(\d+)\//);
+  return match ? Number(match[1]) : null;
+}
+
+export async function upsertPullRequestComment({
+  token,
+  repository,
+  number,
+  body,
+  apiBase = process.env.GITHUB_API_URL || 'https://api.github.com',
+  fetchImpl = fetch,
+}) {
+  if (!token || !repository || !number) return { posted: false, reason: 'missing-github-context' };
+  const headers = {
+    accept: 'application/vnd.github+json',
+    authorization: `Bearer ${token}`,
+    'x-github-api-version': '2022-11-28',
+    'user-agent': 'foxygeo-audit',
+  };
+  const listUrl = `${apiBase}/repos/${repository}/issues/${number}/comments?per_page=100`;
+  const listed = await fetchImpl(listUrl, { headers });
+  if (!listed.ok) return { posted: false, reason: `list-failed:${listed.status}` };
+  const comments = await listed.json();
+  const existing = Array.isArray(comments) ? comments.find((comment) => String(comment.body || '').includes(MARKER)) : null;
+  const target = existing
+    ? `${apiBase}/repos/${repository}/issues/comments/${existing.id}`
+    : `${apiBase}/repos/${repository}/issues/${number}/comments`;
+  const method = existing ? 'PATCH' : 'POST';
+  const written = await fetchImpl(target, {
+    method,
+    headers: { ...headers, 'content-type': 'application/json' },
+    body: JSON.stringify({ body }),
+  });
+  return { posted: written.ok, reason: written.ok ? (existing ? 'updated' : 'created') : `write-failed:${written.status}` };
+}

package/src/index.js

@@ -0,0 +1,5 @@
+export { aiReadiness, isPreviewHost, parseRobots } from './ai-access.js';
+export { discoverLocal } from './discover.js';
+export { findingsFromLive, findingsFromLocal, exitCode } from './findings.js';
+export { markdownReport, textReport } from './report.js';
+export { parseArgs, run } from './cli.js';

package/src/live.js

@@ -0,0 +1,60 @@
+import { extractSchemaTypes } from './schema.js';
+import { parseRobots } from './ai-access.js';
+
+const TIMEOUT_MS = 8000;
+
+async function fetchText(url) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), TIMEOUT_MS);
+  try {
+    const response = await fetch(url, {
+      redirect: 'follow',
+      signal: controller.signal,
+      headers: {
+        'user-agent': 'FoxyGEO-Audit/0.1 (+https://foxygeo.com/tools/cli-audit)',
+        accept: 'text/html,text/plain,*/*',
+      },
+    });
+    const text = response.ok ? await response.text() : '';
+    return { ok: response.ok, status: response.status, url: response.url, text: text.slice(0, 512_000) };
+  } catch {
+    return { ok: false, status: 0, url, text: '' };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+async function firstOk(urls) {
+  let last = { ok: false, status: 0, url: urls[0], text: '' };
+  for (const url of urls) {
+    last = await fetchText(url);
+    if (last.ok) return last;
+  }
+  return last;
+}
+
+export async function liveSnapshot(domain) {
+  const host = domain.replace(/^https?:\/\//, '').replace(/\/.*$/, '').replace(/^www\./, '');
+  const [robots, llms, home] = await Promise.all([
+    firstOk([`https://${host}/robots.txt`, `http://${host}/robots.txt`]),
+    firstOk([`https://${host}/llms.txt`, `http://${host}/llms.txt`]),
+    firstOk([`https://${host}/`, `http://${host}/`]),
+  ]);
+  return {
+    domain: host,
+    robots: {
+      exists: robots.ok,
+      text: robots.ok ? robots.text : '',
+      parsed: parseRobots(robots.ok ? robots.text : null),
+    },
+    llms: {
+      exists: llms.ok,
+      text: llms.ok ? llms.text : '',
+    },
+    homepage: {
+      exists: home.ok,
+      url: home.url,
+      schemaTypes: home.ok ? extractSchemaTypes(home.text) : [],
+    },
+  };
+}

package/src/publish.js

@@ -0,0 +1,33 @@
+import { isPreviewHost } from './ai-access.js';
+
+const DEFAULT_API = 'https://foxygeo.com';
+
+export async function publishAudit(domain, { apiBase = process.env.FOXYGEO_API_URL || DEFAULT_API, fetchImpl = fetch } = {}) {
+  const host = String(domain || '').replace(/^https?:\/\//, '').replace(/\/.*$/, '').replace(/^www\./, '').toLowerCase();
+  if (!host) throw new Error('A public domain is required to publish an audit');
+  if (isPreviewHost(host)) {
+    return { published: false, reason: 'preview-host', publicUrl: null };
+  }
+  const response = await fetchImpl(`${apiBase.replace(/\/$/, '')}/api/v1/cli/audits`, {
+    method: 'POST',
+    headers: {
+      accept: 'application/json',
+      'content-type': 'application/json',
+      'user-agent': 'foxygeo-audit/0.1',
+    },
+    body: JSON.stringify({ domain: host, source: 'cli' }),
+  });
+  if (!response.ok) {
+    const detail = await response.text();
+    return { published: false, reason: `api:${response.status}`, detail: detail.slice(0, 300), publicUrl: null };
+  }
+  const payload = await response.json();
+  return {
+    published: true,
+    reused: Boolean(payload.reused),
+    publicUrl: payload.public_url,
+    reportUrl: payload.report_url,
+    aiReadiness: payload.ai_readiness,
+    geoScore: payload.geo_score,
+  };
+}

package/src/report.js

@@ -0,0 +1,61 @@
+const MARKER = '<!-- foxygeo-audit -->';
+
+export function markdownReport(result, { publicUrl = null } = {}) {
+  const icon = result.score >= 85 ? '✅' : result.score >= 60 ? '⚠️' : '❌';
+  const rows = [
+    `| llms.txt | ${result.readiness.llms.ok ? `pass (${result.readiness.llms.quality})` : 'missing'} |`,
+    `| GPTBot | ${result.gptbot === 'allow' ? 'allowed' : 'blocked'} |`,
+    `| ClaudeBot | ${result.claudebot === 'allow' ? 'allowed' : 'blocked'} |`,
+    `| Schema | ${result.schemaTypes.length ? result.schemaTypes.slice(0, 6).join(', ') : 'none'} |`,
+  ];
+  const findingLines = result.findings.length
+    ? result.findings.map((item) => `- **${item.severity}:** ${item.message}`).join('\n')
+    : '- No blocking issues.';
+  const link = publicUrl
+    ? `\n**Public audit:** ${publicUrl}\n`
+    : '\n';
+  return `${MARKER}
+## ${icon} FoxyGEO AI Readiness: ${result.score}/100
+
+| Check | Status |
+| --- | --- |
+${rows.join('\n')}
+${link}
+${findingLines}
+
+<sub>Run locally: <code>npx @foxygeo/audit</code> · [docs](https://foxygeo.com/tools/cli-audit)</sub>
+`;
+}
+
+export function textReport(result, { publicUrl = null } = {}) {
+  const lines = [
+    `FoxyGEO AI Readiness: ${result.score}/100`,
+    `llms.txt: ${result.readiness.llms.ok ? result.readiness.llms.quality : 'missing'}`,
+    `GPTBot: ${result.gptbot}`,
+    `ClaudeBot: ${result.claudebot}`,
+    `Schema: ${result.schemaTypes.join(', ') || 'none'}`,
+  ];
+  if (publicUrl) lines.push(`Public audit: ${publicUrl}`);
+  for (const finding of result.findings) {
+    lines.push(`[${finding.severity}] ${finding.message}`);
+  }
+  return lines.join('\n');
+}
+
+export function jsonReport(result, extras = {}) {
+  return {
+    tool: 'foxygeo-audit',
+    score: result.score,
+    ...result,
+    ...extras,
+  };
+}
+
+export function githubAnnotations(result) {
+  return result.findings.map((item) => {
+    const level = item.severity === 'error' ? 'error' : item.severity === 'warning' ? 'warning' : 'notice';
+    return `::${level}::${item.message}`;
+  });
+}
+
+export { MARKER };

package/src/schema.js

@@ -0,0 +1,31 @@
+export function extractSchemaTypes(html) {
+  const types = new Set();
+  if (!html) return [];
+  const scriptRe = /<script[^>]*type=["']application\/ld\+json["'][^>]*>([\s\S]*?)<\/script>/gi;
+  let match;
+  while ((match = scriptRe.exec(html))) {
+    const raw = match[1].trim();
+    if (!raw) continue;
+    try {
+      walk(JSON.parse(raw), types);
+    } catch {
+      // Ignore broken JSON-LD blocks; the linter still reports missing coverage.
+    }
+  }
+  return [...types];
+}
+
+function walk(node, types) {
+  if (!node) return;
+  if (Array.isArray(node)) {
+    for (const item of node) walk(item, types);
+    return;
+  }
+  if (typeof node !== 'object') return;
+  const value = node['@type'];
+  if (typeof value === 'string') types.add(value);
+  else if (Array.isArray(value)) {
+    for (const item of value) if (typeof item === 'string') types.add(item);
+  }
+  for (const child of Object.values(node)) walk(child, types);
+}