@runhalo/cli 0.1.0 → 0.4.0

package/README.md

@@ -0,0 +1,97 @@
+# @runhalo/cli
+
+**Halo CLI** — scan your codebase for COPPA 2.0 privacy risks.
+
+[![npm](https://img.shields.io/npm/v/@runhalo/cli.svg)](https://www.npmjs.com/package/@runhalo/cli)
+[![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://www.apache.org/licenses/LICENSE-2.0)
+
+## What it does
+
+One command scans your entire codebase for potential COPPA 2.0 violations and ethical design issues in children's apps. Powered by tree-sitter AST analysis with **20 COPPA rules** and **5 ethical design rules**.
+
+## Quickstart
+
+```bash
+# Scan current directory
+npx @runhalo/cli scan .
+
+# Scan a specific directory
+npx @runhalo/cli scan ./src
+
+# JSON output for CI pipelines
+npx @runhalo/cli scan . --format json
+
+# SARIF output for GitHub Security tab
+npx @runhalo/cli scan . --format sarif --output results.sarif
+
+# Filter by severity
+npx @runhalo/cli scan . --severity critical,high
+```
+
+## Example Output
+
+```
+  Halo COPPA Risk Scanner v0.1.1
+
+  Scanning... 142 files analyzed
+
+  src/auth/social-login.ts:24
+    coppa-auth-001  Unverified social login detected     CRITICAL
+
+  src/services/analytics.ts:89
+    coppa-tracking-003  Third-party ad tracker found      HIGH
+
+  src/components/Chat.tsx:15
+    coppa-ext-011  Unmoderated third-party chat           HIGH
+
+  3 potential issues found | 142 files scanned | 97 checks passing
+```
+
+## Output Formats
+
+| Format | Flag | Use Case |
+|:-------|:-----|:---------|
+| Text | `--format text` (default) | Terminal output |
+| JSON | `--format json` | CI pipelines, tooling |
+| SARIF | `--format sarif` | GitHub Security tab |
+
+## GitHub Action
+
+```yaml
+name: Halo COPPA Audit
+on:
+  pull_request:
+    paths: ['**.ts', '**.js', '**.tsx', '**.jsx', '**.py']
+
+jobs:
+  scan:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+      - run: npx @runhalo/cli scan . --format sarif --output results.sarif
+      - uses: github/codeql-action/upload-sarif@v3
+        with:
+          sarif_file: results.sarif
+```
+
+## Suppression
+
+Suppress individual findings with inline comments:
+
+```typescript
+// halo-ignore coppa-auth-001
+const auth = signInWithPopup(provider);
+```
+
+Or use a `.haloignore` file at your project root.
+
+## Full Documentation
+
+See the [Halo monorepo](https://github.com/runhalo/halo) for the complete rule reference, VS Code extension, MCP server, and more.
+
+## License
+
+Apache 2.0 — [Mindful Media](https://mindfulmedia.org)

package/dist/index.d.ts

@@ -3,7 +3,7 @@
  * Halo CLI - Child Safety Compliance Scanner
  * Usage: runhalo scan <path> [options]
  */
-import { HaloEngine, Violation, ScanResult, EngineConfig } from '@runhalo/engine';
+import { HaloEngine, Violation, ScanResult, EngineConfig, JSONRule } from '@runhalo/engine';
 type OutputFormat = 'json' | 'sarif' | 'text';
 interface CLIOptions {
     format: OutputFormat;
@@ -14,6 +14,11 @@ interface CLIOptions {
     output: string;
     verbose: boolean;
     ethicalPreview: boolean;
+    report: string | boolean;
+    aiAudit: boolean;
+    sectorAuSbd: boolean;
+    pack: string[];
+    offline: boolean;
 }
 /**
  * Format violations as SARIF output
@@ -22,11 +27,30 @@ declare function formatSARIF(results: ScanResult[], rules: any[]): string;
 /**
  * Format violations as JSON output
  */
-declare function formatJSON(results: ScanResult[]): string;
+declare function formatJSON(results: ScanResult[], scoreResult?: any): string;
 /**
  * Format violations as human-readable text
  */
-declare function formatText(results: ScanResult[], verbose?: boolean, fileCount?: number): string;
+declare function formatText(results: ScanResult[], verbose?: boolean, fileCount?: number, scoreResult?: any): string;
+/**
+ * Format trend line comparing current score to last scan for the same project.
+ * Returns empty string if no prior history exists.
+ */
+declare function formatTrend(currentScore: number, projectPath: string): string;
+/**
+ * Generate a self-contained HTML compliance report.
+ * Light theme for email-ability. All CSS inline. No external dependencies.
+ */
+declare function generateHtmlReport(results: ScanResult[], scoreResult: any, fileCount: number, projectPath: string, history?: ScanHistoryEntry[]): string;
+/**
+ * Escape HTML special characters
+ */
+declare function escapeHtml(text: string): string;
+/**
+ * Generate a government-procurement-grade PDF compliance report.
+ * Uses PDFKit — pure JS, no browser dependencies, CI-safe.
+ */
+declare function generatePdfReport(results: ScanResult[], scoreResult: any, fileCount: number, projectPath: string, history?: ScanHistoryEntry[]): Promise<Buffer>;
 /**
  * Create a Halo engine instance
  */
@@ -39,8 +63,134 @@ declare function scanFile(filePath: string, content?: string): Violation[];
  * Scan a directory
  */
 declare function scanDirectory(dirPath: string, config?: EngineConfig): Promise<ScanResult[]>;
+declare const HALO_CONFIG_DIR: string;
+declare const HALO_CONFIG_PATH: string;
+declare const HALO_HISTORY_PATH: string;
+declare const MAX_HISTORY_ENTRIES = 100;
+declare const RULES_CACHE_PATH: string;
+interface RulesCache {
+    etag: string | null;
+    packs: string[];
+    rules: JSONRule[];
+    fetchedAt: string;
+}
+/**
+ * Fetch rules from the Supabase rules-fetch edge function.
+ * Returns raw JSON rules (not compiled) or null on failure.
+ */
+declare function fetchRulesFromAPI(packs: string[], verbose: boolean): Promise<{
+    rules: JSONRule[];
+    etag: string | null;
+} | null>;
+/**
+ * Read the local rules cache.
+ */
+declare function readRulesCache(): RulesCache | null;
+/**
+ * Write rules to the local cache.
+ */
+declare function writeRulesCache(etag: string | null, packs: string[], rules: JSONRule[]): void;
+/**
+ * Load bundled baseline rules from @runhalo/engine's rules.json.
+ */
+declare function loadBaselineRules(packs: string[]): JSONRule[] | null;
+/**
+ * Map CLI options to pack IDs.
+ * --pack takes precedence. Legacy flags (--ethical-preview, --ai-audit, --sector-au-sbd) are mapped.
+ */
+declare function resolvePacks(options: CLIOptions): string[];
+/**
+ * Resolve rules with fallback chain:
+ *   API (fresh) → 304 cache hit → local cache (stale OK) → bundled baseline → null
+ */
+declare function resolveRules(packs: string[], offline: boolean, verbose: boolean): Promise<JSONRule[] | null>;
+interface HaloConfig {
+    email?: string;
+    prompted: boolean;
+    promptedAt: string;
+    consent: boolean;
+    license_key?: string;
+    tier?: 'free' | 'pro' | 'enterprise';
+    scans_today?: number;
+    scan_date?: string;
+}
+interface ScanHistoryEntry {
+    scannedAt: string;
+    score: number;
+    grade: string;
+    totalViolations: number;
+    bySeverity: {
+        critical: number;
+        high: number;
+        medium: number;
+        low: number;
+    };
+    filesScanned: number;
+    projectPath: string;
+    rulesTriggered: string[];
+}
+declare function loadConfig(): HaloConfig | null;
+declare function saveConfig(config: HaloConfig): void;
+declare function loadHistory(): ScanHistoryEntry[];
+declare function saveHistory(entry: ScanHistoryEntry): void;
+declare const FREE_SCAN_LIMIT = 5;
+/**
+ * Validate a license key against Supabase validate-license edge function.
+ * Returns license info or null on failure.
+ */
+declare function validateLicenseKey(licenseKey: string): Promise<{
+    valid: boolean;
+    tier?: string;
+    email?: string;
+    status?: string;
+    expires_at?: string;
+    error?: string;
+} | null>;
+/**
+ * Activate a license key — validates via Supabase, stores in ~/.halo/config.json.
+ */
+declare function activateLicense(licenseKey: string): Promise<number>;
+/**
+ * Check scan limit for free-tier users.
+ * Returns true if scan is allowed, false if blocked.
+ * CI environments always bypass limits.
+ */
+declare function checkScanLimit(): boolean;
+/**
+ * Check if a Pro feature is available for the current user.
+ * Returns true if allowed, false with upsell message if blocked.
+ */
+declare function checkProFeature(featureName: string, flagName: string): boolean;
+/**
+ * First-run email prompt — one-time, optional, non-blocking.
+ * Auto-skips when: config exists, --no-prompt, !isTTY, CI env.
+ */
+declare function firstRunPrompt(noPrompt: boolean): Promise<void>;
 /**
  * Main scan function
  */
 declare function scan(paths: string[], options: CLIOptions): Promise<number>;
-export { scan, scanFile, scanDirectory, createEngine, formatSARIF, formatJSON, formatText };
+interface FixCLIOptions {
+    dryRun: boolean;
+    rules: string[];
+    verbose: boolean;
+    include: string[];
+    exclude: string[];
+    guided: boolean;
+    framework?: string;
+    scaffoldDir?: string;
+}
+/**
+ * Main fix function
+ * Flow: discover files → scan → filter auto-fixable → apply fixes → re-scan → write (or dry-run)
+ */
+declare function fix(paths: string[], options: FixCLIOptions): Promise<number>;
+interface InitOptions {
+    ide: boolean;
+    force: boolean;
+}
+/**
+ * Init command — generate IDE rules files and project configuration.
+ */
+declare function init(projectPath: string, options: InitOptions): Promise<number>;
+export { scan, fix, init, scanFile, scanDirectory, createEngine, formatSARIF, formatJSON, formatText, loadConfig, saveConfig, firstRunPrompt, loadHistory, saveHistory, formatTrend, generateHtmlReport, generatePdfReport, escapeHtml, validateLicenseKey, activateLicense, checkScanLimit, checkProFeature, resolvePacks, resolveRules, fetchRulesFromAPI, readRulesCache, writeRulesCache, loadBaselineRules, FREE_SCAN_LIMIT, HALO_CONFIG_DIR, HALO_CONFIG_PATH, HALO_HISTORY_PATH, MAX_HISTORY_ENTRIES, RULES_CACHE_PATH };