ai-warden 1.0.4 → 1.1.1

package/README.md

@@ -253,34 +253,115 @@ console.log(detector.removePII(text));  // Quick remove
 
 ## 🎮 CLI Usage
 
-AI-Warden includes a command-line tool for file and directory scanning.
+AI-Warden includes a command-line tool for file, directory, and skill repo scanning.
 
 ```bash
 # Install globally
 npm install -g ai-warden
+```
 
-# Scan a file
-aiwarden scan file.txt
+### 🆓 Offline Commands (Free — no API key needed)
 
-# Scan a directory
-aiwarden scan ./src
+These run entirely on your machine. No data leaves your system.
 
-# Scan with options
+```bash
+# Scan local files and directories
+aiwarden scan file.txt
+aiwarden scan ./src
 aiwarden scan ./src --mode strict --verbose
-
-# Interactive whitelist mode
 aiwarden scan ./src --interactive
 
-# Use custom ignore file
-aiwarden scan ./src --ignore-file .aiwardenignore.ci
+# Scan remote skill repos (local pattern matching)
+aiwarden scan-skill https://github.com/user/skill --offline
+aiwarden scan-skill https://github.com/user/skill --offline --json
+aiwarden scan-skill https://github.com/user/skill --offline --strict
+```
+
+### 🔑 API Key Setup (required for API-powered features)
+
+```bash
+# Login (opens browser, saves key locally)
+aiwarden login
+
+# Check your current key and tier
+aiwarden whoami
+
+# Or set key manually
+export AI_WARDEN_API_KEY=sk_live_xxx
+```
+
+Get your API key: [ai-warden.io/signup](https://ai-warden.io/signup) (free tier: 5,000 validations/month)
+
+### 🚀 API-Powered Commands (requires API key)
+
+Full Judge Mars ML analysis — near-zero false positives, deeper detection.
+
+```bash
+# Validate text input
+aiwarden validate "User input text"
+aiwarden validate "Text to check" --json
+
+# Scan skill repos with ML engine
+aiwarden scan-skill https://github.com/user/skill
+aiwarden scan-skill https://github.com/user/skill --json --strict
 ```
 
-**CLI Options:**
+### CLI Options
+
+**Scan options:**
 - `--mode <strict|balanced|permissive>` - Detection sensitivity
 - `--verbose` - Detailed output
 - `--interactive` - Interactive whitelist mode
 - `--ignore-file <path>` - Custom .aiwardenignore file
 
+**Scan-skill options:**
+- `--offline` - Use local scanner only (free, no API key)
+- `--json` - Machine-readable JSON output
+- `--strict` - Exit code 1 unless verdict is SAFE
+
+---
+
+## 🔍 Skill Scanner — Example Output
+
+```
+🔍 AI-Warden Skill Scan
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  Skill:    smart-web-search
+  Source:   github.com/davidme6/smart-web-search
+  Files:    4 scanned
+  Mode:     offline
+
+  LICENSE                  ✅ Safe       (0.00)
+  README.md                ❌ CRITICAL   (1.00)
+    ├─ P102: Data Forwarding Instructions [CRITICAL] — "Email**: smart-web-search@feedback.com"
+    └─ H003: Excessive External URLs [LOW] — "Found 11 external URLs"
+  SKILL.md                 ✅ Safe       (0.19)
+    └─ H003: Excessive External URLs [LOW] — "Found 20 external URLs"
+  _meta.json               ✅ Safe       (0.00)
+
+  Verdict:     ❌ DANGEROUS
+  Trust Score: 0/100
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+### Verdicts
+
+| Verdict | Trust Score | Meaning |
+|---------|-------------|---------|
+| ✅ SAFE | 70-100 | No threats detected |
+| ⚠️ WARNING | 25-69 | Suspicious patterns found, review recommended |
+| ❌ DANGEROUS | 0-24 | Active threats detected, do not install |
+
+### Offline vs API Mode
+
+| | Offline (free) | API (metered) |
+|---|---|---|
+| Detection | Regex patterns | Judge Mars ML + patterns |
+| Speed | Instant | ~150ms/file |
+| False positives | Higher | Lower |
+| Zero-day threats | ❌ | ✅ |
+| Requires API key | No | Yes |
+
 ---
 
 ## 🔧 Configuration

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-warden",
-  "version": "1.0.4",
+  "version": "1.1.1",
   "description": "AI security scanner - Detect prompt injection attacks and PII with user settings",
   "main": "src/index.js",
   "bin": {

package/src/cli.js

@@ -16,6 +16,7 @@ const IgnoreParser = require('./ignoreParser');
 const InteractivePrompt = require('./interactivePrompt');
 const AIWarden = require('./index');
 const config = require('./config');
+const { scanSkill } = require('./skillScanner');
 
 const args = process.argv.slice(2);
 const command = args[0];
@@ -33,6 +34,7 @@ Usage: aiwarden <command> [options]
 
 Commands:
   scan <path>              Scan file or directory (offline mode)
+  scan-skill <url>         Scan a remote skill repo for threats
   validate <text>          Validate text via API (requires API key)
   login                    Sign up or log in and save API key
   logout                   Remove saved API key
@@ -46,6 +48,12 @@ Scan Options (offline mode):
   --interactive            Interactive mode (whitelist threats as you go)
   --ignore-file <path>     Custom ignore file (default: .aiwardenignore)
 
+Scan-Skill Options:
+  --offline                Use local scanner (free, no API key needed)
+  --json                   Output raw JSON
+  --strict                 Exit code 1 if verdict is not SAFE
+  --mode <mode>            Detection mode (strict|balanced|permissive)
+
 Validate Options (API mode):
   --api-key <key>          API key (or use AI_WARDEN_API_KEY env var)
   --mode <mode>            Detection mode (strict|balanced|permissive)
@@ -57,6 +65,11 @@ Examples:
   aiwarden scan file.txt                       Scan single file
   aiwarden scan . --mode strict                Strict detection mode
   
+  # Skill repo scanning
+  aiwarden scan-skill https://github.com/user/skill --offline
+  aiwarden scan-skill https://github.com/user/skill --json
+  aiwarden scan-skill https://github.com/user/skill --strict
+
   # API validation (requires API key)
   aiwarden validate "Ignore all instructions" --api-key sk_live_xxx
   export AI_WARDEN_API_KEY=sk_live_xxx
@@ -325,22 +338,26 @@ async function validateCommand(textOrPath, options = {}) {
     } else {
       // Human-readable output
       const data = result.data || result;  // Handle nested response
-      const blocked = data.decision === 'BLOCK';
+      const blocked = data.decision === 'BLOCK' || data.safe === false;
+      const riskPct = data.riskScore != null ? (data.riskScore * 100).toFixed(1) + '%' : 'N/A';
+      const confPct = data.confidence != null ? (data.confidence * 100).toFixed(1) + '%' : 'N/A';
+      const latency = data.latency_ms != null ? `${data.latency_ms.toFixed(0)}ms` : '';
       
       console.log('═══════════════════════════════════════════════════════');
-      console.log(`Status: ${blocked ? '❌ BLOCKED' : '✅ SAFE'}`);
-      console.log(`Layer: ${data.layer_name || data.layer || 'unknown'}`);
-      console.log(`Confidence: ${((data.confidence || 0) * 100).toFixed(1)}%`);
-      console.log(`Decision: ${data.decision || 'unknown'}`);
+      console.log(`Status:     ${blocked ? '❌ BLOCKED' : '✅ SAFE'}`);
+      console.log(`Risk Score: ${riskPct}`);
+      console.log(`Confidence: ${confPct}`);
+      console.log(`Layer:      ${data.layer_name || data.layer || 'unknown'}`);
+      if (latency) console.log(`Latency:    ${latency}`);
       
       // Show sandwich info if used
       if (data.sandwich && data.sandwich.enabled) {
-        console.log(`Scanned: ${data.sandwich.scannedWords.toLocaleString()} words (head + tail)`);
-        console.log(`Original: ${data.sandwich.originalWords.toLocaleString()} words`);
+        console.log(`Scanned:    ${data.sandwich.scannedWords.toLocaleString()} words (head + tail)`);
+        console.log(`Original:   ${data.sandwich.originalWords.toLocaleString()} words`);
       }
       
       if (data.reason) {
-        console.log(`Reason: ${data.reason}`);
+        console.log(`Reason:     ${data.reason}`);
       }
       
       if (data.cleanText && data.cleanText !== text) {
@@ -351,7 +368,7 @@ async function validateCommand(textOrPath, options = {}) {
       console.log('═══════════════════════════════════════════════════════');
     }
 
-    process.exit((result.data || result).decision === 'BLOCK' ? 1 : 0);
+    process.exit((result.data || result).decision === 'BLOCK' || (result.data || result).safe === false ? 1 : 0);
 
   } catch (error) {
     console.error('❌ Validation failed:', error.message);
@@ -390,6 +407,10 @@ function parseArgs() {
     } else if (args[i] === '--ignore-file' && args[i + 1]) {
       options.ignoreFile = args[i + 1];
       i++;
+    } else if (args[i] === '--offline') {
+      options.offline = true;
+    } else if (args[i] === '--strict') {
+      options.strict = true;
     }
   }
 
@@ -617,6 +638,15 @@ function whoamiCommand() {
     const targetPath = args[1];
     const options = parseArgs();
     scanCommand(targetPath, options);
+  } else if (command === 'scan-skill') {
+    const url = args[1];
+    if (!url) {
+      console.error('❌ Error: No URL specified');
+      console.log('Usage: aiwarden scan-skill <url> [--offline] [--json] [--strict]');
+      process.exit(1);
+    }
+    const options = parseArgs();
+    await scanSkill(url, options);
   } else if (command === 'validate') {
     const text = args[1];
     const options = parseArgs();

package/src/client.js

@@ -79,10 +79,10 @@ class AIWardenClient {
         path: urlObj.pathname + urlObj.search,
         method: 'GET',
         headers: {
-          'Authorization': `Bearer ${this.apiKey}`,
+          'X-API-Key': this.apiKey,
           'Content-Type': 'application/json',
-          'Cache-Control': 'no-cache',  // Prevent Cloudflare from caching and stripping auth header
-          'User-Agent': 'ai-warden-sdk/0.7.0'
+          'Cache-Control': 'no-cache',
+          'User-Agent': 'ai-warden-sdk/1.1.0'
         },
         timeout: this.timeout
       };
@@ -140,10 +140,9 @@ class AIWardenClient {
       await this.init();
     }
 
-    const url = `${this.apiUrl}/api/validate`;
+    const url = `${this.apiUrl}/v1/validate`;
     const payload = {
       text: content,  // API expects 'text', not 'content'
-      // Don't send settings - backend ignores them anyway and Cloudflare WAF blocks large payloads
       ...options
     };
 
@@ -157,10 +156,10 @@ class AIWardenClient {
         path: urlObj.pathname + urlObj.search,
         method: 'POST',
         headers: {
-          'Authorization': `Bearer ${this.apiKey}`,
+          'X-API-Key': this.apiKey,
           'Content-Type': 'application/json',
           'Content-Length': Buffer.byteLength(body),
-          'User-Agent': 'ai-warden-sdk/0.7.0'
+          'User-Agent': 'ai-warden-sdk/1.1.0'
         },
         timeout: this.timeout
       };
@@ -181,11 +180,33 @@ class AIWardenClient {
           if (res.statusCode === 200) {
             try {
               const parsed = JSON.parse(data);
-              // Extract cleanText if present
+              // Normalize API response to match scan() format
+              const passed = parsed.safe === true || parsed.decision === 'ALLOW';
+              const confidence = parsed.confidence || 0;
+              const riskScore = passed ? 0 : Math.round(confidence * 1000);
+
+              let riskLevel = 'NONE';
+              if (!passed) {
+                if (confidence >= 0.9) riskLevel = 'CRITICAL';
+                else if (confidence >= 0.7) riskLevel = 'HIGH';
+                else if (confidence >= 0.4) riskLevel = 'MEDIUM';
+                else riskLevel = 'LOW';
+              }
+
               const result = {
-                ...parsed,
+                passed,
+                riskScore,
+                riskLevel,
+                findings: passed ? [] : [{ name: `${parsed.layer || 'cascade'}`, severity: riskLevel }],
                 cleanText: parsed.cleanText || content,
-                appliedSettings: parsed.appliedSettings || this.settings
+                appliedSettings: parsed.appliedSettings || this.settings,
+                stats: {
+                  scanTimeMs: parsed.latency_ms || 0,
+                  layer: parsed.layer,
+                  confidence
+                },
+                // Preserve raw API fields for advanced use
+                raw: { safe: parsed.safe, decision: parsed.decision, confidence: parsed.confidence, layer: parsed.layer }
               };
               resolve(result);
             } catch (error) {

package/src/skillScanner.js

@@ -0,0 +1,483 @@
+/**
+ * Skill Scanner - Scan remote skill repos for prompt injection threats
+ * 
+ * Supports:
+ * - GitHub/ClawHub repo URLs
+ * - Offline mode (local scanner) and API mode
+ * - Batched file scanning for large repos
+ * - Human-readable and JSON output
+ */
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const { execSync } = require('child_process');
+const https = require('https');
+const http = require('http');
+const scanner = require('./scanner');
+const config = require('./config');
+
+const MAX_FILE_SIZE = 100 * 1024; // 100KB
+const BATCH_SIZE = 50;
+
+// Sandwich scan thresholds (match index.js _sandwichScan)
+const HEAD_WORDS = 2000;
+const TAIL_WORDS = 2000;
+const SANDWICH_THRESHOLD = HEAD_WORDS + TAIL_WORDS; // 4000 words
+
+// Binary file extensions to skip
+const BINARY_EXTENSIONS = new Set([
+  '.png', '.jpg', '.jpeg', '.gif', '.webp', '.ico', '.svg',
+  '.woff', '.woff2', '.ttf', '.eot', '.otf',
+  '.zip', '.tar', '.gz', '.bz2', '.7z', '.rar',
+  '.pdf', '.doc', '.docx', '.xls', '.xlsx',
+  '.exe', '.dll', '.so', '.dylib', '.o',
+  '.mp3', '.mp4', '.avi', '.mov', '.wav',
+  '.bin', '.dat', '.db', '.sqlite',
+  '.pyc', '.class', '.wasm',
+]);
+
+/**
+ * Apply sandwich truncation for large file content.
+ * Keeps HEAD_WORDS from the start and TAIL_WORDS from the end.
+ * Returns { content, sandwich } where sandwich is metadata or null.
+ */
+function applySandwich(content) {
+  const words = content.split(/\s+/);
+  if (words.length <= SANDWICH_THRESHOLD) {
+    return { content, sandwich: null };
+  }
+
+  const head = words.slice(0, HEAD_WORDS).join(' ');
+  const tail = words.slice(-TAIL_WORDS).join(' ');
+  const truncated = head + '\n\n[...middle content omitted for performance...]\n\n' + tail;
+
+  return {
+    content: truncated,
+    sandwich: {
+      enabled: true,
+      originalWords: words.length,
+      scannedWords: HEAD_WORDS + TAIL_WORDS,
+    },
+  };
+}
+
+/**
+ * Parse a GitHub URL into { source, owner, repo, name, displayUrl }
+ */
+function parseRepoUrl(url) {
+  // Remove trailing slash and .git
+  url = url.replace(/\/+$/, '').replace(/\.git$/, '');
+
+  const match = url.match(/(?:https?:\/\/)?(?:www\.)?(github\.com|clawhub\.com)\/([^/]+)\/([^/]+)/);
+  if (!match) {
+    throw new Error(`Invalid repository URL: ${url}\nExpected: https://github.com/<owner>/<repo>`);
+  }
+
+  return {
+    source: match[1].replace('.com', ''),
+    owner: match[2],
+    repo: match[3],
+    name: match[3],
+    displayUrl: `${match[1]}/${match[2]}/${match[3]}`,
+    cloneUrl: `https://${match[1]}/${match[2]}/${match[3]}.git`,
+  };
+}
+
+/**
+ * Clone repo to temp directory
+ */
+function cloneRepo(cloneUrl) {
+  const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'ai-warden-scan-'));
+
+  try {
+    execSync(`git clone --depth 1 ${cloneUrl} ${tmpDir}`, {
+      stdio: 'pipe',
+      timeout: 60000, // 60s timeout
+    });
+  } catch (err) {
+    // Clean up on failure
+    cleanupDir(tmpDir);
+    const msg = err.stderr ? err.stderr.toString().trim() : err.message;
+    throw new Error(`Failed to clone repository: ${msg}`);
+  }
+
+  return tmpDir;
+}
+
+/**
+ * Get git SHA of cloned repo
+ */
+function getGitSha(repoDir) {
+  try {
+    return execSync('git rev-parse HEAD', { cwd: repoDir, stdio: 'pipe' })
+      .toString()
+      .trim();
+  } catch {
+    return 'unknown';
+  }
+}
+
+/**
+ * Classify a file by its path/name into a role
+ */
+function classifyFileRole(relativePath) {
+  const basename = path.basename(relativePath);
+  const dir = path.dirname(relativePath);
+  const ext = path.extname(relativePath).toLowerCase();
+
+  if (basename === 'SKILL.md') return 'skill-definition';
+  if (dir.startsWith('scripts') && (ext === '.sh' || ext === '.py')) return 'install-script';
+  if (dir.startsWith('references')) return 'reference-doc';
+  if (['.yaml', '.yml', '.json', '.toml'].includes(ext)) return 'config';
+  if (ext === '.md') return 'documentation';
+  return 'unknown';
+}
+
+/**
+ * Enumerate all text files in a directory (skip binaries, .git, large files)
+ */
+function enumerateFiles(dir, baseDir = dir) {
+  const results = [];
+  const entries = fs.readdirSync(dir, { withFileTypes: true });
+
+  for (const entry of entries) {
+    const fullPath = path.join(dir, entry.name);
+    const relativePath = path.relative(baseDir, fullPath);
+
+    // Skip hidden dirs and node_modules
+    if (entry.name.startsWith('.') || entry.name === 'node_modules') continue;
+
+    if (entry.isDirectory()) {
+      results.push(...enumerateFiles(fullPath, baseDir));
+    } else if (entry.isFile()) {
+      const ext = path.extname(entry.name).toLowerCase();
+      if (BINARY_EXTENSIONS.has(ext)) continue;
+
+      const stat = fs.statSync(fullPath);
+      if (stat.size > MAX_FILE_SIZE) continue;
+      if (stat.size === 0) continue;
+
+      // Try reading as text — skip if binary
+      try {
+        const content = fs.readFileSync(fullPath, 'utf-8');
+        // Quick binary check: if it has null bytes, skip
+        if (content.includes('\0')) continue;
+
+        results.push({
+          path: relativePath,
+          role: classifyFileRole(relativePath),
+          content,
+        });
+      } catch {
+        // Can't read as text, skip
+      }
+    }
+  }
+
+  return results;
+}
+
+/**
+ * Run offline scan on all files using local scanner
+ */
+function scanOffline(files, options = {}) {
+  const startTime = Date.now();
+  const results = [];
+  let worstScore = 0;
+  let anyThreats = false;
+
+  for (const file of files) {
+    const scanOpts = {
+      mode: options.mode || 'balanced',
+      context: file.role === 'skill-definition' ? 'skill' : 'user',
+    };
+
+    const result = scanner.scan(file.content, scanOpts);
+    const normalizedScore = Math.min(result.riskScore / (scanOpts.mode === 'strict' ? 75 : 150), 1.0);
+
+    results.push({
+      path: file.path,
+      role: file.role,
+      safe: result.passed,
+      score: parseFloat(normalizedScore.toFixed(2)),
+      riskLevel: result.riskLevel,
+      findings: result.findings,
+      findingsCount: result.findings.length,
+    });
+
+    if (normalizedScore > worstScore) worstScore = normalizedScore;
+    if (!result.passed) anyThreats = true;
+  }
+
+  const scanTime = ((Date.now() - startTime) / 1000).toFixed(1);
+  const trustScore = Math.max(0, Math.round((1 - worstScore) * 100));
+
+  let verdict;
+  if (!anyThreats && worstScore < 0.3) verdict = 'SAFE';
+  else if (anyThreats) verdict = 'DANGEROUS';
+  else verdict = 'WARNING';
+
+  return {
+    files: results,
+    verdict,
+    trustScore,
+    scanTime,
+    mode: 'offline',
+  };
+}
+
+/**
+ * Send files to API for scanning (batched)
+ */
+async function scanApi(files, repoInfo, options = {}) {
+  const apiKey = options.apiKey || process.env.AI_WARDEN_API_KEY || config.getApiKey();
+  if (!apiKey) {
+    throw new Error('API key required for online scan. Use --offline for free local scanning, or run: aiwarden login');
+  }
+
+  const apiUrl = options.apiUrl || 'https://api.ai-warden.io';
+  const startTime = Date.now();
+
+  // Chunk files into batches
+  const batches = [];
+  for (let i = 0; i < files.length; i += BATCH_SIZE) {
+    batches.push(files.slice(i, i + BATCH_SIZE));
+  }
+
+  const allResults = [];
+
+  for (const batch of batches) {
+    const payload = {
+      skill: {
+        source: repoInfo.source,
+        url: repoInfo.displayUrl,
+        ref: repoInfo.sha,
+        name: repoInfo.name,
+      },
+      files: batch.map(f => {
+        const { content, sandwich } = applySandwich(f.content);
+        const entry = {
+          path: f.path,
+          role: f.role,
+          content,
+        };
+        if (sandwich) entry.sandwich = sandwich;
+        return entry;
+      }),
+    };
+
+    const result = await postJson(`${apiUrl}/v1/scan-skill`, payload, apiKey);
+    if (result.files) {
+      allResults.push(...result.files);
+    }
+  }
+
+  const scanTime = ((Date.now() - startTime) / 1000).toFixed(1);
+
+  // Aggregate verdict from all batches
+  let worstScore = 0;
+  let anyDangerous = false;
+  let anyWarning = false;
+
+  for (const r of allResults) {
+    if (r.score > worstScore) worstScore = r.score;
+    if (r.riskLevel === 'CRITICAL' || r.riskLevel === 'HIGH') anyDangerous = true;
+    if (r.riskLevel === 'MEDIUM') anyWarning = true;
+  }
+
+  const trustScore = Math.max(0, Math.round((1 - worstScore) * 100));
+  let verdict;
+  if (anyDangerous) verdict = 'DANGEROUS';
+  else if (anyWarning) verdict = 'WARNING';
+  else verdict = 'SAFE';
+
+  return {
+    files: allResults,
+    verdict,
+    trustScore,
+    scanTime,
+    mode: 'api',
+  };
+}
+
+/**
+ * POST JSON to URL (using native http/https)
+ */
+function postJson(url, payload, apiKey) {
+  return new Promise((resolve, reject) => {
+    const urlObj = new URL(url);
+    const protocol = urlObj.protocol === 'https:' ? https : http;
+    const body = JSON.stringify(payload);
+
+    const opts = {
+      hostname: urlObj.hostname,
+      path: urlObj.pathname,
+      method: 'POST',
+      headers: {
+        'X-API-Key': apiKey,
+        'Content-Type': 'application/json',
+        'Content-Length': Buffer.byteLength(body),
+        'User-Agent': 'ai-warden-cli/1.0.4',
+      },
+      timeout: 30000,
+    };
+    if (urlObj.port) opts.port = urlObj.port;
+
+    const req = protocol.request(opts, (res) => {
+      let data = '';
+      res.on('data', chunk => data += chunk);
+      res.on('end', () => {
+        if (res.statusCode === 200) {
+          try { resolve(JSON.parse(data)); }
+          catch (e) { reject(new Error(`Invalid API response: ${e.message}`)); }
+        } else if (res.statusCode === 401) {
+          reject(new Error('Invalid API key'));
+        } else {
+          reject(new Error(`API error ${res.statusCode}: ${data}`));
+        }
+      });
+    });
+
+    req.on('error', e => reject(new Error(`Network error: ${e.message}`)));
+    req.on('timeout', () => { req.destroy(); reject(new Error('Request timeout')); });
+    req.write(body);
+    req.end();
+  });
+}
+
+/**
+ * Format human-readable report
+ */
+function formatReport(scanResult, repoInfo) {
+  const lines = [];
+  const bar = '━'.repeat(45);
+
+  lines.push('');
+  lines.push('🔍 AI-Warden Skill Scan');
+  lines.push(bar);
+
+  lines.push(`  Skill:    ${repoInfo.name}`);
+  lines.push(`  Source:   ${repoInfo.displayUrl}`);
+  lines.push(`  Files:    ${scanResult.files.length} scanned`);
+  if (scanResult.mode === 'offline') lines.push(`  Mode:     offline`);
+  lines.push('');
+
+  for (const file of scanResult.files) {
+    const icon = file.safe !== false ? '✅' : '❌';
+    const label = file.safe !== false ? 'Safe' : file.riskLevel || 'Threat';
+    const score = `(${file.score.toFixed(2)})`;
+    const name = file.path.padEnd(25);
+    lines.push(`  ${name}${icon} ${label.padEnd(10)} ${score}`);
+
+    // Show findings detail for flagged files
+    if (file.findings && file.findings.length > 0) {
+      for (let i = 0; i < file.findings.length; i++) {
+        const f = file.findings[i];
+        const isLast = i === file.findings.length - 1;
+        const branch = isLast ? '└─' : '├─';
+        const severity = f.severity || 'UNKNOWN';
+        const detail = f.match || f.detail || '';
+        const truncated = detail.length > 60 ? detail.substring(0, 57) + '...' : detail;
+        lines.push(`    ${branch} ${f.id}: ${f.name} [${severity}]${truncated ? ' — "' + truncated + '"' : ''}`);
+      }
+    }
+  }
+
+  lines.push('');
+
+  const verdictIcon = scanResult.verdict === 'SAFE' ? '✅' : scanResult.verdict === 'WARNING' ? '⚠️' : '❌';
+  lines.push(`  Verdict:     ${verdictIcon} ${scanResult.verdict}`);
+  lines.push(`  Trust Score: ${scanResult.trustScore}/100`);
+  lines.push(`  Scan Time:   ${scanResult.scanTime}s`);
+  lines.push(bar);
+  lines.push('');
+
+  return lines.join('\n');
+}
+
+/**
+ * Clean up temp directory
+ */
+function cleanupDir(dir) {
+  try {
+    fs.rmSync(dir, { recursive: true, force: true });
+  } catch {
+    // Best effort cleanup
+  }
+}
+
+/**
+ * Main entry point for scan-skill command
+ */
+async function scanSkill(url, options = {}) {
+  // 1. Parse URL
+  const repoInfo = parseRepoUrl(url);
+
+  // 2. Clone
+  if (!options.json) {
+    process.stderr.write(`⏳ Cloning ${repoInfo.displayUrl}...\n`);
+  }
+
+  const tmpDir = cloneRepo(repoInfo.cloneUrl);
+
+  try {
+    // Get git SHA
+    repoInfo.sha = getGitSha(tmpDir);
+
+    // 3. Enumerate files
+    const files = enumerateFiles(tmpDir);
+
+    if (files.length === 0) {
+      if (!options.json) {
+        console.log('⚠️  No scannable files found in repository');
+      }
+      process.exit(0);
+    }
+
+    // 4. Scan
+    let result;
+    if (options.offline) {
+      result = scanOffline(files, options);
+    } else {
+      try {
+        result = await scanApi(files, repoInfo, options);
+      } catch (err) {
+        if (!options.json) {
+          console.error(`⚠️  API unavailable (${err.message}), falling back to offline scan`);
+        }
+        result = scanOffline(files, options);
+      }
+    }
+
+    // 5. Output
+    if (options.json) {
+      console.log(JSON.stringify({
+        skill: { name: repoInfo.name, source: repoInfo.source, url: repoInfo.displayUrl, ref: repoInfo.sha },
+        ...result,
+      }, null, 2));
+    } else {
+      console.log(formatReport(result, repoInfo));
+    }
+
+    // 6. Exit code
+    if (options.strict && result.verdict !== 'SAFE') {
+      process.exit(1);
+    }
+
+    process.exit(result.verdict === 'DANGEROUS' ? 1 : 0);
+
+  } finally {
+    // 7. Cleanup
+    cleanupDir(tmpDir);
+  }
+}
+
+module.exports = {
+  scanSkill,
+  parseRepoUrl,
+  classifyFileRole,
+  enumerateFiles,
+  scanOffline,
+  formatReport,
+};