@oculisecurity/cli 0.1.0

package/dist/commands/init.js

@@ -0,0 +1,135 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runInit = runInit;
+const os = __importStar(require("os"));
+const detect_1 = require("../install/detect");
+const claude_code_1 = require("../install/claude-code");
+const cursor_1 = require("../install/cursor");
+const init_1 = require("../init");
+const AGENT_LABEL = {
+    'claude-code': { configPath: '~/.claude/settings.json' },
+    cursor: { configPath: '~/.cursor/hooks.json' },
+};
+/** Render an absolute path with the user's home dir collapsed to ~. */
+function tilde(absPath, home) {
+    return absPath.startsWith(home) ? '~' + absPath.slice(home.length) : absPath;
+}
+function runInit(opts = {}) {
+    const home = opts.home ?? os.homedir();
+    // 1. Resolve target agent list.
+    let targets;
+    let explicit = false;
+    if (opts.agent) {
+        explicit = true;
+        if (!(0, detect_1.isAgentInstalled)(opts.agent)) {
+            const bin = detect_1.BINARIES[opts.agent];
+            process.stderr.write(`oculi: '${opts.agent}' not found on PATH (looked for '${bin}').\n` +
+                `If you have ${opts.agent === 'claude-code' ? 'Claude Code' : 'Cursor'} installed, make sure \`${bin}\` is on your PATH.\n` +
+                `Otherwise run \`oculi init\` (no --agent) to write the policy and skip hook wiring.\n`);
+            return { exitCode: 1, policyPath: null, policyCreated: false, wired: [], added: {} };
+        }
+        targets = [opts.agent];
+    }
+    else {
+        targets = (0, detect_1.detectAgents)();
+    }
+    // 2. Write ~/.oculi/policy.yaml if missing (always — even when no agents are detected).
+    const policy = (0, init_1.runInit)({ home });
+    // 3. No agents detected → warn, don't wire, exit 0.
+    if (targets.length === 0) {
+        process.stdout.write((policy.created
+            ? `Created ${tilde(policy.path, home)}\n`
+            : `policy already exists, leaving alone (${tilde(policy.path, home)})\n`) +
+            `\n` +
+            `No supported agents detected on PATH.\n` +
+            `  - For Claude Code: install it from https://claude.com/claude-code\n` +
+            `    and ensure \`claude\` is on your PATH.\n` +
+            `  - For Cursor: in Cursor, run "Shell Command: Install 'cursor' command\n` +
+            `    in PATH" from the command palette.\n` +
+            `\n` +
+            `Once an agent is on PATH, re-run \`oculi init\` to wire hooks.\n`);
+        return {
+            exitCode: 0,
+            policyPath: policy.path,
+            policyCreated: policy.created,
+            wired: [],
+            added: {},
+        };
+    }
+    // 4. Wire each target agent's hooks (installers are idempotent).
+    const added = {};
+    for (const a of targets) {
+        const r = a === 'claude-code' ? (0, claude_code_1.installClaudeCode)({ home }) : (0, cursor_1.installCursor)({ home });
+        added[a] = r.added;
+    }
+    // 5. Print stdout summary.
+    let out = '';
+    if (!explicit) {
+        out += `Detected agents: ${targets.join(', ')}\n`;
+    }
+    out += policy.created
+        ? `Created ${tilde(policy.path, home)}\n`
+        : `policy already exists, leaving alone (${tilde(policy.path, home)})\n`;
+    for (const a of targets) {
+        const events = added[a] ?? [];
+        const cfg = AGENT_LABEL[a].configPath;
+        if (events.length === 0) {
+            out += `Wired ${a} hooks → ${cfg} (already up to date)\n`;
+        }
+        else {
+            out += `Wired ${a} hooks → ${cfg}\n`;
+            for (const e of events) {
+                out += `  + ${e}\n`;
+            }
+        }
+    }
+    out += `\nRestart your IDE for the hooks to take effect.\n`;
+    out += `Then run \`oculi serve\` to view events in the dashboard.\n`;
+    out += `\n`;
+    out += `To remove later, run BOTH (in order):\n`;
+    out += `  oculi uninstall                         # removes hooks + policy\n`;
+    out += `  npm uninstall -g @oculisecurity/cli     # removes the binary\n`;
+    out += `(npm uninstall alone won't clean the hooks — npm has no way to know\n`;
+    out += ` about files we wrote outside our own package directory.)\n`;
+    process.stdout.write(out);
+    return {
+        exitCode: 0,
+        policyPath: policy.path,
+        policyCreated: policy.created,
+        wired: targets,
+        added,
+    };
+}

package/dist/commands/report.d.ts

@@ -0,0 +1,33 @@
+import { TelemetryLogEntry } from '../services/telemetry-log';
+export interface ReportData {
+    period: {
+        from: string;
+        to: string;
+        hours: number;
+    };
+    total: number;
+    by_phase: Record<string, number>;
+    by_tool: Array<{
+        tool: string;
+        count: number;
+    }>;
+    by_ide: Array<{
+        ide: string;
+        count: number;
+        percent: number;
+    }>;
+    violations: Array<{
+        timestamp: string;
+        decision: string;
+        tool: string;
+        detail: string;
+        rule_ids: string[];
+    }>;
+}
+export declare function buildReport(entries: TelemetryLogEntry[], hours: number): ReportData;
+export declare function formatReport(report: ReportData): string;
+export interface ReportOptions {
+    json: boolean;
+    hours: number;
+}
+export declare function runReport(opts: ReportOptions): void;

package/dist/commands/report.js

@@ -0,0 +1,145 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildReport = buildReport;
+exports.formatReport = formatReport;
+exports.runReport = runReport;
+const telemetry_log_1 = require("../services/telemetry-log");
+// ---------------------------------------------------------------------------
+// Aggregation
+// ---------------------------------------------------------------------------
+function buildReport(entries, hours) {
+    const now = new Date();
+    const since = new Date(now.getTime() - hours * 3600_000);
+    const byPhase = {};
+    const toolCounts = {};
+    const ideCounts = {};
+    const violations = [];
+    for (const e of entries) {
+        // Phase
+        byPhase[e.phase] = (byPhase[e.phase] ?? 0) + 1;
+        // Tool
+        const tool = e.tool ?? '(none)';
+        toolCounts[tool] = (toolCounts[tool] ?? 0) + 1;
+        // IDE
+        ideCounts[e.ide_source] = (ideCounts[e.ide_source] ?? 0) + 1;
+        // Violations
+        if (e.policy_decision === 'deny' || e.policy_decision === 'warn') {
+            let detail = '—';
+            if (e.action?.command)
+                detail = e.action.command;
+            else if (e.file_path)
+                detail = e.file_path;
+            else if (e.shell_command)
+                detail = e.shell_command;
+            else if (e.mcp_server)
+                detail = e.mcp_server;
+            violations.push({
+                timestamp: e.timestamp,
+                decision: e.policy_decision,
+                tool,
+                detail,
+                rule_ids: e.policy_rule_ids ?? [],
+            });
+        }
+    }
+    const total = entries.length;
+    const byTool = Object.entries(toolCounts)
+        .sort((a, b) => b[1] - a[1])
+        .map(([tool, count]) => ({ tool, count }));
+    const byIde = Object.entries(ideCounts)
+        .sort((a, b) => b[1] - a[1])
+        .map(([ide, count]) => ({
+        ide,
+        count,
+        percent: total > 0 ? Math.round((count / total) * 100) : 0,
+    }));
+    return {
+        period: { from: since.toISOString(), to: now.toISOString(), hours },
+        total,
+        by_phase: byPhase,
+        by_tool: byTool,
+        by_ide: byIde,
+        violations,
+    };
+}
+// ---------------------------------------------------------------------------
+// Human-readable formatting
+// ---------------------------------------------------------------------------
+function bar(count, max, width = 20) {
+    if (max === 0)
+        return '';
+    const filled = Math.round((count / max) * width);
+    return '█'.repeat(filled);
+}
+function padRight(s, len) {
+    return s.length >= len ? s.slice(0, len) : s + ' '.repeat(len - s.length);
+}
+function formatTimestamp(iso) {
+    const d = new Date(iso);
+    return d.toLocaleString('sv-SE', { timeZone: Intl.DateTimeFormat().resolvedOptions().timeZone }).replace('T', ' ');
+}
+function formatReport(report) {
+    const lines = [];
+    const from = formatTimestamp(report.period.from);
+    const to = formatTimestamp(report.period.to);
+    lines.push(`Oculi Report — last ${report.period.hours} hours (${from} → ${to})`);
+    lines.push('');
+    // Event counts by phase
+    const phaseStr = Object.entries(report.by_phase)
+        .map(([phase, count]) => `${count} ${phase}`)
+        .join(', ');
+    lines.push(`Events: ${report.total} total${phaseStr ? ` (${phaseStr})` : ''}`);
+    lines.push('');
+    // By tool
+    if (report.by_tool.length > 0) {
+        lines.push('By tool:');
+        const maxCount = report.by_tool[0]?.count ?? 0;
+        for (const { tool, count } of report.by_tool) {
+            lines.push(`  ${padRight(tool, 14)} ${String(count).padStart(4)}  ${bar(count, maxCount)}`);
+        }
+        lines.push('');
+    }
+    // By IDE
+    if (report.by_ide.length > 0) {
+        lines.push('By IDE:');
+        for (const { ide, count, percent } of report.by_ide) {
+            lines.push(`  ${padRight(ide, 14)} ${String(count).padStart(4)} (${percent}%)`);
+        }
+        lines.push('');
+    }
+    // Violations
+    if (report.violations.length > 0) {
+        lines.push(`Policy violations (${report.violations.length}):`);
+        for (const v of report.violations) {
+            const ts = formatTimestamp(v.timestamp);
+            const ruleStr = v.rule_ids.length > 0 ? v.rule_ids.join(', ') : '—';
+            lines.push(`  ${ts}  ${padRight(v.decision, 5)} ${padRight(v.tool, 12)} ${padRight(v.detail, 25)} ${ruleStr}`);
+        }
+    }
+    else {
+        lines.push('Policy violations: none');
+    }
+    lines.push('');
+    return lines.join('\n');
+}
+function runReport(opts) {
+    const logPath = (0, telemetry_log_1.findTelemetryLog)();
+    if (!logPath) {
+        if (opts.json) {
+            process.stdout.write(JSON.stringify({ error: 'no telemetry log found' }) + '\n');
+        }
+        else {
+            process.stderr.write('oculi: no telemetry log found. Run some commands first.\n');
+        }
+        process.exit(1);
+    }
+    const since = new Date(Date.now() - opts.hours * 3600_000);
+    const entries = (0, telemetry_log_1.readTelemetryLines)(logPath, { since });
+    const report = buildReport(entries, opts.hours);
+    if (opts.json) {
+        process.stdout.write(JSON.stringify(report, null, 2) + '\n');
+    }
+    else {
+        process.stdout.write(formatReport(report));
+    }
+}

package/dist/commands/serve.d.ts

@@ -0,0 +1,27 @@
+import { AppConfig } from '../config';
+export interface ServeOpts {
+    port: number;
+    bind: string;
+    dataDir: string;
+    /** When undefined, no-auth mode (synthetic admin actor). */
+    auth?: string;
+    /** When undefined, OPA is disabled and the built-in fallback policy runs. */
+    opaUrl?: string;
+    verbose?: boolean;
+}
+/**
+ * Build an AppConfig from serve opts + sensible defaults.
+ *
+ * Zero-config localhost: no auth, no OPA, no rate limit, no upstreams.
+ * Non-localhost bind: same defaults except rate limit and auth are required.
+ */
+export declare function buildServeConfig(opts: ServeOpts): AppConfig;
+/**
+ * Validate serve opts. Throws an Error with a CLI-ready message on misuse.
+ * Caller is responsible for printing the message to stderr and exiting.
+ */
+export declare function validateServeOpts(opts: ServeOpts): void;
+/**
+ * Start the gateway. Foreground only — blocks on app.listen and SIGINT/SIGTERM.
+ */
+export declare function runServe(opts: ServeOpts): Promise<void>;

package/dist/commands/serve.js

@@ -0,0 +1,163 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildServeConfig = buildServeConfig;
+exports.validateServeOpts = validateServeOpts;
+exports.runServe = runServe;
+const path = __importStar(require("path"));
+const os = __importStar(require("os"));
+const server_1 = require("../server");
+const data_dir_1 = require("../services/data-dir");
+const telemetry_log_1 = require("../services/telemetry-log");
+const LOCALHOST = new Set(['127.0.0.1', 'localhost', '::1']);
+function isLocalhost(addr) {
+    return LOCALHOST.has(addr);
+}
+/**
+ * Build an AppConfig from serve opts + sensible defaults.
+ *
+ * Zero-config localhost: no auth, no OPA, no rate limit, no upstreams.
+ * Non-localhost bind: same defaults except rate limit and auth are required.
+ */
+function buildServeConfig(opts) {
+    const local = isLocalhost(opts.bind);
+    return {
+        port: opts.port,
+        jwtSecret: opts.auth ?? '',
+        opaUrl: opts.opaUrl ?? 'http://localhost:8181',
+        opaEnabled: !!opts.opaUrl,
+        dbPath: path.join(opts.dataDir, 'oculi.db'),
+        storeFullArgs: true,
+        upstreams: [],
+        rateLimitCapacity: local ? 0 : 10,
+        rateLimitRefillPerSecond: local ? 0 : 2,
+        logLevel: opts.verbose ? 'info' : 'warn',
+    };
+}
+/**
+ * Validate serve opts. Throws an Error with a CLI-ready message on misuse.
+ * Caller is responsible for printing the message to stderr and exiting.
+ */
+function validateServeOpts(opts) {
+    const local = isLocalhost(opts.bind);
+    const envAuth = process.env.OCULI_GATEWAY_TOKEN;
+    const effectiveAuth = opts.auth ?? envAuth;
+    if (!local) {
+        if (!effectiveAuth) {
+            throw new Error(`Binding to ${opts.bind} requires authentication.\n` +
+                'Set --auth <secret> (≥32 chars) or the OCULI_GATEWAY_TOKEN env var.\n' +
+                'Refusing to start an unauthenticated gateway on a non-localhost interface.');
+        }
+        if (effectiveAuth.length < 32) {
+            throw new Error('--auth secret must be at least 32 characters of high-entropy data.\n' +
+                'Generate one with: openssl rand -hex 32');
+        }
+    }
+    // If the user supplied --auth on localhost, honor it but don't require length —
+    // we treat it as advanced usage.
+}
+/**
+ * Start the gateway. Foreground only — blocks on app.listen and SIGINT/SIGTERM.
+ */
+async function runServe(opts) {
+    try {
+        validateServeOpts(opts);
+    }
+    catch (err) {
+        process.stderr.write(`oculi: ${err.message}\n`);
+        process.exit(1);
+    }
+    (0, data_dir_1.ensureDataDir)(opts.dataDir);
+    // OCULI_GATEWAY_TOKEN env var is an alternative way to provide --auth.
+    // Merge here so the rest of the code doesn't have to know about the env var.
+    const auth = opts.auth ?? process.env.OCULI_GATEWAY_TOKEN;
+    const config = buildServeConfig({ ...opts, auth });
+    const { app, audit, close } = await (0, server_1.buildServer)(config);
+    // Backfill the dashboard's sqlite from the CLI's telemetry.jsonl. Without
+    // this, events generated while no gateway was running are invisible at
+    // /admin even though `oculi tail` shows them. Checkpointed so re-runs of
+    // serve are no-ops.
+    const telemetryPath = (0, telemetry_log_1.findTelemetryLog)();
+    if (telemetryPath) {
+        try {
+            const r = audit.replayFromTelemetry(telemetryPath);
+            if (r.inserted > 0 || r.rotated) {
+                const tildePath = telemetryPath.startsWith(os.homedir())
+                    ? '~' + telemetryPath.slice(os.homedir().length)
+                    : telemetryPath;
+                const suffix = r.skipped > 0 ? ` (${r.skipped} malformed lines skipped)` : '';
+                const rotateNote = r.rotated ? ' [file rotated — replayed from start]' : '';
+                process.stdout.write(`Replayed ${r.inserted} events from ${tildePath}${rotateNote}${suffix}\n`);
+            }
+        }
+        catch (err) {
+            process.stderr.write(`oculi: telemetry replay failed (${err.message}) — continuing\n`);
+        }
+    }
+    try {
+        // listenTextResolver suppresses Fastify's default "Server listening at …"
+        // info-level log so our own banner is the only thing the user sees.
+        await app.listen({
+            port: config.port,
+            host: opts.bind,
+            listenTextResolver: () => '',
+        });
+    }
+    catch (err) {
+        const e = err;
+        if (e.code === 'EADDRINUSE') {
+            process.stderr.write(`oculi: port ${config.port} is already in use.\n` +
+                `Try \`oculi serve --port <other-port>\` or stop the process bound to ${config.port}.\n`);
+            await close();
+            process.exit(2);
+        }
+        process.stderr.write(`oculi: failed to start gateway: ${e.message}\n`);
+        await close();
+        process.exit(1);
+    }
+    const url = `http://${opts.bind === '0.0.0.0' ? 'localhost' : opts.bind}:${config.port}`;
+    process.stdout.write(`Oculi gateway listening on ${opts.bind}:${config.port}\n`);
+    process.stdout.write(`  Dashboard:  ${url}/admin/\n`);
+    process.stdout.write(`  Data dir:   ${opts.dataDir}\n`);
+    process.stdout.write(`  Auth:       ${auth ? 'enabled (JWT)' : 'disabled (local-dev)'}\n`);
+    process.stdout.write(`  Rate limit: ${config.rateLimitCapacity === 0 ? 'off' : `${config.rateLimitCapacity} cap / ${config.rateLimitRefillPerSecond}/s`}\n`);
+    for (const signal of ['SIGINT', 'SIGTERM']) {
+        process.on(signal, async () => {
+            process.stdout.write(`\noculi: received ${signal}, shutting down...\n`);
+            await close();
+            process.exit(0);
+        });
+    }
+}

package/dist/commands/tail.d.ts

@@ -0,0 +1,7 @@
+import { TelemetryLogEntry } from '../services/telemetry-log';
+export declare function formatEntry(entry: TelemetryLogEntry, colorEnabled: boolean): string;
+export interface TailOptions {
+    filter?: 'allow' | 'warn' | 'deny';
+    noColor?: boolean;
+}
+export declare function runTail(opts: TailOptions): void;