ainative-ax 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,26 @@
-# Temporary Holding Version
+# ainative-ax
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Score how ready a site is for AI agents, from your terminal.
+
+```bash
+npx ainative-ax audit example.com
+```
+
+Wraps the same scoring engine behind [ainative.ax](https://ainative.ax) — no separate backend, no API key required for a quick scan.
+
+## Usage
+
+```bash
+npx ainative-ax audit <url>     Run a quick agent-readiness scan
+npx ainative-ax --help          Show help
+```
+
+Exits with status `1` if the scan is incomplete (score below max) or fails, so it can gate CI.
+
+## What it checks
+
+Discoverability, structured data, API documentation, authentication standards, security transparency, and more — see the full breakdown at [ainative.ax](https://ainative.ax) or run a scan yourself.
+
+## Full reports
+
+This CLI covers the quick scan. For stored reports, industry benchmarks, and remediation, visit [ainative.ax](https://ainative.ax).

package/bin/ainative-ax.js

@@ -0,0 +1,393 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * ainative-ax CLI — thin client for the real, already-live
+ * POST /api/v1/public/ax-audit endpoint. No new backend logic here;
+ * this mirrors services/auditService.ts's runAudit() response shape
+ * (AuditResult / AuditCheck) so CLI and web output never drift apart.
+ */
+
+const https = require('https');
+const { URL } = require('url');
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const readline = require('readline');
+
+const API_BASE = process.env.AINATIVE_AX_API_URL || 'https://ainative-browser-builder.up.railway.app';
+const TIMEOUT_MS = 60000;
+
+// Session token storage: a plain file under the user's config dir, not an
+// OS keychain — this CLI is deliberately dependency-free, and a native
+// keychain binding would mean a compiled dependency. Documented tradeoff,
+// not an oversight. Permissions locked to the owner only (0600).
+const CONFIG_DIR = path.join(os.homedir(), '.config', 'ainative-ax');
+const TOKEN_FILE = path.join(CONFIG_DIR, 'token');
+
+function saveToken(token) {
+  fs.mkdirSync(CONFIG_DIR, { recursive: true, mode: 0o700 });
+  fs.writeFileSync(TOKEN_FILE, token, { mode: 0o600 });
+}
+
+function loadToken() {
+  try {
+    return fs.readFileSync(TOKEN_FILE, 'utf8').trim() || null;
+  } catch {
+    return null;
+  }
+}
+
+function clearStoredToken() {
+  try {
+    fs.unlinkSync(TOKEN_FILE);
+  } catch {
+    // nothing to clear
+  }
+}
+
+// One shared readline interface + its line async-iterator for the whole
+// process, created lazily. A second `readline.createInterface()` call
+// against the same stdin reliably fails to read anything on piped
+// (non-TTY) input — stdin's data gets consumed by the first interface's
+// internal buffering before the second one attaches. Verified directly:
+// two separate interfaces drop the second prompt's answer every time.
+let _rl;
+let _lineIterator;
+function getLineSource() {
+  if (!_rl) {
+    _rl = readline.createInterface({ input: process.stdin, output: process.stdout, terminal: false });
+    _lineIterator = _rl[Symbol.asyncIterator]();
+  }
+  return _lineIterator;
+}
+
+async function prompt(question, { hidden = false } = {}) {
+  const iterator = getLineSource();
+  if (!hidden) {
+    process.stdout.write(question);
+    const { value } = await iterator.next();
+    return value || '';
+  }
+  // Hidden input: mute the interface's own echo of the piped/typed line
+  // while reading it, matching the common Node CLI password-prompt
+  // pattern (no extra dependency for this).
+  const outputStream = _rl._writeToOutput;
+  process.stdout.write(question);
+  _rl._writeToOutput = () => {};
+  const { value } = await iterator.next();
+  _rl._writeToOutput = outputStream;
+  process.stdout.write('\n');
+  return value || '';
+}
+
+function closePrompt() {
+  if (_rl) _rl.close();
+}
+
+function printUsage() {
+  console.log(`
+ainative-ax — score how ready a site is for AI agents
+
+Usage:
+  npx ainative-ax audit <url> [options]   Run an agent-readiness scan
+  npx ainative-ax login                   Sign in (stores a session locally)
+  npx ainative-ax logout                  Clear your stored session
+  npx ainative-ax history [--json]        List your past scans while signed in
+  npx ainative-ax --help                  Show this help
+
+Audit options:
+  --json               Print the raw API response as JSON (no color) —
+                        pipeable into jq or a CI step. Exit code unchanged.
+  --full                Run the full audit (agent simulation + benchmark
+                        percentile) instead of the quick scan.
+  --industry <name>    Industry for the full audit's benchmark comparison
+                        (default: saas). Only used with --full.
+
+Examples:
+  npx ainative-ax audit example.com
+  npx ainative-ax audit https://example.com --json
+  npx ainative-ax audit example.com --full --industry saas
+  npx ainative-ax login
+  npx ainative-ax history
+
+Full reports, benchmarks, and remediation: https://ainative.ax
+`);
+}
+
+function postJSON(path, body, extraHeaders) {
+  return new Promise((resolve, reject) => {
+    const target = new URL(path, API_BASE);
+    const payload = JSON.stringify(body);
+    const req = https.request(
+      target,
+      {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          'Content-Length': Buffer.byteLength(payload),
+          ...extraHeaders,
+        },
+        timeout: TIMEOUT_MS,
+      },
+      (res) => {
+        let data = '';
+        res.on('data', (chunk) => { data += chunk; });
+        res.on('end', () => {
+          let parsed;
+          try {
+            parsed = data ? JSON.parse(data) : {};
+          } catch {
+            reject(new Error(`Unexpected response from ${target}: ${data.slice(0, 200)}`));
+            return;
+          }
+          if (res.statusCode < 200 || res.statusCode >= 300) {
+            reject(new Error(parsed.detail || `API error: ${res.statusCode}`));
+            return;
+          }
+          resolve(parsed);
+        });
+      },
+    );
+    req.on('timeout', () => {
+      req.destroy();
+      reject(new Error(`Request timed out after ${TIMEOUT_MS / 1000}s`));
+    });
+    req.on('error', reject);
+    req.write(payload);
+    req.end();
+  });
+}
+
+function getJSON(path, extraHeaders) {
+  return new Promise((resolve, reject) => {
+    const target = new URL(path, API_BASE);
+    const req = https.request(
+      target,
+      { method: 'GET', headers: { ...extraHeaders }, timeout: TIMEOUT_MS },
+      (res) => {
+        let data = '';
+        res.on('data', (chunk) => { data += chunk; });
+        res.on('end', () => {
+          let parsed;
+          try {
+            parsed = data ? JSON.parse(data) : {};
+          } catch {
+            reject(new Error(`Unexpected response from ${target}: ${data.slice(0, 200)}`));
+            return;
+          }
+          if (res.statusCode < 200 || res.statusCode >= 300) {
+            reject(new Error(parsed.detail || `API error: ${res.statusCode}`));
+            return;
+          }
+          resolve(parsed);
+        });
+      },
+    );
+    req.on('timeout', () => {
+      req.destroy();
+      reject(new Error(`Request timed out after ${TIMEOUT_MS / 1000}s`));
+    });
+    req.on('error', reject);
+    req.end();
+  });
+}
+
+function normalizeUrl(input) {
+  if (!input) return null;
+  return /^https?:\/\//i.test(input) ? input : `https://${input}`;
+}
+
+function gradeColor(grade) {
+  if (grade.startsWith('A')) return '\x1b[32m'; // green
+  if (grade === 'B') return '\x1b[34m'; // blue
+  if (grade === 'C') return '\x1b[33m'; // yellow
+  return '\x1b[31m'; // red (D, F)
+}
+
+const RESET = '\x1b[0m';
+const DIM = '\x1b[2m';
+const BOLD = '\x1b[1m';
+
+function printResult(result) {
+  const color = gradeColor(result.grade);
+  console.log('');
+  console.log(`${BOLD}AX Audit${RESET} ${DIM}·${RESET} ${result.url}`);
+  console.log(`${color}${BOLD}${result.score}/${result.max_score}${RESET}  ${color}Grade ${result.grade}${RESET}`);
+  console.log('');
+
+  for (const check of result.checks || []) {
+    const mark = check.passed ? '\x1b[32m✓\x1b[0m' : '\x1b[31m✗\x1b[0m';
+    const score = `${check.score}/${check.max_score}`;
+    console.log(`  ${mark} ${check.name.padEnd(28)} ${DIM}${score.padStart(6)}${RESET}`);
+    if (check.details) {
+      console.log(`      ${DIM}${check.details}${RESET}`);
+    }
+  }
+
+  console.log('');
+  console.log(`${DIM}Full report, benchmarks, and remediation: https://ainative.ax${RESET}`);
+  console.log('');
+}
+
+function printFullExtras(result) {
+  if (result.benchmark) {
+    const b = result.benchmark;
+    console.log(`${DIM}Benchmark (${b.industry}):${RESET} ${b.measured ? `${BOLD}${b.percentile}th percentile${RESET} — measured` : `${DIM}${b.label}${RESET}`}`);
+    console.log('');
+  }
+  if (result.simulation) {
+    const s = result.simulation;
+    const mark = s.success ? '\x1b[32m✓\x1b[0m' : '\x1b[31m✗\x1b[0m';
+    console.log(`${BOLD}Agent simulation${RESET} ${DIM}·${RESET} ${s.task}`);
+    console.log(`  ${mark} ${s.success ? 'Completed' : `Stalled — ${s.failure_point || 'unknown step'}`} ${DIM}(${s.total_steps} steps, ${s.total_time_ms}ms)${RESET}`);
+    console.log('');
+  }
+}
+
+async function runAudit(rawUrl, { json, full, industry } = {}) {
+  const url = normalizeUrl(rawUrl);
+  if (!url) {
+    if (json) {
+      console.error(JSON.stringify({ error: 'A URL is required. Try: npx ainative-ax audit example.com --json' }));
+    } else {
+      console.error('Error: a URL is required. Try: npx ainative-ax audit example.com');
+    }
+    process.exitCode = 1;
+    return;
+  }
+
+  if (!json) process.stdout.write(`Scanning ${url}${full ? ' (full audit)' : ''} ...`);
+  try {
+    const result = full
+      ? await postJSON('/api/v1/public/ax-audit/full', { url, industry: industry || 'saas' })
+      : await postJSON('/api/v1/public/ax-audit', { url });
+    if (json) {
+      console.log(JSON.stringify(result));
+    } else {
+      process.stdout.write('\r' + ' '.repeat(50) + '\r');
+      printResult(result);
+      if (full) printFullExtras(result);
+    }
+    if (typeof result.score === 'number' && typeof result.max_score === 'number' && result.score < result.max_score) {
+      process.exitCode = 1;
+    }
+  } catch (err) {
+    if (json) {
+      console.error(JSON.stringify({ error: err.message }));
+    } else {
+      process.stdout.write('\r' + ' '.repeat(50) + '\r');
+      console.error(`Scan failed: ${err.message}`);
+    }
+    process.exitCode = 1;
+  }
+}
+
+async function runLogin() {
+  try {
+    const email = await prompt('Email: ');
+    const password = await prompt('Password: ', { hidden: true });
+    try {
+      const result = await postJSON('/api/v1/auth/login', { email, password });
+      if (!result.access_token) {
+        console.error('Login succeeded but no session token was returned — your account may need email verification first.');
+        process.exitCode = 1;
+        return;
+      }
+      saveToken(result.access_token);
+      console.log(`Signed in as ${result.user && result.user.email ? result.user.email : email}.`);
+    } catch (err) {
+      console.error(`Login failed: ${err.message}`);
+      process.exitCode = 1;
+    }
+  } finally {
+    closePrompt();
+  }
+}
+
+function runLogout() {
+  clearStoredToken();
+  console.log('Signed out.');
+}
+
+async function runHistory({ json } = {}) {
+  const token = loadToken();
+  if (!token) {
+    if (json) {
+      console.error(JSON.stringify({ error: 'Not signed in. Run: npx ainative-ax login' }));
+    } else {
+      console.error('Not signed in. Run: npx ainative-ax login');
+    }
+    process.exitCode = 1;
+    return;
+  }
+  try {
+    const result = await getJSON('/api/v1/public/ax-audit/my-scans', { Authorization: `Bearer ${token}` });
+    if (json) {
+      console.log(JSON.stringify(result));
+      return;
+    }
+    const scans = result.scans || [];
+    if (scans.length === 0) {
+      console.log('No scans yet while signed in. Run: npx ainative-ax audit <url>');
+      return;
+    }
+    console.log('');
+    console.log(`${BOLD}Scan history${RESET} ${DIM}· ${result.total} total${RESET}`);
+    console.log('');
+    for (const s of scans) {
+      const color = gradeColor(s.grade);
+      console.log(`  ${color}${String(s.score).padStart(3)}${RESET}  ${DIM}${s.grade.padEnd(3)}${RESET}  ${s.url.padEnd(38)} ${DIM}${s.scanned_at.slice(0, 10)}${RESET}`);
+    }
+    console.log('');
+  } catch (err) {
+    if (json) {
+      console.error(JSON.stringify({ error: err.message }));
+    } else {
+      console.error(`Could not load scan history: ${err.message}`);
+    }
+    process.exitCode = 1;
+  }
+}
+
+async function main() {
+  const [, , command, ...rest] = process.argv;
+
+  if (!command || command === '--help' || command === '-h') {
+    printUsage();
+    return;
+  }
+
+  if (command === 'audit') {
+    const json = rest.includes('--json');
+    const full = rest.includes('--full');
+    const industryIdx = rest.indexOf('--industry');
+    const industry = industryIdx !== -1 ? rest[industryIdx + 1] : undefined;
+    const skipIndexes = new Set([industryIdx, industryIdx === -1 ? -1 : industryIdx + 1]);
+    const target = rest.find((a, i) => a !== '--json' && a !== '--full' && !skipIndexes.has(i));
+    await runAudit(target, { json, full, industry });
+    return;
+  }
+
+  if (command === 'login') {
+    await runLogin();
+    return;
+  }
+
+  if (command === 'logout') {
+    runLogout();
+    return;
+  }
+
+  if (command === 'history') {
+    const json = rest.includes('--json');
+    await runHistory({ json });
+    return;
+  }
+
+  console.error(`Unknown command: ${command}`);
+  printUsage();
+  process.exitCode = 1;
+}
+
+main();

package/package.json

@@ -1,6 +1,31 @@
 {
   "name": "ainative-ax",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Score how ready a site is for AI agents — CLI for AINative's AX Audit. npx ainative-ax audit <url>",
+  "bin": {
+    "ainative-ax": "./bin/ainative-ax.js"
+  },
+  "main": "./bin/ainative-ax.js",
+  "engines": {
+    "node": ">=18"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/AINative-Studio/ainative-ax.git"
+  },
+  "homepage": "https://ainative.ax",
+  "keywords": [
+    "ai",
+    "agents",
+    "agent-readiness",
+    "ax-audit",
+    "llms-txt",
+    "mcp",
+    "seo",
+    "aeo"
+  ],
+  "files": [
+    "bin"
+  ]
+}