@premierstudio/ai-hooks 1.0.4

package/dist/adapters/index.d.ts

@@ -0,0 +1,2 @@
+export { B as BaseAdapter, r as registry } from '../index-bRA_mZA5.js';
+import '../hooks-CMnWrmJU.js';

package/dist/adapters/index.js

@@ -0,0 +1,122 @@
+import { existsSync } from 'fs';
+import { mkdir, writeFile, readFile, rm } from 'fs/promises';
+import { resolve, dirname } from 'path';
+
+// src/adapters/registry.ts
+var AdapterRegistry = class {
+  adapters = /* @__PURE__ */ new Map();
+  factories = /* @__PURE__ */ new Map();
+  /**
+   * Register an adapter instance.
+   */
+  register(adapter) {
+    this.adapters.set(adapter.id, adapter);
+  }
+  /**
+   * Register an adapter factory for lazy instantiation.
+   */
+  registerFactory(id, factory) {
+    this.factories.set(id, factory);
+  }
+  /**
+   * Get a registered adapter by ID.
+   */
+  get(id) {
+    const existing = this.adapters.get(id);
+    if (existing) return existing;
+    const factory = this.factories.get(id);
+    if (factory) {
+      const adapter = factory();
+      this.adapters.set(id, adapter);
+      return adapter;
+    }
+    return void 0;
+  }
+  /**
+   * Get all registered adapter IDs.
+   */
+  list() {
+    return [.../* @__PURE__ */ new Set([...this.adapters.keys(), ...this.factories.keys()])];
+  }
+  /**
+   * Detect which tools are available in the current environment.
+   * Returns adapters that successfully detect their tool.
+   */
+  async detectAll() {
+    const detected = [];
+    for (const id of this.list()) {
+      const adapter = this.get(id);
+      if (adapter) {
+        try {
+          const found = await adapter.detect();
+          if (found) {
+            detected.push(adapter);
+          }
+        } catch {
+        }
+      }
+    }
+    return detected;
+  }
+  /**
+   * Clear the registry. Useful for testing.
+   */
+  clear() {
+    this.adapters.clear();
+    this.factories.clear();
+  }
+};
+var registry = new AdapterRegistry();
+var BaseAdapter = class {
+  /**
+   * Default install: write generated configs to disk.
+   */
+  async install(configs) {
+    for (const config of configs) {
+      const fullPath = resolve(process.cwd(), config.path);
+      await mkdir(dirname(fullPath), { recursive: true });
+      await writeFile(fullPath, config.content, "utf-8");
+    }
+  }
+  /**
+   * Default uninstall: remove generated config files.
+   */
+  async uninstall() {
+  }
+  // ── Utility Methods ───────────────────────────────────────
+  async fileExists(path) {
+    return existsSync(resolve(process.cwd(), path));
+  }
+  async readJsonFile(path) {
+    const fullPath = resolve(process.cwd(), path);
+    if (!existsSync(fullPath)) return null;
+    const content = await readFile(fullPath, "utf-8");
+    return JSON.parse(content);
+  }
+  async writeJsonFile(path, data) {
+    const fullPath = resolve(process.cwd(), path);
+    await mkdir(dirname(fullPath), { recursive: true });
+    await writeFile(fullPath, JSON.stringify(data, null, 2) + "\n", "utf-8");
+  }
+  async removeFile(path) {
+    const fullPath = resolve(process.cwd(), path);
+    if (existsSync(fullPath)) {
+      await rm(fullPath);
+    }
+  }
+  /**
+   * Check if a CLI command exists on PATH.
+   */
+  async commandExists(command) {
+    const { exec } = await import('child_process');
+    return new Promise((resolve2) => {
+      exec(`which ${command}`, (error) => {
+        resolve2(!error);
+      });
+    });
+  }
+};
+
+export { BaseAdapter, registry };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/adapters/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/adapters/registry.ts","../../src/adapters/base.ts"],"names":["resolve"],"mappings":"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","file":"index.js","sourcesContent":["import type { Adapter, AdapterFactory } from \"../types/index.js\";\n\n/**\n * Global adapter registry.\n * Adapters register themselves when imported, or can be manually added.\n */\nclass AdapterRegistry {\n  private adapters: Map<string, Adapter> = new Map();\n  private factories: Map<string, AdapterFactory> = new Map();\n\n  /**\n   * Register an adapter instance.\n   */\n  register(adapter: Adapter): void {\n    this.adapters.set(adapter.id, adapter);\n  }\n\n  /**\n   * Register an adapter factory for lazy instantiation.\n   */\n  registerFactory(id: string, factory: AdapterFactory): void {\n    this.factories.set(id, factory);\n  }\n\n  /**\n   * Get a registered adapter by ID.\n   */\n  get(id: string): Adapter | undefined {\n    const existing = this.adapters.get(id);\n    if (existing) return existing;\n\n    // Try factory\n    const factory = this.factories.get(id);\n    if (factory) {\n      const adapter = factory();\n      this.adapters.set(id, adapter);\n      return adapter;\n    }\n\n    return undefined;\n  }\n\n  /**\n   * Get all registered adapter IDs.\n   */\n  list(): string[] {\n    return [...new Set([...this.adapters.keys(), ...this.factories.keys()])];\n  }\n\n  /**\n   * Detect which tools are available in the current environment.\n   * Returns adapters that successfully detect their tool.\n   */\n  async detectAll(): Promise<Adapter[]> {\n    const detected: Adapter[] = [];\n\n    for (const id of this.list()) {\n      const adapter = this.get(id);\n      if (adapter) {\n        try {\n          const found = await adapter.detect();\n          if (found) {\n            detected.push(adapter);\n          }\n        } catch {\n          // Detection failed, skip this adapter\n        }\n      }\n    }\n\n    return detected;\n  }\n\n  /**\n   * Clear the registry. Useful for testing.\n   */\n  clear(): void {\n    this.adapters.clear();\n    this.factories.clear();\n  }\n}\n\nexport const registry = new AdapterRegistry();\n","import { existsSync } from \"node:fs\";\nimport { readFile, writeFile, mkdir, rm } from \"node:fs/promises\";\nimport { dirname, resolve } from \"node:path\";\nimport type {\n  Adapter,\n  AdapterCapabilities,\n  GeneratedConfig,\n  HookDefinition,\n  HookEventType,\n} from \"../types/index.js\";\n\n/**\n * Base adapter class with shared utilities.\n * Tool-specific adapters extend this and implement the abstract methods.\n */\nexport abstract class BaseAdapter implements Adapter {\n  abstract readonly id: string;\n  abstract readonly name: string;\n  abstract readonly version: string;\n  abstract readonly capabilities: AdapterCapabilities;\n\n  abstract detect(): Promise<boolean>;\n  abstract generate(hooks: HookDefinition[]): Promise<GeneratedConfig[]>;\n  abstract mapEvent(event: HookEventType): string[];\n  abstract mapNativeEvent(nativeEvent: string): HookEventType[];\n\n  /**\n   * Default install: write generated configs to disk.\n   */\n  async install(configs: GeneratedConfig[]): Promise<void> {\n    for (const config of configs) {\n      const fullPath = resolve(process.cwd(), config.path);\n      await mkdir(dirname(fullPath), { recursive: true });\n      await writeFile(fullPath, config.content, \"utf-8\");\n    }\n  }\n\n  /**\n   * Default uninstall: remove generated config files.\n   */\n  async uninstall(): Promise<void> {\n    // Subclasses should override with specific file paths\n  }\n\n  // ── Utility Methods ───────────────────────────────────────\n\n  protected async fileExists(path: string): Promise<boolean> {\n    return existsSync(resolve(process.cwd(), path));\n  }\n\n  protected async readJsonFile<T>(path: string): Promise<T | null> {\n    const fullPath = resolve(process.cwd(), path);\n    if (!existsSync(fullPath)) return null;\n    const content = await readFile(fullPath, \"utf-8\");\n    return JSON.parse(content) as T;\n  }\n\n  protected async writeJsonFile(path: string, data: unknown): Promise<void> {\n    const fullPath = resolve(process.cwd(), path);\n    await mkdir(dirname(fullPath), { recursive: true });\n    await writeFile(fullPath, JSON.stringify(data, null, 2) + \"\\n\", \"utf-8\");\n  }\n\n  protected async removeFile(path: string): Promise<void> {\n    const fullPath = resolve(process.cwd(), path);\n    if (existsSync(fullPath)) {\n      await rm(fullPath);\n    }\n  }\n\n  /**\n   * Check if a CLI command exists on PATH.\n   */\n  protected async commandExists(command: string): Promise<boolean> {\n    const { exec } = await import(\"node:child_process\");\n    return new Promise((resolve) => {\n      exec(`which ${command}`, (error) => {\n        resolve(!error);\n      });\n    });\n  }\n}\n"]}

package/dist/hooks/index.d.ts

@@ -0,0 +1,27 @@
+import { H as HookDefinition } from '../hooks-CMnWrmJU.js';
+
+/**
+ * Built-in hook: Block dangerous shell commands.
+ * Prevents rm -rf /, drop database, and other destructive patterns.
+ */
+declare const blockDangerousCommands: HookDefinition;
+/**
+ * Built-in hook: Scan for secrets in file writes.
+ * Detects API keys, tokens, and credentials being written to files.
+ */
+declare const scanSecrets: HookDefinition;
+/**
+ * Built-in hook: Protect gitignored files from being read.
+ */
+declare const protectGitignored: HookDefinition;
+/**
+ * Built-in hook: Log all shell commands (after phase).
+ */
+declare const auditShellCommands: HookDefinition;
+/**
+ * All built-in hooks as an array.
+ * Use with `extends` in defineConfig to include defaults.
+ */
+declare const builtinHooks: HookDefinition[];
+
+export { auditShellCommands, blockDangerousCommands, builtinHooks, protectGitignored, scanSecrets };

package/dist/hooks/index.js

@@ -0,0 +1,155 @@
+// src/config/define.ts
+function hook(phase, events, handler) {
+  return new HookBuilderChain(phase, events, handler);
+}
+var HookBuilderChain = class {
+  constructor(phase, events, handler) {
+    this.phase = phase;
+    this.events = events;
+    this.handler = handler;
+    this._id = `hook-${events.join("-")}-${Date.now()}`;
+    this._name = `Hook for ${events.join(", ")}`;
+  }
+  _id;
+  _name;
+  _description;
+  _priority;
+  _filter;
+  _enabled;
+  id(id) {
+    this._id = id;
+    return this;
+  }
+  name(name) {
+    this._name = name;
+    return this;
+  }
+  description(desc) {
+    this._description = desc;
+    return this;
+  }
+  priority(p) {
+    this._priority = p;
+    return this;
+  }
+  filter(fn) {
+    this._filter = fn;
+    return this;
+  }
+  enabled(e) {
+    this._enabled = e;
+    return this;
+  }
+  build() {
+    return {
+      id: this._id,
+      name: this._name,
+      description: this._description,
+      events: this.events,
+      handler: this.handler,
+      phase: this.phase,
+      priority: this._priority,
+      filter: this._filter,
+      enabled: this._enabled
+    };
+  }
+};
+
+// src/hooks/builtin.ts
+var blockDangerousCommands = hook("before", ["shell:before"], async (ctx, next) => {
+  const command = ctx.event.command;
+  const dangerous = DANGEROUS_PATTERNS.find((p) => p.pattern.test(command));
+  if (dangerous) {
+    ctx.results.push({
+      blocked: true,
+      reason: `Blocked dangerous command: ${dangerous.description}`
+    });
+    return;
+  }
+  await next();
+}).id("ai-hooks:block-dangerous-commands").name("Block Dangerous Commands").description("Prevents destructive shell commands like rm -rf /, drop database, etc.").priority(1).build();
+var DANGEROUS_PATTERNS = [
+  { pattern: /rm\s+(-[a-zA-Z]*f[a-zA-Z]*\s+)?\/\s*$/, description: "rm -rf /" },
+  { pattern: /rm\s+-[a-zA-Z]*f[a-zA-Z]*\s+~\/?\s*$/, description: "rm -rf ~" },
+  { pattern: /mkfs\./, description: "filesystem format" },
+  { pattern: /dd\s+.*of=\/dev\/[sh]d/, description: "disk overwrite" },
+  { pattern: /:\(\)\s*\{\s*:\|:&\s*\}\s*;:/, description: "fork bomb" },
+  { pattern: />\s*\/dev\/[sh]d/, description: "device overwrite" },
+  { pattern: /chmod\s+(-R\s+)?777\s+\//, description: "chmod 777 /" },
+  { pattern: /DROP\s+DATABASE/i, description: "DROP DATABASE" },
+  { pattern: /DROP\s+TABLE/i, description: "DROP TABLE" },
+  { pattern: /TRUNCATE\s+TABLE/i, description: "TRUNCATE TABLE" }
+];
+var scanSecrets = hook("before", ["file:write", "file:edit"], async (ctx, next) => {
+  const content = ctx.event.type === "file:write" ? ctx.event.content : ctx.event.newContent;
+  const found = SECRET_PATTERNS.find((p) => p.pattern.test(content));
+  if (found) {
+    ctx.results.push({
+      blocked: true,
+      reason: `Potential secret detected: ${found.description}. Use environment variables instead.`
+    });
+    return;
+  }
+  await next();
+}).id("ai-hooks:scan-secrets").name("Scan for Secrets").description("Prevents hardcoded API keys, tokens, and credentials in file writes.").priority(2).build();
+var SECRET_PATTERNS = [
+  { pattern: /(?:api[_-]?key|apikey)\s*[:=]\s*['"][a-zA-Z0-9]{20,}['"]/i, description: "API key" },
+  {
+    pattern: /(?:secret|token|password|passwd|pwd)\s*[:=]\s*['"][^'"]{8,}['"]/i,
+    description: "Secret/token/password"
+  },
+  { pattern: /-----BEGIN (?:RSA |EC |DSA )?PRIVATE KEY-----/, description: "Private key" },
+  { pattern: /ghp_[a-zA-Z0-9]{36}/, description: "GitHub personal access token" },
+  { pattern: /sk-[a-zA-Z0-9]{20,}/, description: "OpenAI/Stripe secret key" },
+  { pattern: /AKIA[0-9A-Z]{16}/, description: "AWS access key ID" },
+  { pattern: /xox[bpors]-[a-zA-Z0-9-]{10,}/, description: "Slack token" }
+];
+var protectGitignored = hook("before", ["file:write"], async (ctx, next) => {
+  const path = ctx.event.path;
+  const sensitive = SENSITIVE_FILES.some((f) => path.endsWith(f));
+  if (sensitive) {
+    ctx.results.push({
+      blocked: true,
+      reason: `Cannot write to sensitive file: ${path}. This file should be managed manually.`
+    });
+    return;
+  }
+  await next();
+}).id("ai-hooks:protect-sensitive-files").name("Protect Sensitive Files").description("Prevents AI tools from overwriting .env, credentials, and other sensitive files.").priority(3).build();
+var SENSITIVE_FILES = [
+  ".env",
+  ".env.local",
+  ".env.production",
+  "credentials.json",
+  "service-account.json",
+  "id_rsa",
+  "id_ed25519",
+  ".npmrc",
+  ".pypirc"
+];
+var auditShellCommands = hook("after", ["shell:after"], async (ctx, next) => {
+  const { command, exitCode, duration } = ctx.event;
+  ctx.results.push({
+    data: {
+      audit: {
+        type: "shell",
+        command,
+        exitCode,
+        duration,
+        timestamp: ctx.event.timestamp,
+        tool: ctx.tool.name
+      }
+    }
+  });
+  await next();
+}).id("ai-hooks:audit-shell").name("Audit Shell Commands").description("Records all shell command executions for audit trail.").priority(999).build();
+var builtinHooks = [
+  blockDangerousCommands,
+  scanSecrets,
+  protectGitignored,
+  auditShellCommands
+];
+
+export { auditShellCommands, blockDangerousCommands, builtinHooks, protectGitignored, scanSecrets };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/hooks/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/config/define.ts","../../src/hooks/builtin.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["import type {\n  AiHooksConfig,\n  HookDefinition,\n  HookEventType,\n  HookContext,\n  EventOf,\n} from \"../types/index.js\";\n\n/**\n * Define an ai-hooks configuration.\n * Use this as the default export of your `ai-hooks.config.ts`.\n *\n * @example\n * ```ts\n * import { defineConfig, hook } from \"@premierstudio/ai-hooks\";\n *\n * export default defineConfig({\n *   hooks: [\n *     hook(\"before\", [\"shell:before\"], async (ctx, next) => {\n *       if (ctx.event.command.includes(\"rm -rf /\")) {\n *         ctx.results.push({ blocked: true, reason: \"Dangerous command\" });\n *         return;\n *       }\n *       await next();\n *     }).id(\"block-dangerous\").name(\"Block Dangerous Commands\").build(),\n *   ],\n * });\n * ```\n */\nexport function defineConfig(config: AiHooksConfig): AiHooksConfig {\n  return config;\n}\n\n/**\n * Fluent builder for creating hook definitions.\n * The generic parameter provides type-safe access to event properties\n * inside the handler, while the output is a non-generic HookDefinition\n * for collection compatibility.\n *\n * @example\n * ```ts\n * hook(\"before\", [\"file:write\", \"file:edit\"], async (ctx, next) => {\n *   // validate file changes\n *   await next();\n * })\n *   .id(\"validate-writes\")\n *   .name(\"Validate File Writes\")\n *   .priority(10)\n *   .build()\n * ```\n */\nexport function hook<T extends HookEventType>(\n  phase: \"before\",\n  events: T[],\n  handler: (ctx: HookContext<T>, next: () => Promise<void>) => Promise<void> | void,\n): HookBuilderChain<T>;\nexport function hook<T extends HookEventType>(\n  phase: \"after\",\n  events: T[],\n  handler: (ctx: HookContext<T>, next: () => Promise<void>) => Promise<void> | void,\n): HookBuilderChain<T>;\nexport function hook<T extends HookEventType>(\n  phase: \"before\" | \"after\",\n  events: T[],\n  handler: (ctx: HookContext<T>, next: () => Promise<void>) => Promise<void> | void,\n): HookBuilderChain<T> {\n  return new HookBuilderChain(phase, events, handler);\n}\n\nclass HookBuilderChain<T extends HookEventType> {\n  private _id: string;\n  private _name: string;\n  private _description?: string;\n  private _priority?: number;\n  private _filter?: (event: EventOf<T>) => boolean;\n  private _enabled?: boolean;\n\n  constructor(\n    private phase: \"before\" | \"after\",\n    private events: T[],\n    private handler: (ctx: HookContext<T>, next: () => Promise<void>) => Promise<void> | void,\n  ) {\n    this._id = `hook-${events.join(\"-\")}-${Date.now()}`;\n    this._name = `Hook for ${events.join(\", \")}`;\n  }\n\n  id(id: string): this {\n    this._id = id;\n    return this;\n  }\n\n  name(name: string): this {\n    this._name = name;\n    return this;\n  }\n\n  description(desc: string): this {\n    this._description = desc;\n    return this;\n  }\n\n  priority(p: number): this {\n    this._priority = p;\n    return this;\n  }\n\n  filter(fn: (event: EventOf<T>) => boolean): this {\n    this._filter = fn;\n    return this;\n  }\n\n  enabled(e: boolean): this {\n    this._enabled = e;\n    return this;\n  }\n\n  build(): HookDefinition {\n    // The handler/filter are widened from their narrow generic types to\n    // the base HookContext/HookEvent types. This is runtime-safe because\n    // the handler only accesses properties of the specific event type\n    // it was designed for, which are always present on the actual event.\n    return {\n      id: this._id,\n      name: this._name,\n      description: this._description,\n      events: this.events,\n      handler: this.handler as unknown as HookDefinition[\"handler\"],\n      phase: this.phase,\n      priority: this._priority,\n      filter: this._filter as unknown as HookDefinition[\"filter\"],\n      enabled: this._enabled,\n    };\n  }\n}\n","import { hook } from \"../config/define.js\";\nimport type { HookDefinition } from \"../types/index.js\";\n\n/**\n * Built-in hook: Block dangerous shell commands.\n * Prevents rm -rf /, drop database, and other destructive patterns.\n */\nexport const blockDangerousCommands = hook(\"before\", [\"shell:before\"], async (ctx, next) => {\n  const command = ctx.event.command;\n  const dangerous = DANGEROUS_PATTERNS.find((p) => p.pattern.test(command));\n\n  if (dangerous) {\n    ctx.results.push({\n      blocked: true,\n      reason: `Blocked dangerous command: ${dangerous.description}`,\n    });\n    return;\n  }\n\n  await next();\n})\n  .id(\"ai-hooks:block-dangerous-commands\")\n  .name(\"Block Dangerous Commands\")\n  .description(\"Prevents destructive shell commands like rm -rf /, drop database, etc.\")\n  .priority(1)\n  .build();\n\nconst DANGEROUS_PATTERNS = [\n  { pattern: /rm\\s+(-[a-zA-Z]*f[a-zA-Z]*\\s+)?\\/\\s*$/, description: \"rm -rf /\" },\n  { pattern: /rm\\s+-[a-zA-Z]*f[a-zA-Z]*\\s+~\\/?\\s*$/, description: \"rm -rf ~\" },\n  { pattern: /mkfs\\./, description: \"filesystem format\" },\n  { pattern: /dd\\s+.*of=\\/dev\\/[sh]d/, description: \"disk overwrite\" },\n  { pattern: /:\\(\\)\\s*\\{\\s*:\\|:&\\s*\\}\\s*;:/, description: \"fork bomb\" },\n  { pattern: />\\s*\\/dev\\/[sh]d/, description: \"device overwrite\" },\n  { pattern: /chmod\\s+(-R\\s+)?777\\s+\\//, description: \"chmod 777 /\" },\n  { pattern: /DROP\\s+DATABASE/i, description: \"DROP DATABASE\" },\n  { pattern: /DROP\\s+TABLE/i, description: \"DROP TABLE\" },\n  { pattern: /TRUNCATE\\s+TABLE/i, description: \"TRUNCATE TABLE\" },\n];\n\n/**\n * Built-in hook: Scan for secrets in file writes.\n * Detects API keys, tokens, and credentials being written to files.\n */\nexport const scanSecrets = hook(\"before\", [\"file:write\", \"file:edit\"], async (ctx, next) => {\n  const content = ctx.event.type === \"file:write\" ? ctx.event.content : ctx.event.newContent;\n\n  const found = SECRET_PATTERNS.find((p) => p.pattern.test(content));\n\n  if (found) {\n    ctx.results.push({\n      blocked: true,\n      reason: `Potential secret detected: ${found.description}. Use environment variables instead.`,\n    });\n    return;\n  }\n\n  await next();\n})\n  .id(\"ai-hooks:scan-secrets\")\n  .name(\"Scan for Secrets\")\n  .description(\"Prevents hardcoded API keys, tokens, and credentials in file writes.\")\n  .priority(2)\n  .build();\n\nconst SECRET_PATTERNS = [\n  { pattern: /(?:api[_-]?key|apikey)\\s*[:=]\\s*['\"][a-zA-Z0-9]{20,}['\"]/i, description: \"API key\" },\n  {\n    pattern: /(?:secret|token|password|passwd|pwd)\\s*[:=]\\s*['\"][^'\"]{8,}['\"]/i,\n    description: \"Secret/token/password\",\n  },\n  { pattern: /-----BEGIN (?:RSA |EC |DSA )?PRIVATE KEY-----/, description: \"Private key\" },\n  { pattern: /ghp_[a-zA-Z0-9]{36}/, description: \"GitHub personal access token\" },\n  { pattern: /sk-[a-zA-Z0-9]{20,}/, description: \"OpenAI/Stripe secret key\" },\n  { pattern: /AKIA[0-9A-Z]{16}/, description: \"AWS access key ID\" },\n  { pattern: /xox[bpors]-[a-zA-Z0-9-]{10,}/, description: \"Slack token\" },\n];\n\n/**\n * Built-in hook: Protect gitignored files from being read.\n */\nexport const protectGitignored = hook(\"before\", [\"file:write\"], async (ctx, next) => {\n  const path = ctx.event.path;\n\n  // Block writes to common sensitive files\n  const sensitive = SENSITIVE_FILES.some((f) => path.endsWith(f));\n  if (sensitive) {\n    ctx.results.push({\n      blocked: true,\n      reason: `Cannot write to sensitive file: ${path}. This file should be managed manually.`,\n    });\n    return;\n  }\n\n  await next();\n})\n  .id(\"ai-hooks:protect-sensitive-files\")\n  .name(\"Protect Sensitive Files\")\n  .description(\"Prevents AI tools from overwriting .env, credentials, and other sensitive files.\")\n  .priority(3)\n  .build();\n\nconst SENSITIVE_FILES = [\n  \".env\",\n  \".env.local\",\n  \".env.production\",\n  \"credentials.json\",\n  \"service-account.json\",\n  \"id_rsa\",\n  \"id_ed25519\",\n  \".npmrc\",\n  \".pypirc\",\n];\n\n/**\n * Built-in hook: Log all shell commands (after phase).\n */\nexport const auditShellCommands = hook(\"after\", [\"shell:after\"], async (ctx, next) => {\n  const { command, exitCode, duration } = ctx.event;\n  ctx.results.push({\n    data: {\n      audit: {\n        type: \"shell\",\n        command,\n        exitCode,\n        duration,\n        timestamp: ctx.event.timestamp,\n        tool: ctx.tool.name,\n      },\n    },\n  });\n  await next();\n})\n  .id(\"ai-hooks:audit-shell\")\n  .name(\"Audit Shell Commands\")\n  .description(\"Records all shell command executions for audit trail.\")\n  .priority(999)\n  .build();\n\n/**\n * All built-in hooks as an array.\n * Use with `extends` in defineConfig to include defaults.\n */\nexport const builtinHooks: HookDefinition[] = [\n  blockDangerousCommands,\n  scanSecrets,\n  protectGitignored,\n  auditShellCommands,\n];\n"]}

package/dist/hooks-CMnWrmJU.d.ts

@@ -0,0 +1,212 @@
+/**
+ * Universal event types that map across all AI coding tools.
+ *
+ * Each tool adapter translates these universal events to/from
+ * the tool's native event system.
+ */
+type SessionStartEvent = {
+    type: "session:start";
+    tool: string;
+    version: string;
+    workingDirectory: string;
+    timestamp: number;
+    metadata: Record<string, unknown>;
+};
+type SessionEndEvent = {
+    type: "session:end";
+    tool: string;
+    duration: number;
+    timestamp: number;
+    metadata: Record<string, unknown>;
+};
+type PromptSubmitEvent = {
+    type: "prompt:submit";
+    prompt: string;
+    timestamp: number;
+    metadata: Record<string, unknown>;
+};
+type PromptResponseEvent = {
+    type: "prompt:response";
+    response: string;
+    model: string;
+    tokens: {
+        input: number;
+        output: number;
+    };
+    timestamp: number;
+    metadata: Record<string, unknown>;
+};
+type ToolCallEvent = {
+    type: "tool:before";
+    toolName: string;
+    input: Record<string, unknown>;
+    timestamp: number;
+    metadata: Record<string, unknown>;
+};
+type ToolResultEvent = {
+    type: "tool:after";
+    toolName: string;
+    input: Record<string, unknown>;
+    output: unknown;
+    duration: number;
+    timestamp: number;
+    metadata: Record<string, unknown>;
+};
+type FileReadEvent = {
+    type: "file:read";
+    path: string;
+    timestamp: number;
+    metadata: Record<string, unknown>;
+};
+type FileWriteEvent = {
+    type: "file:write";
+    path: string;
+    content: string;
+    timestamp: number;
+    metadata: Record<string, unknown>;
+};
+type FileEditEvent = {
+    type: "file:edit";
+    path: string;
+    oldContent: string;
+    newContent: string;
+    timestamp: number;
+    metadata: Record<string, unknown>;
+};
+type FileDeleteEvent = {
+    type: "file:delete";
+    path: string;
+    timestamp: number;
+    metadata: Record<string, unknown>;
+};
+type ShellBeforeEvent = {
+    type: "shell:before";
+    command: string;
+    cwd: string;
+    timestamp: number;
+    metadata: Record<string, unknown>;
+};
+type ShellAfterEvent = {
+    type: "shell:after";
+    command: string;
+    cwd: string;
+    exitCode: number;
+    stdout: string;
+    stderr: string;
+    duration: number;
+    timestamp: number;
+    metadata: Record<string, unknown>;
+};
+type McpCallEvent = {
+    type: "mcp:before";
+    server: string;
+    method: string;
+    params: Record<string, unknown>;
+    timestamp: number;
+    metadata: Record<string, unknown>;
+};
+type McpResultEvent = {
+    type: "mcp:after";
+    server: string;
+    method: string;
+    params: Record<string, unknown>;
+    result: unknown;
+    duration: number;
+    timestamp: number;
+    metadata: Record<string, unknown>;
+};
+type NotificationEvent = {
+    type: "notification";
+    level: "info" | "warn" | "error";
+    message: string;
+    timestamp: number;
+    metadata: Record<string, unknown>;
+};
+type BeforeEvent = SessionStartEvent | PromptSubmitEvent | ToolCallEvent | FileWriteEvent | FileEditEvent | FileDeleteEvent | ShellBeforeEvent | McpCallEvent;
+type AfterEvent = SessionEndEvent | PromptResponseEvent | ToolResultEvent | FileReadEvent | ShellAfterEvent | McpResultEvent | NotificationEvent;
+type HookEvent = BeforeEvent | AfterEvent;
+type HookEventType = HookEvent["type"];
+/**
+ * Extract the event shape for a given event type string.
+ */
+type EventOf<T extends HookEventType> = Extract<HookEvent, {
+    type: T;
+}>;
+
+/**
+ * Result of a "before" hook. Controls whether the event proceeds.
+ */
+type HookResult = {
+    /** If true, the event is blocked and won't proceed to the tool. */
+    blocked?: boolean;
+    /** Reason for blocking (shown to the user/tool). */
+    reason?: string;
+    /** Modified event data to pass forward (mutation). */
+    mutated?: Partial<HookEvent>;
+    /** Arbitrary data to attach to the hook context. */
+    data?: Record<string, unknown>;
+};
+/**
+ * The context object passed to every hook function.
+ * Inspired by Express.js req/res pattern but adapted for AI tools.
+ */
+type HookContext<T extends HookEventType = HookEventType> = {
+    /** The event that triggered this hook. */
+    event: EventOf<T>;
+    /** The AI tool that emitted this event. */
+    tool: {
+        name: string;
+        version: string;
+    };
+    /** Working directory where the tool is running. */
+    cwd: string;
+    /** Shared state bag for passing data between hooks in a chain. */
+    state: Map<string, unknown>;
+    /** Accumulated results from previous hooks in the chain. */
+    results: HookResult[];
+    /** Timestamp of when the hook chain started. */
+    startedAt: number;
+};
+/**
+ * A "before" hook function. Runs before the event is processed.
+ * Can block, mutate, or pass through.
+ */
+type BeforeHookFn<T extends HookEventType = HookEventType> = (ctx: HookContext<T>, next: () => Promise<void>) => Promise<void> | void;
+/**
+ * An "after" hook function. Runs after the event is processed.
+ * Cannot block (event already happened), but can observe and react.
+ */
+type AfterHookFn<T extends HookEventType = HookEventType> = (ctx: HookContext<T>, next: () => Promise<void>) => Promise<void> | void;
+/**
+ * A hook definition with metadata.
+ *
+ * The generic parameter provides type safety when creating hooks
+ * for specific events. For collections/storage, use the non-generic
+ * default which accepts any event type.
+ */
+type HookDefinition = {
+    /** Unique identifier for this hook. */
+    id: string;
+    /** Human-readable name. */
+    name: string;
+    /** Description of what this hook does. */
+    description?: string;
+    /** Which event types this hook listens to. */
+    events: HookEventType[];
+    /** The hook function. Takes the widest context; narrowing happens at creation time via hook(). */
+    handler: (ctx: HookContext, next: () => Promise<void>) => Promise<void> | void;
+    /** Priority (lower = runs first). Default: 100. */
+    priority?: number;
+    /** Whether this hook runs "before" or "after" the event. */
+    phase: "before" | "after";
+    /** Optional filter to narrow when this hook runs. */
+    filter?: (event: HookEvent) => boolean;
+    /** Whether this hook is enabled. Default: true. */
+    enabled?: boolean;
+};
+/**
+ * Type guard: is this a "before" event type?
+ */
+declare function isBeforeEvent(event: HookEvent): event is BeforeEvent;
+
+export { type AfterEvent as A, type BeforeEvent as B, type EventOf as E, type FileDeleteEvent as F, type HookDefinition as H, type McpCallEvent as M, type NotificationEvent as N, type PromptResponseEvent as P, type SessionEndEvent as S, type ToolCallEvent as T, type HookEventType as a, type HookContext as b, type HookEvent as c, type HookResult as d, type AfterHookFn as e, type BeforeHookFn as f, type FileEditEvent as g, type FileReadEvent as h, type FileWriteEvent as i, type McpResultEvent as j, type PromptSubmitEvent as k, type SessionStartEvent as l, type ShellAfterEvent as m, type ShellBeforeEvent as n, type ToolResultEvent as o, isBeforeEvent as p };