@oculisecurity/cli 0.1.0

package/dist/install/cursor.d.ts

@@ -0,0 +1,13 @@
+export interface InstallOpts {
+    /** Override the home directory (tests only). Production callers should omit this. */
+    home?: string;
+}
+export interface InstallResult {
+    path: string;
+    added: string[];
+    removed: string[];
+}
+export declare function installCursor(opts?: InstallOpts): InstallResult;
+export declare function uninstallCursor(opts?: InstallOpts): InstallResult;
+/** Does ~/.cursor/hooks.json still have any oculi-marked hook? */
+export declare function hasOculiHooks(home?: string): boolean;

package/dist/install/cursor.js

@@ -0,0 +1,119 @@
+"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.installCursor = installCursor;
+exports.uninstallCursor = uninstallCursor;
+exports.hasOculiHooks = hasOculiHooks;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const os = __importStar(require("os"));
+/** Cursor hook events managed by Oculi. */
+const OCULI_EVENTS = [
+    'beforeShellExecution',
+    'afterFileEdit',
+    'beforeReadFile',
+    'beforeMCPExecution',
+    'stop',
+];
+const OCULI_MARKER = 'oculi emit cursor';
+function resolveConfigPath(opts) {
+    return path.join(opts.home ?? os.homedir(), '.cursor', 'hooks.json');
+}
+function readConfig(filePath) {
+    if (!fs.existsSync(filePath)) {
+        return { version: 1, hooks: {} };
+    }
+    const raw = fs.readFileSync(filePath, 'utf8');
+    const parsed = JSON.parse(raw);
+    return {
+        version: parsed.version ?? 1,
+        hooks: parsed.hooks ?? {},
+    };
+}
+function installCursor(opts = {}) {
+    const configPath = resolveConfigPath(opts);
+    const config = readConfig(configPath);
+    const added = [];
+    for (const event of OCULI_EVENTS) {
+        const entries = config.hooks[event] ?? [];
+        const alreadyInstalled = entries.some((e) => e.command.includes(OCULI_MARKER));
+        if (!alreadyInstalled) {
+            config.hooks[event] = [...entries, { command: `oculi emit cursor ${event}` }];
+            added.push(event);
+        }
+    }
+    if (added.length > 0) {
+        fs.mkdirSync(path.dirname(configPath), { recursive: true });
+        fs.writeFileSync(configPath, JSON.stringify(config, null, 2) + '\n', 'utf8');
+    }
+    return { path: configPath, added, removed: [] };
+}
+function uninstallCursor(opts = {}) {
+    const configPath = resolveConfigPath(opts);
+    const config = readConfig(configPath);
+    const removed = [];
+    for (const event of Object.keys(config.hooks)) {
+        const before = config.hooks[event];
+        const after = before.filter((e) => !e.command.includes(OCULI_MARKER));
+        if (after.length < before.length) {
+            removed.push(...before.filter((e) => e.command.includes(OCULI_MARKER)).map(() => event));
+            if (after.length === 0) {
+                delete config.hooks[event];
+            }
+            else {
+                config.hooks[event] = after;
+            }
+        }
+    }
+    if (removed.length > 0) {
+        if (Object.keys(config.hooks).length === 0) {
+            fs.writeFileSync(configPath, JSON.stringify({ version: config.version, hooks: {} }, null, 2) + '\n', 'utf8');
+        }
+        else {
+            fs.writeFileSync(configPath, JSON.stringify(config, null, 2) + '\n', 'utf8');
+        }
+    }
+    return { path: configPath, added: [], removed };
+}
+/** Does ~/.cursor/hooks.json still have any oculi-marked hook? */
+function hasOculiHooks(home) {
+    const configPath = resolveConfigPath({ home });
+    const config = readConfig(configPath);
+    for (const entries of Object.values(config.hooks)) {
+        if (entries.some((e) => e.command.includes(OCULI_MARKER)))
+            return true;
+    }
+    return false;
+}

package/dist/install/detect.d.ts

@@ -0,0 +1,5 @@
+export declare const AGENTS: readonly ["claude-code", "cursor"];
+export type Agent = (typeof AGENTS)[number];
+export declare const BINARIES: Record<Agent, string>;
+export declare function isAgentInstalled(agent: Agent): boolean;
+export declare function detectAgents(): Agent[];

package/dist/install/detect.js

@@ -0,0 +1,64 @@
+"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.BINARIES = exports.AGENTS = void 0;
+exports.isAgentInstalled = isAgentInstalled;
+exports.detectAgents = detectAgents;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+exports.AGENTS = ['claude-code', 'cursor'];
+exports.BINARIES = {
+    'claude-code': 'claude',
+    cursor: 'cursor',
+};
+const WIN_EXTS = ['.exe', '.cmd', '.bat'];
+function pathEntries() {
+    const sep = process.platform === 'win32' ? ';' : ':';
+    return (process.env.PATH ?? '').split(sep).filter(Boolean);
+}
+function existsInDir(dir, bin) {
+    if (process.platform === 'win32') {
+        if (WIN_EXTS.some((e) => fs.existsSync(path.join(dir, bin + e))))
+            return true;
+    }
+    return fs.existsSync(path.join(dir, bin));
+}
+function isAgentInstalled(agent) {
+    const bin = exports.BINARIES[agent];
+    return pathEntries().some((dir) => existsInDir(dir, bin));
+}
+function detectAgents() {
+    return exports.AGENTS.filter(isAgentInstalled);
+}

package/dist/middleware/auth.d.ts

@@ -0,0 +1,15 @@
+import { FastifyRequest, FastifyInstance } from 'fastify';
+import { AuthenticatedActor } from '../types';
+/**
+ * Resolve an AuthenticatedActor from a request — used by routes that need
+ * auth but handle it themselves (e.g. /mcp which also accepts ?token= for SSE).
+ * Reads from request.actor (set by middleware) or falls back to the ?token=
+ * query parameter (browsers can't set headers for SSE connections).
+ */
+export declare function resolveActor(request: FastifyRequest, jwtSecret: string): AuthenticatedActor | null;
+declare module 'fastify' {
+    interface FastifyRequest {
+        actor: AuthenticatedActor;
+    }
+}
+export declare function registerAuthMiddleware(app: FastifyInstance, jwtSecret: string): void;

package/dist/middleware/auth.js

@@ -0,0 +1,116 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveActor = resolveActor;
+exports.registerAuthMiddleware = registerAuthMiddleware;
+const jsonwebtoken_1 = __importDefault(require("jsonwebtoken"));
+/**
+ * Resolve an AuthenticatedActor from a request — used by routes that need
+ * auth but handle it themselves (e.g. /mcp which also accepts ?token= for SSE).
+ * Reads from request.actor (set by middleware) or falls back to the ?token=
+ * query parameter (browsers can't set headers for SSE connections).
+ */
+function resolveActor(request, jwtSecret) {
+    if (request.actor?.actor)
+        return request.actor;
+    const query = request.query;
+    const token = query.token;
+    if (!token)
+        return null;
+    try {
+        const payload = jsonwebtoken_1.default.verify(token, jwtSecret);
+        if (!payload.actor || !payload.orgId || !Array.isArray(payload.roles))
+            return null;
+        return { sub: payload.sub, actor: payload.actor, orgId: payload.orgId, roles: payload.roles };
+    }
+    catch {
+        return null;
+    }
+}
+function registerAuthMiddleware(app, jwtSecret) {
+    // Decorate request so TypeScript knows the property exists
+    app.decorateRequest('actor', null);
+    // Prehandler hook: runs on every request before route handlers
+    app.addHook('preHandler', async (request, reply) => {
+        // No-auth mode (e.g. `oculi serve` on localhost): inject a synthetic admin
+        // actor on every request and skip all JWT logic. Routes that gate on
+        // `request.actor` (admin APIs, MCP) still work; protected proxy endpoints
+        // (/v1/call etc.) are reachable, which is intended for local dev.
+        if (!jwtSecret) {
+            request.actor = {
+                sub: 'local',
+                actor: 'local-dev',
+                orgId: 'default',
+                roles: ['admin'],
+            };
+            return;
+        }
+        // Skip auth for health check and all /admin static assets.
+        // The admin HTML is served unauthenticated; the /admin/logs and /admin/upstreams
+        // API routes enforce auth themselves via request.actor checks.
+        if (request.url === '/health' ||
+            request.url === '/favicon.ico' ||
+            request.url === '/favicon.svg' ||
+            request.url === '/v1/events' ||
+            request.url === '/v1/hooks') {
+            return;
+        }
+        // For /admin and /mcp routes: parse JWT if present but don't require it.
+        // /admin static assets need no auth; API routes check request.actor internally.
+        // /mcp handles auth inside the route (also accepts ?token= for SSE browser connections).
+        if (request.url.startsWith('/admin') || request.url.startsWith('/api/admin') || request.url.startsWith('/mcp')) {
+            const header = request.headers['authorization'];
+            if (header?.startsWith('Bearer ')) {
+                try {
+                    const p = jsonwebtoken_1.default.verify(header.slice(7), jwtSecret);
+                    if (p.actor && p.orgId && Array.isArray(p.roles)) {
+                        request.actor = { sub: p.sub, actor: p.actor, orgId: p.orgId, roles: p.roles };
+                    }
+                }
+                catch { /* token invalid — continue without auth */ }
+            }
+            return;
+        }
+        const authHeader = request.headers['authorization'];
+        if (!authHeader || !authHeader.startsWith('Bearer ')) {
+            reply.code(401).send({
+                error: 'Missing or malformed Authorization header. Expected: Bearer <token>',
+                code: 'MISSING_TOKEN',
+            });
+            return;
+        }
+        const token = authHeader.slice(7);
+        let payload;
+        try {
+            payload = jsonwebtoken_1.default.verify(token, jwtSecret);
+        }
+        catch (err) {
+            const message = err instanceof jsonwebtoken_1.default.TokenExpiredError
+                ? 'Token has expired'
+                : err instanceof jsonwebtoken_1.default.JsonWebTokenError
+                    ? 'Invalid token signature'
+                    : 'Token verification failed';
+            reply.code(401).send({
+                error: message,
+                code: 'INVALID_TOKEN',
+            });
+            return;
+        }
+        // Validate required fields
+        if (!payload.actor || !payload.orgId || !Array.isArray(payload.roles)) {
+            reply.code(401).send({
+                error: 'Token payload missing required fields (actor, orgId, roles)',
+                code: 'MALFORMED_TOKEN',
+            });
+            return;
+        }
+        request.actor = {
+            sub: payload.sub,
+            actor: payload.actor,
+            orgId: payload.orgId,
+            roles: payload.roles,
+        };
+    });
+}

package/dist/routes/adapters/claude-code.d.ts

@@ -0,0 +1,38 @@
+import { OculiEvent } from './schema';
+/**
+ * Parse a Claude Code hook event from raw stdin JSON and the hook event name.
+ *
+ * This is the single source of truth for all Claude Code payload parsing.
+ * The HTTP adapter's normalize() delegates here so that nothing outside this
+ * module ever needs to understand Claude Code's wire format.
+ *
+ * @param stdin     Raw JSON string sent to the hook's stdin by Claude Code.
+ * @param hookEvent Hook event name from the Claude Code runtime
+ *                  (e.g. 'PreToolUse', 'PostToolUse').
+ */
+export declare function parseClaudeCodeEvent(stdin: string, hookEvent: string): OculiEvent;
+/**
+ * Detect whether a parsed request body came from Claude Code.
+ * Detection key: tool_name + session_id (Cursor uses conversation_id instead).
+ */
+export declare function detect(body: Record<string, unknown>): boolean;
+/**
+ * Normalize a pre-parsed HTTP request body into an OculiEvent.
+ * Delegates all parsing logic to parseClaudeCodeEvent.
+ */
+export declare function normalize(body: Record<string, unknown>): OculiEvent;
+/**
+ * Output shapes follow the Claude Code hook spec at
+ * https://code.claude.com/docs/en/hooks.
+ *
+ *  - PreToolUse: blocking via `hookSpecificOutput.permissionDecision`.
+ *  - PostToolUse: cannot block the tool (already ran); top-level `decision: "block"`
+ *    only prevents Claude from continuing to the next turn.
+ *  - Stop / others: empty `{}` = allow / default behavior. We never block Stop.
+ *
+ * All shapes are emitted with exit code 0; Claude Code ignores stdout on exit 2.
+ */
+export declare function formatAllow(_event: OculiEvent): string;
+export declare function formatDeny(reason: string, event: OculiEvent): string;
+export declare function formatWarn(reason: string, event: OculiEvent): string;
+export declare function denyStatusCode(): number;

package/dist/routes/adapters/claude-code.js

@@ -0,0 +1,125 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseClaudeCodeEvent = parseClaudeCodeEvent;
+exports.detect = detect;
+exports.normalize = normalize;
+exports.formatAllow = formatAllow;
+exports.formatDeny = formatDeny;
+exports.formatWarn = formatWarn;
+exports.denyStatusCode = denyStatusCode;
+/**
+ * Adapter for Claude Code PreToolUse / PostToolUse hook payloads.
+ *
+ * Wire format (sent to the hook's stdin by Claude Code):
+ *   { hook_event_name, tool_name, tool_input, tool_response, session_id, cwd, ... }
+ *
+ * Block response (written to stdout):
+ *   { "decision": "block", "reason": "..." }
+ */
+/**
+ * Normalize Claude Code tool names to standard cross-IDE identifiers.
+ * Unmatched tool names pass through unchanged (preserving specificity).
+ */
+const TOOL_NORMALIZATIONS = {
+    Bash: 'shell',
+    Read: 'file_read',
+    Write: 'file_edit',
+    Edit: 'file_edit',
+    MultiEdit: 'file_edit',
+};
+/**
+ * Parse a Claude Code hook event from raw stdin JSON and the hook event name.
+ *
+ * This is the single source of truth for all Claude Code payload parsing.
+ * The HTTP adapter's normalize() delegates here so that nothing outside this
+ * module ever needs to understand Claude Code's wire format.
+ *
+ * @param stdin     Raw JSON string sent to the hook's stdin by Claude Code.
+ * @param hookEvent Hook event name from the Claude Code runtime
+ *                  (e.g. 'PreToolUse', 'PostToolUse').
+ */
+function parseClaudeCodeEvent(stdin, hookEvent) {
+    const body = JSON.parse(stdin);
+    const phase = hookEvent === 'PreToolUse' ? 'pre' : 'post';
+    const rawTool = body.tool_name;
+    const tool = TOOL_NORMALIZATIONS[rawTool] ?? rawTool;
+    const toolInput = body.tool_input;
+    const cwd = body.cwd;
+    // For shell tools, populate shell_command and action.command from tool_input
+    let shell_command;
+    let action;
+    if (tool === 'shell' && toolInput?.command) {
+        shell_command = String(toolInput.command);
+        action = { command: shell_command };
+    }
+    return {
+        schema_version: '1',
+        ide_source: 'claude-code',
+        actor: 'claude-code',
+        org_id: 'default',
+        hook_event_name: hookEvent,
+        phase,
+        session_id: body.session_id,
+        tool,
+        tool_args: toolInput,
+        tool_result: body.tool_response,
+        shell_command,
+        cwd,
+        context: cwd ? { workspace: cwd } : undefined,
+        action,
+        timestamp: new Date().toISOString(),
+        raw_payload: body,
+    };
+}
+/**
+ * Detect whether a parsed request body came from Claude Code.
+ * Detection key: tool_name + session_id (Cursor uses conversation_id instead).
+ */
+function detect(body) {
+    return (typeof body.tool_name === 'string' &&
+        typeof body.session_id === 'string');
+}
+/**
+ * Normalize a pre-parsed HTTP request body into an OculiEvent.
+ * Delegates all parsing logic to parseClaudeCodeEvent.
+ */
+function normalize(body) {
+    const hookEvent = body.hook_event_name ?? 'PostToolUse';
+    return parseClaudeCodeEvent(JSON.stringify(body), hookEvent);
+}
+/**
+ * Output shapes follow the Claude Code hook spec at
+ * https://code.claude.com/docs/en/hooks.
+ *
+ *  - PreToolUse: blocking via `hookSpecificOutput.permissionDecision`.
+ *  - PostToolUse: cannot block the tool (already ran); top-level `decision: "block"`
+ *    only prevents Claude from continuing to the next turn.
+ *  - Stop / others: empty `{}` = allow / default behavior. We never block Stop.
+ *
+ * All shapes are emitted with exit code 0; Claude Code ignores stdout on exit 2.
+ */
+function formatAllow(_event) {
+    return '{}';
+}
+function formatDeny(reason, event) {
+    if (event.hook_event_name === 'PreToolUse') {
+        return JSON.stringify({
+            hookSpecificOutput: {
+                hookEventName: 'PreToolUse',
+                permissionDecision: 'deny',
+                permissionDecisionReason: reason,
+            },
+        });
+    }
+    // PostToolUse (and unknown events) — prevent Claude from continuing.
+    return JSON.stringify({ decision: 'block', reason });
+}
+function formatWarn(reason, event) {
+    if (event.hook_event_name === 'PreToolUse') {
+        return JSON.stringify({ systemMessage: reason });
+    }
+    return '{}';
+}
+function denyStatusCode() {
+    return 200; // Claude Code reads the JSON body; HTTP status is always 200
+}

package/dist/routes/adapters/cursor.d.ts

@@ -0,0 +1,21 @@
+import { OculiEvent } from './schema';
+/**
+ * Parse a Cursor hook event from raw stdin JSON and the hook event name.
+ *
+ * This is the single source of truth for all Cursor payload parsing.
+ * The HTTP adapter's normalize() delegates here.
+ *
+ * @param stdin     Raw JSON string sent to the hook's stdin by Cursor.
+ * @param hookEvent Hook event name (e.g. 'beforeShellExecution', 'stop').
+ */
+export declare function parseCursorEvent(stdin: string, hookEvent: string): OculiEvent;
+/** Detect whether a parsed request body came from Cursor. */
+export declare function detect(body: Record<string, unknown>): boolean;
+/**
+ * Normalize a pre-parsed HTTP request body into an OculiEvent.
+ * Delegates all parsing logic to parseCursorEvent.
+ */
+export declare function normalize(body: Record<string, unknown>): OculiEvent;
+export declare function formatAllow(_event: OculiEvent): string;
+export declare function formatDeny(reason: string, _event: OculiEvent): string;
+export declare function denyStatusCode(): number;

package/dist/routes/adapters/cursor.js

@@ -0,0 +1,139 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseCursorEvent = parseCursorEvent;
+exports.detect = detect;
+exports.normalize = normalize;
+exports.formatAllow = formatAllow;
+exports.formatDeny = formatDeny;
+exports.denyStatusCode = denyStatusCode;
+const crypto_1 = require("crypto");
+/**
+ * Adapter for Cursor hook payloads.
+ *
+ * Wire formats (all share conversation_id + generation_id + hook_event_name):
+ *
+ *   beforeShellExecution:  { conversation_id, generation_id, hook_event_name, content, workspace_roots }
+ *   afterFileEdit:         { conversation_id, generation_id, hook_event_name, file_path, content, workspace_roots }
+ *   beforeReadFile:        { conversation_id, generation_id, hook_event_name, file_path, content, workspace_roots }
+ *   beforeMCPExecution:    { conversation_id, generation_id, hook_event_name, mcp_server, mcp_tool, workspace_roots }
+ *   afterMCPExecution:     { conversation_id, generation_id, hook_event_name, mcp_server, mcp_tool, workspace_roots }
+ *   stop:                  { conversation_id, generation_id, hook_event_name, workspace_roots }
+ *
+ * Detection: conversation_id + generation_id (both strings).
+ *
+ * Block response (written to stdout):
+ *   { "permissionDecision": "deny", "permissionDecisionReason": "..." }
+ */
+/** 16-hex-char SHA-256 prefix — enough to detect duplicates, not enough to reconstruct content. */
+function sha256prefix(content) {
+    return (0, crypto_1.createHash)('sha256').update(content).digest('hex').slice(0, 16);
+}
+/**
+ * Parse a Cursor hook event from raw stdin JSON and the hook event name.
+ *
+ * This is the single source of truth for all Cursor payload parsing.
+ * The HTTP adapter's normalize() delegates here.
+ *
+ * @param stdin     Raw JSON string sent to the hook's stdin by Cursor.
+ * @param hookEvent Hook event name (e.g. 'beforeShellExecution', 'stop').
+ */
+function parseCursorEvent(stdin, hookEvent) {
+    const body = JSON.parse(stdin);
+    let phase;
+    if (hookEvent === 'stop') {
+        phase = 'complete';
+    }
+    else if (hookEvent.startsWith('after')) {
+        phase = 'post';
+    }
+    else {
+        phase = 'pre';
+    }
+    let tool;
+    let tool_args;
+    let tool_result;
+    let file_path;
+    let shell_command;
+    let mcp_server;
+    let action;
+    switch (hookEvent) {
+        case 'beforeShellExecution':
+            tool = 'shell';
+            shell_command = body.content;
+            tool_args = { command: body.content };
+            if (body.content)
+                action = { command: body.content };
+            break;
+        case 'beforeReadFile':
+            tool = 'file_read';
+            file_path = body.file_path;
+            tool_args = { path: body.file_path };
+            if (body.content)
+                action = { content_hash: sha256prefix(body.content) };
+            break;
+        case 'afterFileEdit':
+            tool = 'file_edit';
+            file_path = body.file_path;
+            tool_result = { path: body.file_path };
+            if (body.content)
+                action = { content_hash: sha256prefix(body.content) };
+            break;
+        case 'beforeMCPExecution':
+        case 'afterMCPExecution':
+            tool = 'mcp_call';
+            mcp_server = body.mcp_server;
+            tool_args = { mcp_tool: body.mcp_tool, mcp_server: body.mcp_server };
+            break;
+        case 'stop':
+            tool = 'session_stop';
+            break;
+    }
+    const workspace_roots = Array.isArray(body.workspace_roots)
+        ? body.workspace_roots
+        : undefined;
+    const conversationId = body.conversation_id;
+    const workspace = workspace_roots?.[0];
+    return {
+        schema_version: '1',
+        ide_source: 'cursor',
+        actor: 'cursor',
+        org_id: 'default',
+        hook_event_name: hookEvent,
+        phase,
+        session_id: conversationId,
+        trace_id: body.generation_id,
+        tool,
+        tool_args,
+        tool_result,
+        file_path,
+        shell_command,
+        mcp_server,
+        workspace_roots,
+        context: { workspace, conversation_id: conversationId },
+        action,
+        timestamp: new Date().toISOString(),
+        raw_payload: body,
+    };
+}
+/** Detect whether a parsed request body came from Cursor. */
+function detect(body) {
+    return (typeof body.conversation_id === 'string' &&
+        typeof body.generation_id === 'string');
+}
+/**
+ * Normalize a pre-parsed HTTP request body into an OculiEvent.
+ * Delegates all parsing logic to parseCursorEvent.
+ */
+function normalize(body) {
+    const hookEvent = body.hook_event_name ?? 'unknown';
+    return parseCursorEvent(JSON.stringify(body), hookEvent);
+}
+function formatAllow(_event) {
+    return JSON.stringify({ permissionDecision: 'allow' });
+}
+function formatDeny(reason, _event) {
+    return JSON.stringify({ permissionDecision: 'deny', permissionDecisionReason: reason });
+}
+function denyStatusCode() {
+    return 200; // Cursor reads permissionDecision from the JSON body
+}

package/dist/routes/adapters/index.d.ts

@@ -0,0 +1,16 @@
+import { OculiEvent } from './schema';
+export interface HookAdapter {
+    detect(body: Record<string, unknown>): boolean;
+    normalize(body: Record<string, unknown>): OculiEvent;
+    formatAllow(event: OculiEvent): string;
+    formatDeny(reason: string, event: OculiEvent): string;
+    /** Non-blocking advisory output. Optional: only adapters whose hook protocol distinguishes warn from allow need to implement this. */
+    formatWarn?(reason: string, event: OculiEvent): string;
+    /** HTTP status code for deny responses. Most adapters use 200 (body carries the decision); Windsurf uses 403. */
+    denyStatusCode(): number;
+}
+/**
+ * Find the first adapter that recognises the given payload.
+ * Returns null if no adapter matches (unknown source).
+ */
+export declare function detectAdapter(body: Record<string, unknown>): HookAdapter | null;