shieldcortex 4.2.5 → 4.3.0

package/dist/index.d.ts

@@ -43,6 +43,9 @@
  *   shieldcortex codex install           # Configure MCP server for Codex CLI + VS Code extension
  *   shieldcortex codex uninstall         # Remove Codex MCP configuration
  *   shieldcortex codex status            # Check Codex MCP configuration
+ *   shieldcortex xray <target>           # Inspect package/file/plugin for hidden risk
+ *   shieldcortex xray <path> --deep      # Deep scan (Pro) with full analysis
+ *   shieldcortex xray <package> --json   # JSON output
  *   shieldcortex cortex capture      # Log a mistake with rule extraction
  *   shieldcortex cortex preflight    # Pre-flight check before a task
  *   shieldcortex cortex review       # Weekly pattern review

package/dist/index.js

@@ -43,6 +43,9 @@
  *   shieldcortex codex install           # Configure MCP server for Codex CLI + VS Code extension
  *   shieldcortex codex uninstall         # Remove Codex MCP configuration
  *   shieldcortex codex status            # Check Codex MCP configuration
+ *   shieldcortex xray <target>           # Inspect package/file/plugin for hidden risk
+ *   shieldcortex xray <path> --deep      # Deep scan (Pro) with full analysis
+ *   shieldcortex xray <package> --json   # JSON output
  *   shieldcortex cortex capture      # Log a mistake with rule extraction
  *   shieldcortex cortex preflight    # Pre-flight check before a task
  *   shieldcortex cortex review       # Weekly pattern review
@@ -763,6 +766,12 @@ ${bold}DOCS${reset}
         console.log(`   Total processed:        ${result.totalProcessed}`);
         process.exit(0);
     }
+    // Handle "xray" subcommand — package/file/plugin risk inspector
+    if (process.argv[2] === 'xray') {
+        const { handleXRayCommand } = await import('./xray/index.js');
+        await handleXRayCommand(process.argv.slice(3));
+        process.exit(0);
+    }
     // Handle "cortex" subcommand (Pro tier — mistake learning)
     if (process.argv[2] === 'cortex') {
         const { handleCortexCommand } = await import('./cortex/cli.js');
@@ -774,7 +783,7 @@ ${bold}DOCS${reset}
         'doctor', 'quickstart', 'setup', 'install', 'migrate', 'uninstall', 'hook',
         'openclaw', 'clawdbot', 'copilot', 'codex', 'service', 'config', 'status',
         'graph', 'license', 'licence', 'audit', 'iron-dome', 'scan', 'cloud',
-        'scan-skill', 'scan-skills', 'dashboard', 'api', 'worker', 'stats', 'cortex', 'consolidate',
+        'scan-skill', 'scan-skills', 'dashboard', 'api', 'worker', 'stats', 'cortex', 'consolidate', 'xray',
     ]);
     const arg = process.argv[2];
     if (arg && !arg.startsWith('-') && !knownCommands.has(arg)) {

package/dist/license/gate.d.ts

@@ -6,7 +6,7 @@
  *   isFeatureEnabled('cloud_sync');               // returns boolean (soft check)
  */
 import { type LicenseTier } from './keys.js';
-export type GatedFeature = 'custom_injection_patterns' | 'custom_iron_dome_policies' | 'custom_firewall_rules' | 'audit_export' | 'skill_scanner_deep' | 'cloud_sync' | 'team_management' | 'shared_patterns' | 'cortex_learning' | 'deps_quarantine' | 'deps_clean' | 'deps_auto_protect' | 'deps_global_scan' | 'memory_types' | 'memory_scopes' | 'dream_mode' | 'llm_reranking' | 'positive_feedback';
+export type GatedFeature = 'custom_injection_patterns' | 'custom_iron_dome_policies' | 'custom_firewall_rules' | 'audit_export' | 'skill_scanner_deep' | 'cloud_sync' | 'team_management' | 'shared_patterns' | 'cortex_learning' | 'deps_quarantine' | 'deps_clean' | 'deps_auto_protect' | 'deps_global_scan' | 'memory_types' | 'memory_scopes' | 'dream_mode' | 'llm_reranking' | 'positive_feedback' | 'xray_deep';
 export declare class FeatureGatedError extends Error {
     feature: GatedFeature;
     requiredTier: LicenseTier;

package/dist/license/gate.js

@@ -26,6 +26,7 @@ const FEATURE_TIERS = {
     dream_mode: 'pro',
     llm_reranking: 'pro',
     positive_feedback: 'pro',
+    xray_deep: 'pro',
 };
 const FEATURE_DESCRIPTIONS = {
     custom_injection_patterns: 'Define up to 50 custom regex patterns for detecting domain-specific threats.',
@@ -46,6 +47,7 @@ const FEATURE_DESCRIPTIONS = {
     dream_mode: 'Background memory consolidation — merge duplicates, archive stale, detect contradictions.',
     llm_reranking: 'LLM-powered memory reranking for precision recall.',
     positive_feedback: 'Capture what worked, not just what failed — learn from success.',
+    xray_deep: 'Deep X-Ray scanning: npm registry analysis, binary file inspection, dependency graph risk, and AI-directive detection in metadata and filenames.',
 };
 // ── Error class ──────────────────────────────────────────
 export class FeatureGatedError extends Error {

package/dist/xray/dir-scanner.d.ts

@@ -0,0 +1,14 @@
+/**
+ * X-Ray Directory Scanner
+ *
+ * Walks a directory tree, scans each file, checks package.json if present,
+ * and aggregates findings into a single XRayResult.
+ */
+import type { XRayResult } from './types.js';
+/**
+ * Scan an entire directory for X-Ray findings.
+ *
+ * @param dirPath - Path to the directory to scan
+ * @param deep - If true, performs deeper analysis (Pro feature)
+ */
+export declare function scanDirectory(dirPath: string, deep: boolean): Promise<XRayResult>;

package/dist/xray/dir-scanner.js

@@ -0,0 +1,77 @@
+/**
+ * X-Ray Directory Scanner
+ *
+ * Walks a directory tree, scans each file, checks package.json if present,
+ * and aggregates findings into a single XRayResult.
+ */
+import fs from 'fs';
+import path from 'path';
+import { scanFile } from './file-scanner.js';
+import { calculateTrustScore } from './trust-score.js';
+// ── Constants ───────────────────────────────────────────────
+/** Directories to skip when walking. */
+const SKIP_DIRS = new Set([
+    'node_modules', '.git', '.svn', '.hg', 'dist', 'build', '.next',
+    '__pycache__', '.tox', '.venv', 'venv', '.cache', 'coverage',
+]);
+/** Maximum number of files to scan per directory. */
+const MAX_FILES = 5000;
+// ── Directory walker ────────────────────────────────────────
+function walkDir(dirPath, files, depth = 0) {
+    if (depth > 20 || files.length >= MAX_FILES)
+        return;
+    let entries;
+    try {
+        entries = fs.readdirSync(dirPath, { withFileTypes: true });
+    }
+    catch {
+        return;
+    }
+    for (const entry of entries) {
+        if (files.length >= MAX_FILES)
+            break;
+        if (entry.isDirectory()) {
+            if (!SKIP_DIRS.has(entry.name) && !entry.name.startsWith('.')) {
+                walkDir(path.join(dirPath, entry.name), files, depth + 1);
+            }
+        }
+        else if (entry.isFile()) {
+            files.push(path.join(dirPath, entry.name));
+        }
+    }
+}
+// ── Public API ──────────────────────────────────────────────
+/**
+ * Scan an entire directory for X-Ray findings.
+ *
+ * @param dirPath - Path to the directory to scan
+ * @param deep - If true, performs deeper analysis (Pro feature)
+ */
+export async function scanDirectory(dirPath, deep) {
+    const startTime = Date.now();
+    const allFindings = [];
+    // Collect files
+    const files = [];
+    walkDir(dirPath, files);
+    // Scan each file
+    for (const file of files) {
+        const findings = await scanFile(file, deep);
+        allFindings.push(...findings);
+    }
+    // Check for package.json at root
+    const pkgJsonPath = path.join(dirPath, 'package.json');
+    if (fs.existsSync(pkgJsonPath) && !files.includes(pkgJsonPath)) {
+        const findings = await scanFile(pkgJsonPath, deep);
+        allFindings.push(...findings);
+    }
+    const { score, riskLevel } = calculateTrustScore(allFindings);
+    return {
+        target: dirPath,
+        trustScore: score,
+        riskLevel,
+        findings: allFindings,
+        filesScanned: files.length,
+        scannedAt: new Date(),
+        deepScan: deep,
+    };
+}

package/dist/xray/file-scanner.d.ts

@@ -0,0 +1,15 @@
+/**
+ * X-Ray File Scanner
+ *
+ * Scans individual files for hidden risk patterns.
+ * Handles code files (.js/.ts), JSON, and binary/image files.
+ * Uses only Node.js built-ins — no new dependencies.
+ */
+import type { XRayFinding } from './types.js';
+/**
+ * Scan a single file for X-Ray findings.
+ *
+ * @param filePath - Absolute or relative path to the file
+ * @param deep - If true, performs deeper analysis (Pro feature)
+ */
+export declare function scanFile(filePath: string, deep: boolean): Promise<XRayFinding[]>;

package/dist/xray/file-scanner.js

@@ -0,0 +1,296 @@
+/**
+ * X-Ray File Scanner
+ *
+ * Scans individual files for hidden risk patterns.
+ * Handles code files (.js/.ts), JSON, and binary/image files.
+ * Uses only Node.js built-ins — no new dependencies.
+ */
+import fs from 'fs';
+import path from 'path';
+import { detectPatterns, detectFilenameDirectives } from './patterns.js';
+// ── Constants ───────────────────────────────────────────────
+/** Extensions treated as code files. */
+const CODE_EXTENSIONS = new Set(['.js', '.ts', '.mjs', '.cjs', '.mts', '.cts', '.jsx', '.tsx']);
+/** Extensions treated as JSON. */
+const JSON_EXTENSIONS = new Set(['.json']);
+/** Extensions treated as images. */
+const IMAGE_EXTENSIONS = new Set(['.png', '.jpg', '.jpeg', '.gif', '.bmp', '.webp']);
+/** Maximum file size to scan (10 MB). */
+const MAX_FILE_SIZE = 10 * 1024 * 1024;
+// ── Image EOI markers ───────────────────────────────────────
+/** JPEG End-of-Image marker. */
+const JPEG_EOI = Buffer.from([0xff, 0xd9]);
+/** PNG IEND chunk signature. */
+const PNG_IEND = Buffer.from([0x49, 0x45, 0x4e, 0x44]);
+/** GIF trailer byte. */
+const GIF_TRAILER = 0x3b;
+// ── Helpers ─────────────────────────────────────────────────
+function hasZeroWidthUnicode(content) {
+    const zwMatch = content.match(/[\u200b\u200c\u200d\ufeff\u2060]{2,}/);
+    if (!zwMatch)
+        return null;
+    const before = content.slice(0, zwMatch.index);
+    const line = (before.match(/\n/g) || []).length + 1;
+    return {
+        severity: 'medium',
+        category: 'unicode-trick',
+        title: 'Zero-width Unicode characters detected',
+        description: 'File contains clusters of zero-width characters that may hide invisible content.',
+        line,
+        evidence: `${zwMatch[0].length} zero-width chars at line ${line}`,
+    };
+}
+function checkPolyglot(buf) {
+    // Check for multiple magic byte signatures in a single file
+    const signatures = [
+        { name: 'PDF', magic: Buffer.from('%PDF') },
+        { name: 'ZIP/JAR', magic: Buffer.from([0x50, 0x4b, 0x03, 0x04]) },
+        { name: 'ELF', magic: Buffer.from([0x7f, 0x45, 0x4c, 0x46]) },
+        { name: 'PE/EXE', magic: Buffer.from([0x4d, 0x5a]) },
+        { name: 'GZIP', magic: Buffer.from([0x1f, 0x8b]) },
+    ];
+    const matched = [];
+    for (const sig of signatures) {
+        // Check at start and also embedded
+        if (buf.includes(sig.magic)) {
+            matched.push(sig.name);
+        }
+    }
+    if (matched.length >= 2) {
+        return {
+            severity: 'high',
+            category: 'steganography',
+            title: 'Polyglot file detected',
+            description: `File contains multiple format signatures (${matched.join(', ')}), indicating a polyglot that may hide payloads.`,
+            evidence: matched.join(', '),
+        };
+    }
+    return null;
+}
+// ── Image scanner ───────────────────────────────────────────
+function scanImage(filePath, buf) {
+    const findings = [];
+    const ext = path.extname(filePath).toLowerCase();
+    // Check for appended data after EOI marker
+    if (ext === '.jpg' || ext === '.jpeg') {
+        const eoiIndex = buf.lastIndexOf(JPEG_EOI);
+        if (eoiIndex >= 0 && eoiIndex < buf.length - 2) {
+            const trailing = buf.length - eoiIndex - 2;
+            if (trailing > 16) {
+                findings.push({
+                    severity: 'high',
+                    category: 'steganography',
+                    title: 'Data appended after JPEG EOI marker',
+                    description: `${trailing} bytes found after the JPEG End-of-Image marker — may contain hidden payloads.`,
+                    file: filePath,
+                    evidence: `${trailing} trailing bytes after EOI at offset ${eoiIndex}`,
+                });
+            }
+        }
+    }
+    if (ext === '.png') {
+        const iendIndex = buf.lastIndexOf(PNG_IEND);
+        if (iendIndex >= 0) {
+            // IEND chunk: 4-byte length + 4-byte type + 4-byte CRC = the IEND text is at +4 from chunk start
+            // After IEND chunk: iendIndex + 4 (IEND) + 4 (CRC) = iendIndex + 8
+            const afterIend = iendIndex + 8;
+            if (afterIend < buf.length) {
+                const trailing = buf.length - afterIend;
+                if (trailing > 16) {
+                    findings.push({
+                        severity: 'high',
+                        category: 'steganography',
+                        title: 'Data appended after PNG IEND chunk',
+                        description: `${trailing} bytes found after the PNG IEND marker — may contain hidden payloads.`,
+                        file: filePath,
+                        evidence: `${trailing} trailing bytes after IEND at offset ${iendIndex}`,
+                    });
+                }
+            }
+        }
+    }
+    if (ext === '.gif') {
+        const lastByte = buf[buf.length - 1];
+        if (lastByte !== GIF_TRAILER) {
+            // Find the trailer
+            const trailerIndex = buf.lastIndexOf(GIF_TRAILER);
+            if (trailerIndex >= 0 && trailerIndex < buf.length - 1) {
+                const trailing = buf.length - trailerIndex - 1;
+                if (trailing > 16) {
+                    findings.push({
+                        severity: 'high',
+                        category: 'steganography',
+                        title: 'Data appended after GIF trailer',
+                        description: `${trailing} bytes found after the GIF trailer byte — may contain hidden payloads.`,
+                        file: filePath,
+                        evidence: `${trailing} trailing bytes after GIF trailer`,
+                    });
+                }
+            }
+        }
+    }
+    // Check EXIF/metadata chunks for text with AI directives
+    // Look for readable text in the binary that matches AI directive patterns
+    const textChunks = extractTextFromBinary(buf);
+    if (textChunks) {
+        const metaFindings = detectPatterns(textChunks, filePath);
+        for (const f of metaFindings) {
+            if (f.category === 'ai-directive' || f.category === 'metadata-exploit') {
+                f.description = `Image metadata contains: ${f.description}`;
+                findings.push(f);
+            }
+        }
+    }
+    return findings;
+}
+/**
+ * Extract readable ASCII/UTF-8 text sequences from a binary buffer.
+ * Returns concatenated text chunks >= 8 chars for pattern scanning.
+ */
+function extractTextFromBinary(buf) {
+    const chunks = [];
+    let current = '';
+    for (let i = 0; i < buf.length && i < 1024 * 1024; i++) {
+        const byte = buf[i];
+        // Printable ASCII range
+        if (byte >= 0x20 && byte <= 0x7e) {
+            current += String.fromCharCode(byte);
+        }
+        else {
+            if (current.length >= 8) {
+                chunks.push(current);
+            }
+            current = '';
+        }
+    }
+    if (current.length >= 8) {
+        chunks.push(current);
+    }
+    return chunks.length > 0 ? chunks.join('\n') : null;
+}
+// ── JSON scanner ────────────────────────────────────────────
+function scanJson(filePath, content) {
+    const findings = [];
+    // Run pattern detection for metadata injection, postinstall hooks, etc.
+    findings.push(...detectPatterns(content, filePath));
+    // Check for suspicious scripts in package.json
+    const basename = path.basename(filePath);
+    if (basename === 'package.json') {
+        try {
+            const pkg = JSON.parse(content);
+            const scripts = pkg.scripts || {};
+            for (const hook of ['preinstall', 'install', 'postinstall', 'preuninstall', 'postuninstall']) {
+                if (scripts[hook]) {
+                    const val = scripts[hook];
+                    if (/curl|wget|node\s+-e|bash\s+-c|powershell|https?:\/\/|eval|exec/i.test(val)) {
+                        findings.push({
+                            severity: 'high',
+                            category: 'persistence-hook',
+                            title: `Suspicious ${hook} script`,
+                            description: `package.json "${hook}" script executes potentially dangerous commands.`,
+                            file: filePath,
+                            evidence: val.slice(0, 120),
+                        });
+                    }
+                }
+            }
+        }
+        catch {
+            // Not valid JSON — just rely on pattern detection
+        }
+    }
+    return findings;
+}
+// ── Public API ──────────────────────────────────────────────
+/**
+ * Scan a single file for X-Ray findings.
+ *
+ * @param filePath - Absolute or relative path to the file
+ * @param deep - If true, performs deeper analysis (Pro feature)
+ */
+export async function scanFile(filePath, deep) {
+    const findings = [];
+    const ext = path.extname(filePath).toLowerCase();
+    const basename = path.basename(filePath);
+    // Check filename for AI directives
+    findings.push(...detectFilenameDirectives(basename));
+    // Check file exists and size
+    let stat;
+    try {
+        stat = fs.statSync(filePath);
+    }
+    catch {
+        return findings;
+    }
+    if (!stat.isFile() || stat.size > MAX_FILE_SIZE) {
+        return findings;
+    }
+    // Route by extension
+    if (IMAGE_EXTENSIONS.has(ext)) {
+        const buf = fs.readFileSync(filePath);
+        findings.push(...scanImage(filePath, buf));
+        // Polyglot check
+        const polyglot = checkPolyglot(buf);
+        if (polyglot) {
+            polyglot.file = filePath;
+            findings.push(polyglot);
+        }
+    }
+    else if (JSON_EXTENSIONS.has(ext)) {
+        const content = fs.readFileSync(filePath, 'utf-8');
+        findings.push(...scanJson(filePath, content));
+        // Zero-width unicode check
+        const zw = hasZeroWidthUnicode(content);
+        if (zw) {
+            zw.file = filePath;
+            findings.push(zw);
+        }
+    }
+    else if (CODE_EXTENSIONS.has(ext)) {
+        const content = fs.readFileSync(filePath, 'utf-8');
+        findings.push(...detectPatterns(content, filePath));
+        // Zero-width unicode check
+        const zw = hasZeroWidthUnicode(content);
+        if (zw) {
+            zw.file = filePath;
+            findings.push(zw);
+        }
+    }
+    else {
+        // For any other text-like file, try reading as text
+        try {
+            const buf = fs.readFileSync(filePath);
+            // Check if it's mostly text
+            let nonPrintable = 0;
+            const sampleSize = Math.min(buf.length, 8192);
+            for (let i = 0; i < sampleSize; i++) {
+                const b = buf[i];
+                if (b < 0x09 || (b > 0x0d && b < 0x20 && b !== 0x1b)) {
+                    nonPrintable++;
+                }
+            }
+            if (nonPrintable / sampleSize < 0.1) {
+                // Treat as text
+                const content = buf.toString('utf-8');
+                findings.push(...detectPatterns(content, filePath));
+                const zw = hasZeroWidthUnicode(content);
+                if (zw) {
+                    zw.file = filePath;
+                    findings.push(zw);
+                }
+            }
+            else {
+                // Binary file — polyglot check
+                const polyglot = checkPolyglot(buf);
+                if (polyglot) {
+                    polyglot.file = filePath;
+                    findings.push(polyglot);
+                }
+            }
+        }
+        catch {
+            // Can't read — skip
+        }
+    }
+    return findings;
+}

package/dist/xray/index.d.ts

@@ -0,0 +1,20 @@
+/**
+ * X-Ray — Package, File & Plugin Risk Inspector
+ *
+ * Main entry point for the `shieldcortex xray` CLI command.
+ * Inspects npm packages, local files, and directories for hidden risk.
+ *
+ * Free tier: local scans only (no npm registry), max 5 scans/day.
+ * Pro tier:  npm registry analysis, deep scanning, unlimited scans.
+ */
+export type { XRayTarget, XRayFinding, XRayCategory, XRayResult } from './types.js';
+export { calculateTrustScore } from './trust-score.js';
+export { detectPatterns, detectFilenameDirectives } from './patterns.js';
+export { scanFile } from './file-scanner.js';
+export { scanDirectory } from './dir-scanner.js';
+export { inspectNpmPackage } from './npm-inspector.js';
+export { formatXRayReport, formatXRayMarkdown } from './report.js';
+/**
+ * Handle the `shieldcortex xray` CLI command.
+ */
+export declare function handleXRayCommand(args: string[]): Promise<void>;

package/dist/xray/index.js

@@ -0,0 +1,166 @@
+/**
+ * X-Ray — Package, File & Plugin Risk Inspector
+ *
+ * Main entry point for the `shieldcortex xray` CLI command.
+ * Inspects npm packages, local files, and directories for hidden risk.
+ *
+ * Free tier: local scans only (no npm registry), max 5 scans/day.
+ * Pro tier:  npm registry analysis, deep scanning, unlimited scans.
+ */
+import fs from 'fs';
+import path from 'path';
+import os from 'os';
+import { isFeatureEnabled, requireFeature } from '../license/gate.js';
+import { scanFile } from './file-scanner.js';
+import { scanDirectory } from './dir-scanner.js';
+import { inspectNpmPackage } from './npm-inspector.js';
+import { calculateTrustScore } from './trust-score.js';
+import { formatXRayReport, formatXRayMarkdown } from './report.js';
+export { calculateTrustScore } from './trust-score.js';
+export { detectPatterns, detectFilenameDirectives } from './patterns.js';
+export { scanFile } from './file-scanner.js';
+export { scanDirectory } from './dir-scanner.js';
+export { inspectNpmPackage } from './npm-inspector.js';
+export { formatXRayReport, formatXRayMarkdown } from './report.js';
+// ── Usage tracking ──────────────────────────────────────────
+const USAGE_FILE = path.join(os.homedir(), '.shieldcortex', 'xray-usage.json');
+const FREE_DAILY_LIMIT = 5;
+function getUsage() {
+    try {
+        const raw = fs.readFileSync(USAGE_FILE, 'utf-8');
+        return JSON.parse(raw);
+    }
+    catch {
+        return { date: '', count: 0 };
+    }
+}
+function incrementUsage() {
+    const today = new Date().toISOString().slice(0, 10);
+    const usage = getUsage();
+    if (usage.date !== today) {
+        // New day — reset
+        usage.date = today;
+        usage.count = 1;
+    }
+    else {
+        usage.count++;
+    }
+    const dir = path.dirname(USAGE_FILE);
+    if (!fs.existsSync(dir)) {
+        fs.mkdirSync(dir, { recursive: true });
+    }
+    fs.writeFileSync(USAGE_FILE, JSON.stringify(usage));
+}
+function checkFreeLimit() {
+    if (isFeatureEnabled('xray_deep'))
+        return true; // Pro users are unlimited
+    const today = new Date().toISOString().slice(0, 10);
+    const usage = getUsage();
+    if (usage.date !== today)
+        return true; // New day
+    return usage.count < FREE_DAILY_LIMIT;
+}
+// ── Target detection ────────────────────────────────────────
+function isNpmPackageName(target) {
+    // npm package names: lowercase, may start with @scope/
+    if (target.startsWith('.') || target.startsWith('/') || target.startsWith('~'))
+        return false;
+    if (fs.existsSync(target))
+        return false; // Local path takes priority
+    return /^(@[a-z0-9-~][a-z0-9-._~]*\/)?[a-z0-9-~][a-z0-9-._~]*$/.test(target);
+}
+// ── CLI handler ─────────────────────────────────────────────
+/**
+ * Handle the `shieldcortex xray` CLI command.
+ */
+export async function handleXRayCommand(args) {
+    const flags = new Set(args.filter(a => a.startsWith('--')));
+    const positional = args.filter(a => !a.startsWith('--'));
+    const deep = flags.has('--deep');
+    const jsonOutput = flags.has('--json');
+    const markdownOutput = flags.has('--markdown');
+    // Show usage if no target
+    if (positional.length === 0) {
+        console.error('Usage: shieldcortex xray <target> [--deep] [--json] [--markdown]');
+        console.error('');
+        console.error('  target:     npm package name, local file path, or directory path');
+        console.error('  --deep      Deep scan with full analysis (Pro)');
+        console.error('  --json      Output JSON result');
+        console.error('  --markdown  Output markdown report');
+        console.error('');
+        console.error('Examples:');
+        console.error('  shieldcortex xray ./src/');
+        console.error('  shieldcortex xray package.json');
+        console.error('  shieldcortex xray lodash --deep');
+        process.exit(1);
+    }
+    const target = positional[0];
+    // Deep scan requires Pro
+    if (deep) {
+        try {
+            requireFeature('xray_deep');
+        }
+        catch (err) {
+            console.error(err instanceof Error ? err.message : String(err));
+            process.exit(1);
+        }
+    }
+    // Check free tier limit
+    if (!checkFreeLimit()) {
+        console.error('Daily scan limit reached. Upgrade to Pro for unlimited scans.');
+        console.error('  https://shieldcortex.ai/pricing');
+        process.exit(1);
+    }
+    let result;
+    if (isNpmPackageName(target)) {
+        // NPM package inspection
+        if (!isFeatureEnabled('xray_deep')) {
+            console.error('npm registry inspection requires a Pro licence.');
+            console.error('Free tier supports local file and directory scans only.');
+            console.error('  Upgrade: https://shieldcortex.ai/pricing');
+            process.exit(1);
+        }
+        result = await inspectNpmPackage(target, deep);
+    }
+    else {
+        // Local file or directory
+        const resolved = path.resolve(target);
+        if (!fs.existsSync(resolved)) {
+            console.error(`Target not found: ${resolved}`);
+            process.exit(1);
+        }
+        const stat = fs.statSync(resolved);
+        if (stat.isDirectory()) {
+            result = await scanDirectory(resolved, deep);
+        }
+        else if (stat.isFile()) {
+            const findings = await scanFile(resolved, deep);
+            const { score, riskLevel } = calculateTrustScore(findings);
+            result = {
+                target: resolved,
+                trustScore: score,
+                riskLevel,
+                findings,
+                filesScanned: 1,
+                scannedAt: new Date(),
+                deepScan: deep,
+            };
+        }
+        else {
+            console.error(`Target is not a file or directory: ${resolved}`);
+            process.exit(1);
+        }
+    }
+    // Track usage
+    incrementUsage();
+    // Output
+    if (jsonOutput) {
+        console.log(JSON.stringify(result, null, 2));
+    }
+    else if (markdownOutput) {
+        console.log(formatXRayMarkdown(result));
+    }
+    else {
+        console.log(formatXRayReport(result));
+    }
+}

package/dist/xray/npm-inspector.d.ts

@@ -0,0 +1,15 @@
+/**
+ * X-Ray NPM Package Inspector
+ *
+ * Downloads package metadata from registry.npmjs.org, analyses it for risk
+ * signals, and optionally scans the tarball contents (Pro/deep scan).
+ * Uses only Node.js built-ins (https module) — no new dependencies.
+ */
+import type { XRayResult } from './types.js';
+/**
+ * Inspect an npm package for hidden risk.
+ *
+ * @param packageName - npm package name (e.g. "lodash", "@scope/pkg")
+ * @param deep - If true, downloads and scans the tarball (Pro feature)
+ */
+export declare function inspectNpmPackage(packageName: string, deep?: boolean): Promise<XRayResult>;