@hasna/hooks 0.2.19 → 0.3.0

package/dist/db/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * SQLite DB module for hooks — persistent storage at ~/.hasna/hooks/hooks.db
+ *
+ * Uses bun:sqlite with WAL mode for concurrent reads.
+ * Supports HASNA_HOOKS_DATA_DIR / HOOKS_DATA_DIR and HASNA_HOOKS_DB_PATH / HOOKS_DB_PATH env overrides.
+ */
+import { Database } from "bun:sqlite";
+export declare function getDbPath(): string;
+export declare function getDb(): Database;
+export declare function closeDb(): void;
+export declare function createTestDb(): Database;

package/dist/db/legacy-import.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Legacy flat-file import — runs once on first DB creation.
+ *
+ * Scans for old .claude/session-log-*.jsonl and .claude/errors.log files
+ * in the user's home projects directory and imports their entries into hook_events.
+ *
+ * Non-blocking: any failure is logged to stderr and skipped.
+ * Tracks completion via a `_meta` table row keyed "legacy_import_done".
+ */
+import type { Database } from "bun:sqlite";
+export declare function runLegacyImport(db: Database): void;

package/dist/db/migrations/001_initial.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Migration 001 — initial schema
+ * Creates hook_events table and indexes.
+ */
+import type { Database } from "bun:sqlite";
+export declare function up(db: Database): void;

package/dist/db/migrations/002_session_events.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Migration 002 — session events
+ * Rebuilds hook_events so the event_type CHECK constraint accepts
+ * 'SessionStart' and 'SessionEnd'. SQLite cannot ALTER a CHECK
+ * constraint, so the table is recreated and rows are copied over.
+ * Skips the rebuild when the constraint already includes SessionStart
+ * (fresh databases created from the updated schema.ts).
+ */
+import type { Database } from "bun:sqlite";
+export declare function up(db: Database): void;

package/dist/db/migrations/003_user_prompt_submit_event.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Migration 003 — UserPromptSubmit event.
+ *
+ * Rebuilds hook_events so the event_type CHECK constraint accepts Codewith's
+ * UserPromptSubmit. SQLite cannot ALTER a CHECK constraint, so the table is
+ * recreated and rows are copied over. Skips the rebuild when the constraint is
+ * already current (fresh databases or databases rebuilt by a newer 002).
+ */
+import type { Database } from "bun:sqlite";
+export declare function up(db: Database): void;

package/dist/db/migrations/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Migration runner — applies pending migrations in order.
+ * Tracks applied migrations in a `schema_migrations` table.
+ * Migrations are additive-only, never destructive.
+ */
+import type { Database } from "bun:sqlite";
+export declare function runMigrations(db: Database): void;

package/dist/db/pg-migrations.d.ts

@@ -0,0 +1,7 @@
+/**
+ * PostgreSQL migrations for open-hooks remote storage and sync.
+ *
+ * Equivalent to the SQLite schema in schema.ts, migrations/, and index.ts,
+ * translated for PostgreSQL.
+ */
+export declare const PG_MIGRATIONS: string[];

package/dist/db/remote-storage.d.ts

@@ -0,0 +1,9 @@
+export declare class PgAdapterAsync {
+    private readonly pool;
+    constructor(connectionString: string);
+    run(sql: string, ...params: unknown[]): Promise<{
+        changes: number;
+    }>;
+    all(sql: string, ...params: unknown[]): Promise<unknown[]>;
+    close(): Promise<void>;
+}

package/dist/db/retention.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Retention/cleanup — auto-prune hook_events older than N days.
+ *
+ * Configurable via HOOKS_RETENTION_DAYS env var (default: 30).
+ * Called on DB open after migrations.
+ */
+import type { Database } from "bun:sqlite";
+export declare function runRetention(db: Database, days?: number): number;

package/dist/db/schema.d.ts

@@ -0,0 +1,22 @@
+/**
+ * SQLite schema for @hasna/hooks local data.
+ * Owned by this package (no shared runtime dependency).
+ */
+import type { Database } from "bun:sqlite";
+export declare const CREATE_HOOK_EVENTS_TABLE = "\n  CREATE TABLE IF NOT EXISTS hook_events (\n    id           TEXT PRIMARY KEY,\n    timestamp    TEXT NOT NULL,\n    session_id   TEXT NOT NULL,\n    hook_name    TEXT NOT NULL,\n    event_type   TEXT NOT NULL CHECK (event_type IN ('PreToolUse', 'PostToolUse', 'Stop', 'Notification', 'SessionStart', 'SessionEnd', 'UserPromptSubmit')),\n    tool_name    TEXT,\n    tool_input   TEXT,\n    result       TEXT CHECK (result IN ('continue', 'block', NULL)),\n    error        TEXT,\n    duration_ms  INTEGER,\n    project_dir  TEXT,\n    metadata     TEXT\n  )\n";
+export declare const CREATE_INDEXES: string[];
+export interface HookEventRow {
+    id: string;
+    timestamp: string;
+    session_id: string;
+    hook_name: string;
+    event_type: "PreToolUse" | "PostToolUse" | "Stop" | "Notification" | "SessionStart" | "SessionEnd" | "UserPromptSubmit";
+    tool_name: string | null;
+    tool_input: string | null;
+    result: "continue" | "block" | null;
+    error: string | null;
+    duration_ms: number | null;
+    project_dir: string | null;
+    metadata: string | null;
+}
+export declare function applySchema(db: Database): void;

package/dist/db/storage-sync.d.ts

@@ -0,0 +1,57 @@
+import { PgAdapterAsync } from "./remote-storage.js";
+export declare const STORAGE_TABLES: readonly ["hook_events", "schema_migrations", "_meta", "feedback"];
+export declare const HOOKS_STORAGE_TABLES: readonly ["hook_events", "schema_migrations", "_meta", "feedback"];
+type StorageTable = (typeof STORAGE_TABLES)[number];
+export type StorageMode = "local" | "hybrid" | "remote";
+export interface StorageEnv {
+    name: string;
+}
+export interface SyncResult {
+    table: string;
+    rowsRead: number;
+    rowsWritten: number;
+    errors: string[];
+}
+export interface SyncMeta {
+    table_name: string;
+    last_synced_at: string | null;
+    direction: "push" | "pull";
+}
+export declare const HOOKS_STORAGE_ENV = "HASNA_HOOKS_DATABASE_URL";
+export declare const HOOKS_STORAGE_FALLBACK_ENV = "HOOKS_DATABASE_URL";
+export declare const HOOKS_STORAGE_MODE_ENV = "HASNA_HOOKS_STORAGE_MODE";
+export declare const HOOKS_STORAGE_MODE_FALLBACK_ENV = "HOOKS_STORAGE_MODE";
+export declare const STORAGE_DATABASE_ENV: readonly ["HASNA_HOOKS_DATABASE_URL", "HOOKS_DATABASE_URL"];
+export declare const STORAGE_MODE_ENV: readonly ["HASNA_HOOKS_STORAGE_MODE", "HOOKS_STORAGE_MODE"];
+export interface StorageStatus {
+    configured: boolean;
+    mode: StorageMode;
+    env: typeof STORAGE_DATABASE_ENV;
+    activeEnv: string | null;
+    service: "hooks";
+    tables: typeof STORAGE_TABLES;
+    sync: SyncMeta[];
+}
+export declare function getStorageDatabaseEnvName(): (typeof STORAGE_DATABASE_ENV)[number] | null;
+export declare function getStorageDatabaseEnv(): StorageEnv | null;
+export declare function getStorageDatabaseUrl(): string | null;
+export declare function getStorageMode(): StorageMode;
+export declare function getStoragePg(): Promise<PgAdapterAsync>;
+export declare function runStorageMigrations(remote: PgAdapterAsync): Promise<void>;
+export declare function storagePush(options?: {
+    tables?: string[];
+}): Promise<SyncResult[]>;
+export declare function storagePull(options?: {
+    tables?: string[];
+}): Promise<SyncResult[]>;
+export declare function storageSync(options?: {
+    tables?: string[];
+}): Promise<{
+    pull: SyncResult[];
+    push: SyncResult[];
+}>;
+export declare function getSyncMetaAll(): SyncMeta[];
+export declare function getStorageStatus(): StorageStatus;
+export declare function resolveTables(tables?: string[]): StorageTable[];
+export declare function parseStorageTables(value?: string | string[] | null): StorageTable[] | undefined;
+export {};

package/dist/index.d.ts

@@ -0,0 +1,72 @@
+/**
+ * @hasna/hooks - Open source Claude Code hooks library
+ *
+ * Install hooks with a single command:
+ *   npx @hasna/hooks install gitguard branchprotect
+ *
+ * Or use the interactive CLI:
+ *   npx @hasna/hooks
+ */
+export { HOOKS, HOOK_EVENTS, CATEGORIES, getHook, getHooksByCategory, searchHooks, type HookMeta, type HookEvent, type Category, } from "./lib/registry.js";
+import type { HookEvent as HookEventType } from "./lib/registry.js";
+export { installHook, installHooks, getInstalledHooks, getRegisteredHooks, getRegisteredHooksForTarget, removeHook, hookExists, buildCodewithTomlFragment, getHookPath, getSettingsPath, isEventSupported, type InstallResult, type InstallOptions, type Scope, type Target, type CodewithInstallMode, } from "./lib/installer.js";
+export interface HookAgentInfo {
+    agent_id: string;
+    agent_type: "claude" | "gemini" | "codewith" | "custom";
+    name?: string;
+    preferences?: Record<string, unknown>;
+}
+/** The JSON object passed to a hook via stdin */
+export interface HookInput {
+    session_id?: string;
+    cwd?: string;
+    hook_event_name?: HookEventType | string;
+    prompt?: string;
+    tool_name?: string;
+    tool_input?: Record<string, unknown>;
+    agent?: HookAgentInfo;
+    [key: string]: unknown;
+}
+/** The JSON object a PreToolUse hook returns via stdout */
+export interface HookOutput {
+    decision?: "approve" | "block";
+    reason?: string;
+    continue?: boolean;
+    hookSpecificOutput?: {
+        hookEventName: "SessionStart" | "UserPromptSubmit" | "PreToolUse" | "PostToolUse" | "Stop" | "Notification" | "SessionEnd";
+        additionalContext?: string;
+        permissionDecision?: "allow" | "deny" | "ask";
+        permissionDecisionReason?: string;
+        updatedInput?: unknown;
+    };
+    [key: string]: unknown;
+}
+import type { InstallOptions, InstallResult } from "./lib/installer.js";
+/** Install a hook scoped to the current project (.claude/settings.json) */
+export declare function installHookForProject(name: string, options?: Omit<InstallOptions, "scope">): InstallResult;
+/** Install multiple hooks scoped to the current project */
+export declare function installHooksForProject(names: string[], options?: Omit<InstallOptions, "scope">): InstallResult[];
+/** List all hooks registered for the current project */
+export declare function listProjectHooks(): string[];
+/** Remove a hook from the current project */
+export declare function removeProjectHook(name: string): boolean;
+export interface RunHookOptions {
+    /** Agent profile ID to inject into hook input */
+    profile?: string;
+    /** Timeout in milliseconds (default: 10000) */
+    timeout?: number;
+}
+export interface RunHookResult {
+    output: HookOutput;
+    stderr: string;
+    exitCode: number;
+}
+/**
+ * Programmatically execute a hook with the given input.
+ * Spawns the hook's src/hook.ts via bun, passes input as stdin JSON,
+ * and returns the parsed stdout JSON.
+ */
+export declare function runHook(name: string, input: HookInput, options?: RunHookOptions): Promise<RunHookResult>;
+export { createProfile, getProfile, listProfiles, updateProfile, deleteProfile, touchProfile, getProfilesDir, exportProfiles, importProfiles, type AgentProfile, type CreateProfileInput, } from "./lib/profiles.js";
+export { HOOKS_STORAGE_ENV, HOOKS_STORAGE_FALLBACK_ENV, HOOKS_STORAGE_MODE_ENV, HOOKS_STORAGE_MODE_FALLBACK_ENV, HOOKS_STORAGE_TABLES, STORAGE_DATABASE_ENV, STORAGE_MODE_ENV, STORAGE_TABLES, getStorageDatabaseEnv, getStorageDatabaseEnvName, getStorageDatabaseUrl, getStorageMode, getStoragePg, getStorageStatus, getSyncMetaAll, parseStorageTables, resolveTables, runStorageMigrations, storagePull, storagePush, storageSync, } from "./storage.js";
+export type { StorageEnv, StorageMode, StorageStatus, SyncMeta, SyncResult } from "./storage.js";