@mauribadnights/clooks 0.5.1 → 0.5.3

package/docs/reference/http-api.md

@@ -0,0 +1,122 @@
+# HTTP API
+
+clooks runs an HTTP server on localhost (default port 7890). Claude Code sends hook events as HTTP POST requests. The API also exposes health endpoints for monitoring and orchestration.
+
+---
+
+## Authentication
+
+If `settings.authToken` is configured in `manifest.yaml`, all requests except `GET /health` must include the token:
+
+```
+Authorization: Bearer <token>
+```
+
+Failed authentication returns `401 Unauthorized`.
+
+Rate limiting applies to authentication failures: after 10 failures within 60 seconds from the same source IP, the server returns `429 Too Many Requests` with a `Retry-After` header.
+
+---
+
+## Endpoints
+
+### GET /health
+
+Public health check. No authentication required.
+
+**Response:**
+
+```json
+{
+  "status": "ok",
+  "pid": 12345
+}
+```
+
+### GET /health/detail
+
+Authenticated detailed health check.
+
+**Response:**
+
+```json
+{
+  "status": "ok",
+  "pid": 12345,
+  "uptime": 3600,
+  "handlers": 8,
+  "port": 7890
+}
+```
+
+### POST /hooks/:eventName
+
+Main hook dispatch endpoint. Accepts a HookInput JSON body, executes all matching handlers for the event, and returns the merged result.
+
+The `:eventName` parameter must be one of the 9 valid hook events (see [Hook Events](hook-events.md)).
+
+**Request:**
+
+```bash
+curl -X POST http://localhost:7890/hooks/PreToolUse \
+  -H "Authorization: Bearer your-token" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "session_id": "abc123",
+    "hook_event_name": "PreToolUse",
+    "tool_name": "Bash",
+    "tool_input": { "command": "ls -la" },
+    "cwd": "/home/user/project",
+    "transcript_path": "/tmp/transcript.jsonl",
+    "permission_mode": "default"
+  }'
+```
+
+**Response:**
+
+```json
+{
+  "additionalContext": "Handler 1 output\nHandler 2 output",
+  "decision": "allow",
+  "reason": "All checks passed"
+}
+```
+
+---
+
+## Response Merging
+
+When multiple handlers return results for the same event, fields are merged as follows:
+
+| Field | Strategy |
+|-------|----------|
+| `additionalContext` | Concatenated with newlines |
+| `decision` | Last writer wins (latest handler in execution order) |
+| `reason` | Last writer wins |
+| `hookSpecificOutput` | Last writer wins |
+
+> **Note:** Handler execution order is determined by the order in `manifest.yaml`, modified by any `depends` declarations. See [Types](types.md) for the `HandlerConfig.depends` field.
+
+---
+
+## Error Responses
+
+| Status | Condition |
+|--------|-----------|
+| `400` | Invalid event name or malformed JSON body |
+| `401` | Missing or invalid auth token |
+| `404` | Unknown route |
+| `429` | Rate limited (too many authentication failures) |
+| `500` | Internal server error |
+
+All error responses return a JSON body:
+
+```json
+{
+  "error": "Description of the problem"
+}
+```
+
+---
+
+[Home](../index.md) | [Prev: Hook Events](hook-events.md) | [Next: Config Files](config-files.md)

package/docs/reference/types.md

@@ -0,0 +1,410 @@
+# Types
+
+TypeScript type reference for programmatic usage. All types are exported from the `@mauribadnights/clooks` package.
+
+```typescript
+import type { Manifest, HandlerConfig, HookInput, HookEvent } from '@mauribadnights/clooks';
+```
+
+---
+
+## Core Types
+
+### HookEvent
+
+```typescript
+type HookEvent =
+  | 'SessionStart'
+  | 'UserPromptSubmit'
+  | 'PreToolUse'
+  | 'PostToolUse'
+  | 'Stop'
+  | 'SubagentStart'
+  | 'SubagentStop'
+  | 'Notification'
+  | 'ConfigChange';
+```
+
+### HookInput
+
+```typescript
+interface HookInput {
+  session_id: string;
+  transcript_path: string;
+  cwd: string;
+  permission_mode: string;
+  hook_event_name: HookEvent;
+
+  // UserPromptSubmit
+  prompt?: string;
+
+  // Pre/PostToolUse
+  tool_name?: string;
+  tool_input?: Record<string, unknown>;
+
+  // SessionStart
+  source?: string;
+  agent_type?: string;
+
+  // Stop
+  stop_hook_active?: boolean;
+
+  // Internal: dependency outputs injected by the engine
+  _handlerOutputs?: Record<string, unknown>;
+
+  // Extensible for plugins
+  [key: string]: unknown;
+}
+```
+
+---
+
+## Handler Types
+
+### HandlerConfig
+
+A union of three handler types, all sharing a common base.
+
+```typescript
+interface BaseHandler {
+  id: string;
+  filter?: string;
+  timeout?: number;
+  enabled?: boolean;
+  sessionIsolation?: boolean;
+  depends?: string[];
+  async?: boolean;
+  agent?: string;
+  project?: string;
+}
+
+interface ScriptHandlerConfig extends BaseHandler {
+  type: 'script';
+  command: string;
+}
+
+interface InlineHandlerConfig extends BaseHandler {
+  type: 'inline';
+  module: string;
+}
+
+interface LLMHandlerConfig extends BaseHandler {
+  type: 'llm';
+  model: LLMModel;
+  prompt: string;
+  batchGroup?: string;
+  maxTokens?: number;      // Default: 1024
+  temperature?: number;    // Default: 1.0
+}
+
+type HandlerConfig = ScriptHandlerConfig | InlineHandlerConfig | LLMHandlerConfig;
+```
+
+### LLMModel
+
+```typescript
+type LLMModel = 'claude-haiku-4-5' | 'claude-sonnet-4-6' | 'claude-opus-4-6';
+```
+
+### HandlerResult
+
+```typescript
+interface HandlerResult {
+  id: string;
+  ok: boolean;
+  output?: unknown;
+  error?: string;
+  duration_ms: number;
+  filtered?: boolean;
+  usage?: TokenUsage;
+  cost_usd?: number;
+}
+```
+
+### HandlerState
+
+```typescript
+interface HandlerState {
+  consecutiveFailures: number;
+  disabled: boolean;
+  totalFires: number;
+  totalErrors: number;
+}
+```
+
+---
+
+## Manifest Types
+
+### Manifest
+
+```typescript
+interface Manifest {
+  handlers: Partial<Record<HookEvent, HandlerConfig[]>>;
+  prefetch?: PrefetchKey[];
+  settings?: {
+    port?: number;
+    logLevel?: 'debug' | 'info' | 'warn' | 'error';
+    anthropicApiKey?: string;
+    authToken?: string;
+  };
+}
+```
+
+### PluginManifest
+
+```typescript
+interface PluginManifest {
+  name: string;
+  version: string;
+  description?: string;
+  author?: string;
+  handlers: Partial<Record<HookEvent, HandlerConfig[]>>;
+  prefetch?: PrefetchKey[];
+  extras?: PluginExtras;
+}
+
+interface PluginExtras {
+  skills?: string[];
+  agents?: string[];
+  readme?: string;
+  [key: string]: unknown;
+}
+```
+
+---
+
+## Plugin Types
+
+### InstalledPlugin
+
+```typescript
+interface InstalledPlugin {
+  name: string;
+  version: string;
+  path: string;
+  installedAt: string;
+}
+```
+
+### PluginRegistry
+
+```typescript
+interface PluginRegistry {
+  plugins: InstalledPlugin[];
+}
+```
+
+---
+
+## Metrics Types
+
+### MetricEntry
+
+```typescript
+interface MetricEntry {
+  ts: string;
+  event: HookEvent;
+  handler: string;
+  duration_ms: number;
+  ok: boolean;
+  error?: string;
+  filtered?: boolean;
+  usage?: TokenUsage;
+  cost_usd?: number;
+  session_id?: string;
+  agent_type?: string;
+}
+```
+
+### CostEntry
+
+```typescript
+interface CostEntry {
+  ts: string;
+  event: HookEvent;
+  handler: string;
+  model: LLMModel;
+  usage: TokenUsage;
+  cost_usd: number;
+  batched: boolean;
+}
+```
+
+### TokenUsage
+
+```typescript
+interface TokenUsage {
+  input_tokens: number;
+  output_tokens: number;
+}
+```
+
+---
+
+## Context Types
+
+### PrefetchKey
+
+```typescript
+type PrefetchKey = 'transcript' | 'git_status' | 'git_diff';
+```
+
+### PrefetchContext
+
+```typescript
+interface PrefetchContext {
+  transcript?: string;
+  git_status?: string;
+  git_diff?: string;
+}
+```
+
+---
+
+## Diagnostic Types
+
+### DiagnosticResult
+
+```typescript
+interface DiagnosticResult {
+  check: string;
+  status: 'ok' | 'warn' | 'error';
+  message: string;
+}
+```
+
+---
+
+## Exported Functions
+
+### Server
+
+```typescript
+createServer(manifest: Manifest, metrics: MetricsCollector): ServerContext;
+startDaemon(manifest: Manifest, metrics: MetricsCollector, options?: object): Promise<ServerContext>;
+stopDaemon(): boolean;
+isDaemonRunning(): boolean;
+```
+
+### Manifest
+
+```typescript
+loadManifest(): Promise<Manifest>;
+loadCompositeManifest(): Promise<Manifest>;
+validateManifest(manifest: Manifest): void;
+createDefaultManifest(authToken?: string): Promise<string>;
+```
+
+### Plugins
+
+```typescript
+loadPlugins(pluginsDir?: string, registryPath?: string): Promise<Array>;
+mergeManifests(userManifest: Manifest, plugins: Array): Manifest;
+validatePluginManifest(manifest: PluginManifest): void;
+installPlugin(sourcePath: string, pluginsDir?: string, registryPath?: string): Promise<InstalledPlugin>;
+uninstallPlugin(name: string, pluginsDir?: string, registryPath?: string): Promise<void>;
+listPlugins(registryPath?: string): Promise<InstalledPlugin[]>;
+```
+
+### Handlers
+
+```typescript
+executeHandlers(
+  event: HookEvent,
+  input: HookInput,
+  handlers: HandlerConfig[],
+  context?: PrefetchContext,
+  onAsyncResult?: (result: HandlerResult) => void,
+  currentAgent?: string
+): Promise<HandlerResult[]>;
+
+resolveExecutionOrder(handlers: HandlerConfig[]): HandlerConfig[][];
+resetSessionIsolatedHandlers(handlers: Partial<Record<HookEvent, HandlerConfig[]>>): void;
+cleanupHandlerState(id: string): void;
+```
+
+### Filtering
+
+```typescript
+evaluateFilter(filter: string, input: HookInput): boolean;
+```
+
+### LLM
+
+```typescript
+executeLLMHandler(handler: LLMHandlerConfig, input: HookInput, context: PrefetchContext): Promise<HandlerResult>;
+executeLLMHandlersBatched(
+  handlers: LLMHandlerConfig[],
+  input: HookInput,
+  context: PrefetchContext,
+  sessionId?: string
+): Promise<HandlerResult[]>;
+calculateCost(model: LLMModel, usage: TokenUsage): number;
+```
+
+### Context
+
+```typescript
+prefetchContext(keys: PrefetchKey[], input: HookInput): Promise<PrefetchContext>;
+renderPromptTemplate(template: string, input: HookInput, context: PrefetchContext): string;
+```
+
+### Auth
+
+```typescript
+generateAuthToken(): string;
+validateAuth(authHeader: string, expectedToken: string): boolean;
+rotateToken(options?: object): Promise<string>;
+```
+
+### Metrics
+
+```typescript
+class MetricsCollector {
+  record(entry: MetricEntry): void;
+  // ...
+}
+```
+
+### Rate Limiting
+
+```typescript
+class RateLimiter { /* ... */ }
+class DenyCache { /* ... */ }
+```
+
+### Service
+
+```typescript
+installService(): Promise<void>;
+uninstallService(): Promise<void>;
+isServiceInstalled(): Promise<boolean>;
+getServiceStatus(): Promise<string>;
+```
+
+### Migration and Diagnostics
+
+```typescript
+migrate(): Promise<void>;
+restore(): Promise<void>;
+syncSettings(): Promise<void>;
+runDoctor(): Promise<DiagnosticResult[]>;
+```
+
+### File Watching
+
+```typescript
+startWatcher(path: string, onReload: () => void, onError?: (err: Error) => void): FSWatcher | null;
+stopWatcher(watcher: FSWatcher): void;
+```
+
+### Agent
+
+```typescript
+installAgent(): Promise<void>;
+```
+
+---
+
+[Home](../index.md) | [Prev: Config Files](config-files.md) | [Next: Monitoring](../operations/monitoring.md)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mauribadnights/clooks",
-  "version": "0.5.1",
+  "version": "0.5.3",
   "description": "Persistent hook runtime for Claude Code — eliminates process spawning overhead and gives you observability",
   "bin": {
     "clooks": "./dist/cli.js"
@@ -16,6 +16,7 @@
   },
   "license": "MIT",
   "author": "mauribadnights",
+  "homepage": "https://mauribadnights.github.io/clooks/",
   "repository": {
     "type": "git",
     "url": "https://github.com/mauribadnights/clooks.git"