dsh-hooks 0.2.2 → 0.3.0

package/examples/notify-webhook.mjs

@@ -0,0 +1,229 @@
+#!/usr/bin/env node
+/**
+ * Generic webhook notification for dsh-hooks — posts the hook context as
+ * one JSON document to any HTTP endpoint. Works with Slack incoming
+ * webhooks, Discord, Lark/DingTalk custom bots, ntfy, Bark, n8n, or any
+ * automation service that accepts a JSON POST.
+ *
+ * Reads the hook context from DSH_HOOK_* environment variables and POSTs
+ * `application/json`. Only present context fields are included, so the
+ * payload shape is stable and small.
+ *
+ * Required environment (set in the dsh process environment, NOT in config):
+ *   DSH_HOOKS_WEBHOOK_URL     target webhook URL
+ * …or pass it as the first flag: --url <url>
+ *
+ * Usage (from a dsh-hooks config):
+ *   - on: 'turn/end'
+ *     when: 'completed'
+ *     run: 'node examples/notify-webhook.mjs --url https://hooks.slack.com/services/T/B/…'
+ *   - on: 'tool/call'
+ *     run: 'node examples/notify-webhook.mjs'
+ *
+ * Optional flags:
+ *   --url <url>        webhook URL (overrides the environment variable)
+ *   --slack            post Slack-style `{ text }` instead of the full
+ *                      context document
+ *   --timeout <ms>     fetch timeout (default 10000)
+ *   -q                 quiet: suppress success output (hooks parse stdout)
+ *
+ * Zero npm dependencies: fetch is global in Node 18+.
+ * The module exports its helpers for testing; it only executes when invoked
+ * directly (node notify-webhook.mjs), not when imported.
+ */
+import { pathToFileURL } from 'node:url'
+
+/** Every DSH_HOOK_* variable this script understands, in payload order. */
+const CONTEXT_VARS = [
+  'DSH_HOOK_EVENT',
+  'DSH_HOOK_TIMESTAMP',
+  'DSH_HOOK_SESSION_ID',
+  'DSH_HOOK_SESSION_NAME',
+  'DSH_HOOK_CWD',
+  'DSH_HOOK_TURN',
+  'DSH_HOOK_STEP',
+  'DSH_HOOK_REASON',
+  'DSH_HOOK_TOOL',
+  'DSH_HOOK_CALL_ID',
+  'DSH_HOOK_TOOL_ARGS',
+  'DSH_HOOK_TOOL_ERROR',
+  'DSH_HOOK_SOURCE',
+  'DSH_HOOK_DURATION_MS',
+  'DSH_HOOK_STATUS',
+  'DSH_HOOK_ERROR',
+  'DSH_HOOK_CONTENT',
+  'DSH_HOOK_USAGE_INPUT_TOKENS',
+  'DSH_HOOK_USAGE_OUTPUT_TOKENS',
+  'DSH_HOOK_USAGE_CACHE_READ_TOKENS',
+  'DSH_HOOK_USAGE_CACHE_WRITE_TOKENS',
+  'DSH_HOOK_USAGE_REASONING_TOKENS',
+]
+
+/** Parse one context env var into a number, or undefined when absent/garbage. */
+function num(value) {
+  if (value === undefined || value === '') return undefined
+  const n = Number(value)
+  return Number.isFinite(n) ? n : undefined
+}
+
+/** Read the raw context: only the variables that are present and non-empty. */
+export function readEnv(env = process.env) {
+  const raw = {}
+  for (const name of CONTEXT_VARS) {
+    const value = env[name]
+    if (value !== undefined && value !== '') raw[name] = value
+  }
+  return raw
+}
+
+/** Group one raw env snapshot into a nested JSON payload. */
+export function buildPayload(raw) {
+  const payload = {}
+  const session = {}
+  if (raw.DSH_HOOK_SESSION_ID) session.id = raw.DSH_HOOK_SESSION_ID
+  if (raw.DSH_HOOK_SESSION_NAME) session.name = raw.DSH_HOOK_SESSION_NAME
+  if (raw.DSH_HOOK_CWD) session.cwd = raw.DSH_HOOK_CWD
+  if (Object.keys(session).length > 0) payload.session = session
+  if (raw.DSH_HOOK_EVENT) payload.event = raw.DSH_HOOK_EVENT
+  if (raw.DSH_HOOK_TIMESTAMP) payload.timestamp = raw.DSH_HOOK_TIMESTAMP
+  const turn = num(raw.DSH_HOOK_TURN)
+  const step = num(raw.DSH_HOOK_STEP)
+  const durationMs = num(raw.DSH_HOOK_DURATION_MS)
+  if (turn !== undefined) payload.turn = turn
+  if (step !== undefined) payload.step = step
+  if (durationMs !== undefined) payload.duration_ms = durationMs
+  if (raw.DSH_HOOK_REASON) payload.reason = raw.DSH_HOOK_REASON
+  if (raw.DSH_HOOK_TOOL) payload.tool = raw.DSH_HOOK_TOOL
+  if (raw.DSH_HOOK_CALL_ID) payload.call_id = raw.DSH_HOOK_CALL_ID
+  if (raw.DSH_HOOK_TOOL_ARGS) payload.tool_args = raw.DSH_HOOK_TOOL_ARGS
+  if (raw.DSH_HOOK_TOOL_ERROR) payload.tool_error = raw.DSH_HOOK_TOOL_ERROR
+  if (raw.DSH_HOOK_SOURCE) payload.source = raw.DSH_HOOK_SOURCE
+  if (raw.DSH_HOOK_STATUS) payload.status = raw.DSH_HOOK_STATUS
+  if (raw.DSH_HOOK_ERROR) payload.error = raw.DSH_HOOK_ERROR
+  if (raw.DSH_HOOK_CONTENT) payload.content = raw.DSH_HOOK_CONTENT
+  const usage = {}
+  const usageInput = num(raw.DSH_HOOK_USAGE_INPUT_TOKENS)
+  const usageOutput = num(raw.DSH_HOOK_USAGE_OUTPUT_TOKENS)
+  const usageCacheRead = num(raw.DSH_HOOK_USAGE_CACHE_READ_TOKENS)
+  const usageCacheWrite = num(raw.DSH_HOOK_USAGE_CACHE_WRITE_TOKENS)
+  const usageReasoning = num(raw.DSH_HOOK_USAGE_REASONING_TOKENS)
+  if (usageInput !== undefined) usage.input_tokens = usageInput
+  if (usageOutput !== undefined) usage.output_tokens = usageOutput
+  if (usageCacheRead !== undefined) usage.cache_read_tokens = usageCacheRead
+  if (usageCacheWrite !== undefined) usage.cache_write_tokens = usageCacheWrite
+  if (usageReasoning !== undefined) usage.reasoning_tokens = usageReasoning
+  if (Object.keys(usage).length > 0) payload.usage = usage
+  return payload
+}
+
+/** One-line summary for Slack-style `{ text }` payloads. */
+export function summarize(payload) {
+  const label = payload.session?.name || payload.session?.id || ''
+  const where = label ? ` · ${label}` : ''
+  switch (payload.event) {
+    case 'turn/end':
+      if (payload.reason === 'completed') return `✅ 任务已完成${where}（回合 #${payload.turn ?? '?'}）`
+      if (payload.error) return `❌ 任务失败${where}: ${payload.error.slice(0, 200)}`
+      return `⏸ 任务${payload.reason ? ` ${payload.reason}` : '结束'}${where}（回合 #${payload.turn ?? '?'}）`
+    case 'tool/call':
+      return `🔧 调用工具 ${payload.tool ?? ''}${where}`
+    case 'tool/result':
+      if (payload.tool_error) return `⚠️ 工具 ${payload.tool ?? ''} 失败${where}: ${payload.tool_error}`
+      return `✅ 工具 ${payload.tool ?? ''} 完成${where}`
+    case 'approval/asked':
+      return `⏳ 需要审批：工具 ${payload.tool ?? ''}${where}`
+    case 'user/message':
+      return `💬 新消息${where}${payload.content ? `：${payload.content.slice(0, 120)}` : ''}`
+    case 'session/title':
+      return `🏷 会话改名${where}: ${payload.session?.name ?? ''}`
+    case 'session/created':
+      return `✨ 会话开始${where}`
+    case 'session/disposed':
+      return `🏁 会话结束${where}`
+    default:
+      return `🔔 DSH ${payload.event ?? '事件'}${where}`
+  }
+}
+
+/** Parse the optional CLI flags. */
+export function parseArgs(args) {
+  const opts = { url: '', slack: false, timeoutMs: 10000, quiet: false }
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i]
+    if (a === '--url') opts.url = args[++i] ?? ''
+    else if (a === '--slack') opts.slack = true
+    else if (a === '--timeout') {
+      const n = Number(args[++i])
+      if (Number.isFinite(n) && n > 0) opts.timeoutMs = n
+    } else if (a === '-q') opts.quiet = true
+  }
+  return opts
+}
+
+/** POST one JSON body to the webhook with a timeout; one retry on transport failure. */
+export async function postJson(url, body, timeoutMs = 10000) {
+  const attempt = async () => {
+    const controller = new AbortController()
+    const timer = setTimeout(() => controller.abort(), timeoutMs)
+    try {
+      return await fetch(url, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify(body),
+        signal: controller.signal,
+      })
+    } finally {
+      clearTimeout(timer)
+    }
+  }
+  let response
+  try {
+    response = await attempt()
+  } catch (error) {
+    // One retry for transient transport failures (webhook endpoints often
+    // drop the first request when cold).
+    try {
+      response = await attempt()
+    } catch (retryError) {
+      const cause = retryError instanceof Error ? retryError.message : String(retryError)
+      throw new Error(`webhook 请求失败（重试后仍失败）: ${cause}`)
+    }
+  }
+  if (!response.ok) throw new Error(`webhook 响应 HTTP ${response.status}`)
+}
+
+/** Full pipeline for one hook event. Exported for tests and CLI use. */
+export async function run(env = process.env, args = []) {
+  const opts = parseArgs(args)
+  const url = opts.url || env.DSH_HOOKS_WEBHOOK_URL
+  if (!url) throw new Error('缺少 webhook URL：请设置 DSH_HOOKS_WEBHOOK_URL 或传 --url <url>')
+  const raw = readEnv(env)
+  if (!raw.DSH_HOOK_EVENT) throw new Error('缺少 DSH_HOOK_EVENT（请通过 dsh-hooks 触发，不要直接运行）')
+  const payload = buildPayload(raw)
+  const body = opts.slack ? { text: summarize(payload) } : payload
+  await postJson(url, body, opts.timeoutMs)
+  return body
+}
+
+function isDirectRun() {
+  try {
+    return process.argv[1] !== undefined && import.meta.url === pathToFileURL(process.argv[1]).href
+  } catch {
+    return false
+  }
+}
+
+if (isDirectRun()) {
+  run(process.env, process.argv.slice(2))
+    .then((body) => {
+      if (!parseArgs(process.argv.slice(2)).quiet) {
+        const text = JSON.stringify(body)
+        console.log(`已发送 webhook: ${text.length > 80 ? text.slice(0, 80) + '…' : text}`)
+      }
+      process.exit(0)
+    })
+    .catch((error) => {
+      console.warn(`[dsh-hooks/notify-webhook] ${error instanceof Error ? error.message : String(error)}`)
+      process.exit(1)
+    })
+}

package/lib/config.d.ts

@@ -1,10 +1,23 @@
 /** Hookable event kinds. v1 is emit-only: no waterfall/interception events. */
-export declare const HOOK_EVENTS: readonly ["turn/start", "turn/end", "approval/asked", "agent/created", "agent/disposed", "agent/error", "agent/status"];
+export declare const HOOK_EVENTS: readonly ['turn/start', 'turn/end', 'step/end', 'tool/call', 'tool/result', 'user/message', 'approval/asked', 'session/title', 'session/created', 'session/disposed', 'agent/created', 'agent/disposed', 'agent/error', 'agent/status'];
 export type HookEvent = (typeof HOOK_EVENTS)[number];
 /** `turn/end` reason kinds (from @deepseek-ai/dsh-session TurnEndReasonMap). */
-export declare const TURN_END_REASONS: readonly ["completed", "error", "aborted", "blocked", "max-tokens", "interrupted"];
+export declare const TURN_END_REASONS: readonly ['completed', 'error', 'aborted', 'blocked', 'max-tokens', 'interrupted'];
 export type TurnEndReasonKind = (typeof TURN_END_REASONS)[number];
-/** One declared hook: a matching event runs `run` through the platform shell. */
+/**
+ * Built-in notification: send the hook context through a channel declared
+ * in config, no external script required. Mutually exclusive with `run` —
+ * a hook declares exactly one of the two.
+ */
+export interface NotifySpec {
+    /** Channel to send through. */
+    channel: 'webhook' | 'desktop';
+    /** webhook: the target URL (falls back to the `DSH_HOOKS_WEBHOOK_URL` env var). */
+    url?: string;
+    /** webhook: post a Slack-style `{ text }` one-line summary instead of the full context document. */
+    slack?: boolean;
+}
+/** One declared hook: a matching event runs `run` (or sends `notify`). */
 export interface HookSpec {
     /** Event that triggers the hook. */
     on: HookEvent;
@@ -13,13 +26,48 @@ export interface HookSpec {
      * (`completed`, `error`, …). Ignored for other events.
      */
     when?: TurnEndReasonKind;
-    /** Command to spawn through the platform shell. */
-    run: string;
+    /**
+     * Optional field → regex filters: every declared regex must match the
+     * context's field value for the hook to run. Fields are `HookContext`
+     * keys (`tool`, `sessionName`, `sessionId`, `error`, `source`, `cwd`,
+     * `content`, …); a field absent from the context never matches.
+     */
+    match?: Record<string, RegExp>;
+    /**
+     * Command to spawn through the platform shell. Exactly one of `run` and
+     * `notify` must be declared.
+     */
+    run?: string;
+    /** Built-in notification channel. Exactly one of `run` and `notify` must be declared. */
+    notify?: NotifySpec | null;
+    /**
+     * How the context reaches the command. `env` (default) passes the
+     * `DSH_HOOK_*` variables only; `stdin` additionally writes the full
+     * context as one JSON document to the command's stdin.
+     */
+    input?: 'env' | 'stdin';
     /** Per-hook timeout in milliseconds. Defaults to 10000. */
     timeoutMs?: number;
+    /**
+     * Retry count for non-zero exit codes (default 0: fire-and-forget,
+     * never retried). Spawn failures and timeouts are never retried.
+     */
+    retries?: number;
+    /** Base delay between retries in milliseconds; doubles per attempt. Defaults to 500. */
+    retryDelayMs?: number;
+}
+/** Execution-history settings: in-memory ring buffer + optional JSONL log. */
+export interface HistoryConfig {
+    /** Persist records to disk. Defaults to true. */
+    enabled?: boolean;
+    /** JSONL file path. Defaults to ~/.dsh/dsh-hooks/history.jsonl (0600). */
+    path?: string;
+    /** In-memory ring buffer size. Defaults to 500. */
+    max?: number;
 }
 export interface Config {
     hooks?: HookSpec[];
+    history?: HistoryConfig | null;
 }
 export declare const Config: {
     (data?: Config | null): Config;

package/lib/config.js

@@ -3,7 +3,14 @@ import Schema from '@deepseek-ai/schemastery';
 export const HOOK_EVENTS = [
     'turn/start',
     'turn/end',
+    'step/end',
+    'tool/call',
+    'tool/result',
+    'user/message',
     'approval/asked',
+    'session/title',
+    'session/created',
+    'session/disposed',
     'agent/created',
     'agent/disposed',
     'agent/error',
@@ -24,11 +31,39 @@ export const TURN_END_REASONS = [
 // declaration self-contained.
 export const Config = Schema.object({
     hooks: Schema.array(Schema.object({
-        on: Schema.union([...HOOK_EVENTS]).description('触发事件：turn/start | turn/end | approval/asked | agent/created | agent/disposed | agent/error | agent/status'),
+        on: Schema.union([...HOOK_EVENTS]).description('触发事件：turn/start | turn/end | step/end | tool/call | tool/result | user/message | approval/asked | session/title | session/created | session/disposed | agent/created | agent/disposed | agent/error | agent/status'),
         when: Schema.union([...TURN_END_REASONS]).description('可选过滤：对 turn/end 匹配结束原因（completed/error/aborted/blocked/max-tokens/interrupted）；其他事件忽略该字段'),
-        run: Schema.string().required().description('触发时通过系统 shell 执行的命令'),
+        match: Schema.dict(Schema.regExp()).description('可选通用过滤：字段 → 正则，全部匹配才触发。字段为上下文键（tool/sessionName/sessionId/error/source/cwd/content/reason/…），上下文中不存在的字段视为不匹配'),
+        run: Schema.string().description('触发时通过系统 shell 执行的命令（与 notify 二选一）'),
+        notify: Schema.union([
+            Schema.object({
+                channel: Schema.union(['webhook', 'desktop'])
+                    .required()
+                    .description('通知渠道：webhook 发 HTTP JSON；desktop 发系统桌面通知'),
+                url: Schema.string().description('webhook 渠道的目标 URL（缺省时用环境变量 DSH_HOOKS_WEBHOOK_URL）'),
+                slack: Schema.boolean().default(false).description('webhook 渠道：改为发送 Slack 风格 { text } 单行摘要'),
+            }),
+            Schema.const(null),
+        ])
+            .default(null)
+            .description('内置通知（与 run 二选一）：配置驱动发送，无需外部脚本'),
+        input: Schema.union(['env', 'stdin'])
+            .default('env')
+            .description('上下文传递方式：env 只传 DSH_HOOK_* 环境变量（默认）；stdin 额外把完整上下文 JSON 写入命令标准输入'),
         timeoutMs: Schema.number().default(10000).description('单次执行超时（毫秒）'),
-    }).description('一个事件 → 命令的 hook 声明'))
+        retries: Schema.natural().default(0).description('非零退出码的重试次数（默认 0 不重试；spawn 失败与超时不重试）'),
+        retryDelayMs: Schema.natural().default(500).description('重试基础间隔（毫秒），每次翻倍'),
+    }).description('一个事件 → 命令/通知的 hook 声明'))
         .default([])
         .description('事件触发时执行的外部命令列表；按声明顺序触发'),
+    history: Schema.union([
+        Schema.object({
+            enabled: Schema.boolean().default(true).description('是否把执行历史持久化到磁盘（默认 true）'),
+            path: Schema.string().description('JSONL 文件路径（默认 ~/.dsh/dsh-hooks/history.jsonl，权限 0600）'),
+            max: Schema.natural().default(500).description('内存环形缓冲条数（默认 500）'),
+        }),
+        Schema.const(null),
+    ])
+        .default(null)
+        .description('hook 执行历史：内存环形缓冲 + 可选 JSONL 持久化日志（供 UI/调试使用，严格 best-effort）'),
 }).description('dsh-hooks 配置：声明式生命周期 hooks');

package/lib/context.d.ts

@@ -14,14 +14,28 @@ export interface HookContext {
     /** Absolute working directory of the session, when known. */
     cwd?: string;
     turn?: number;
+    /** Step number of the turn (step and tool events). */
+    step?: number;
     reason?: string;
     tool?: string;
     callId?: string;
+    /** Raw tool-call arguments JSON as the model produced it (tool/call). */
+    toolArgs?: string;
+    /** Tool failure identity (`name`/`code`) when a tool result errored. */
+    toolError?: string;
+    /** Producer source kind: user message source, title source, etc. */
+    source?: string;
     durationMs?: number;
     status?: string;
     error?: string;
-    /** Turn content snapshot, e.g. the turn's final assistant text. */
+    /** Event content snapshot: turn assistant text, tool result text, … */
     content?: string;
+    /** Aggregated token usage of the turn (turn/end), when reported. */
+    usageInputTokens?: number;
+    usageOutputTokens?: number;
+    usageCacheReadTokens?: number;
+    usageCacheWriteTokens?: number;
+    usageReasoningTokens?: number;
     timestamp: string;
 }
 export declare function toEnv(ctx: HookContext): Record<string, string>;

package/lib/context.js

@@ -13,12 +13,20 @@ export function toEnv(ctx) {
         env.DSH_HOOK_CWD = ctx.cwd;
     if (ctx.turn !== undefined)
         env.DSH_HOOK_TURN = String(ctx.turn);
+    if (ctx.step !== undefined)
+        env.DSH_HOOK_STEP = String(ctx.step);
     if (ctx.reason !== undefined)
         env.DSH_HOOK_REASON = ctx.reason;
     if (ctx.tool !== undefined)
         env.DSH_HOOK_TOOL = ctx.tool;
     if (ctx.callId !== undefined)
         env.DSH_HOOK_CALL_ID = ctx.callId;
+    if (ctx.toolArgs !== undefined)
+        env.DSH_HOOK_TOOL_ARGS = ctx.toolArgs;
+    if (ctx.toolError !== undefined)
+        env.DSH_HOOK_TOOL_ERROR = ctx.toolError;
+    if (ctx.source !== undefined)
+        env.DSH_HOOK_SOURCE = ctx.source;
     if (ctx.durationMs !== undefined)
         env.DSH_HOOK_DURATION_MS = String(ctx.durationMs);
     if (ctx.status !== undefined)
@@ -27,6 +35,16 @@ export function toEnv(ctx) {
         env.DSH_HOOK_ERROR = ctx.error;
     if (ctx.content !== undefined)
         env.DSH_HOOK_CONTENT = ctx.content;
+    if (ctx.usageInputTokens !== undefined)
+        env.DSH_HOOK_USAGE_INPUT_TOKENS = String(ctx.usageInputTokens);
+    if (ctx.usageOutputTokens !== undefined)
+        env.DSH_HOOK_USAGE_OUTPUT_TOKENS = String(ctx.usageOutputTokens);
+    if (ctx.usageCacheReadTokens !== undefined)
+        env.DSH_HOOK_USAGE_CACHE_READ_TOKENS = String(ctx.usageCacheReadTokens);
+    if (ctx.usageCacheWriteTokens !== undefined)
+        env.DSH_HOOK_USAGE_CACHE_WRITE_TOKENS = String(ctx.usageCacheWriteTokens);
+    if (ctx.usageReasoningTokens !== undefined)
+        env.DSH_HOOK_USAGE_REASONING_TOKENS = String(ctx.usageReasoningTokens);
     return env;
 }
 /** Render `{{DSH_HOOK_*}}` placeholders from the context map. */

package/lib/dry-run.d.ts

@@ -0,0 +1,48 @@
+import { type HookSpec, type TurnEndReasonKind } from './config.js';
+import type { HookContext } from './context.js';
+/** Profile patch file for a profile name. */
+export declare function patchFilePath(profile: string): string;
+/**
+ * Load and normalize the dsh-hooks config block from a profile's
+ * cordis.patch.yml. Runs the block through the Config schema so match
+ * regexes compile and invalid entries fail loudly.
+ */
+export declare function loadHooks(profile: string, paths?: {
+    patchFile?: string;
+}): {
+    hooks: HookSpec[];
+    source: string;
+};
+/** A synthetic context for the simulated event, overridable per field. */
+export declare function mockContext(event: string, overrides?: Partial<HookContext>): HookContext;
+export interface DryRunLine {
+    /** 1-based hook index in the config. */
+    index: number;
+    matched: boolean;
+    /** Short reason the hook was skipped (empty when matched). */
+    why: string;
+    /** One-line hook description. */
+    summary: string;
+}
+/** One-line hook description for report rows. */
+export declare function describeHook(hook: HookSpec): string;
+/** Evaluate every hook against the simulated event/context. */
+export declare function evaluateHooks(hooks: readonly HookSpec[], event: string, ctx: HookContext, reasonKind?: TurnEndReasonKind): DryRunLine[];
+export interface DryRunOptions {
+    profile?: string;
+    event: string;
+    reason?: TurnEndReasonKind;
+    tool?: string;
+    sessionName?: string;
+    /** Actually run the matching hooks (real side effects!). */
+    execute?: boolean;
+    print?: (line: string) => void;
+    paths?: {
+        patchFile?: string;
+    };
+}
+/** Full dry-run report; optionally executes the matching hooks. */
+export declare function runDryRun(options: DryRunOptions): Promise<{
+    matched: number;
+    total: number;
+}>;

package/lib/dry-run.js

@@ -0,0 +1,136 @@
+/**
+ * dry-run: simulate a hook event against a profile's dsh-hooks config and
+ * report which hooks would fire (and why the others would not). `--execute`
+ * actually runs the matching hooks, for end-to-end verification.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import YAML from 'yaml';
+import { Config } from './config.js';
+import { matchFilters } from './events.js';
+import { createHookRunner } from './runner.js';
+import { fireNotify } from './notify.js';
+/** Profile patch file for a profile name. */
+export function patchFilePath(profile) {
+    return join(homedir(), '.dsh', 'profiles', profile, 'cordis.patch.yml');
+}
+/**
+ * Load and normalize the dsh-hooks config block from a profile's
+ * cordis.patch.yml. Runs the block through the Config schema so match
+ * regexes compile and invalid entries fail loudly.
+ */
+export function loadHooks(profile, paths = {}) {
+    const file = paths.patchFile ?? patchFilePath(profile);
+    if (!existsSync(file))
+        throw new Error(`未找到 ${file}（profile 不存在或没有 cordis.patch.yml）`);
+    let entries;
+    try {
+        entries = YAML.parse(readFileSync(file, 'utf8'));
+    }
+    catch {
+        throw new Error(`cordis.patch.yml 解析失败：${file}`);
+    }
+    if (!Array.isArray(entries))
+        throw new Error('cordis.patch.yml 顶层必须是 YAML 数组');
+    let block;
+    for (const entry of entries) {
+        if (entry !== null && typeof entry === 'object' && entry.id === 'dsh-hooks') {
+            block = entry;
+            break;
+        }
+    }
+    if (block === undefined)
+        throw new Error('cordis.patch.yml 中没有 id: dsh-hooks 的配置块');
+    const rawHooks = block.config?.hooks;
+    const config = Config({ hooks: (Array.isArray(rawHooks) ? rawHooks : []) });
+    return { hooks: config.hooks ?? [], source: file };
+}
+/** A synthetic context for the simulated event, overridable per field. */
+export function mockContext(event, overrides = {}) {
+    return {
+        event,
+        sessionId: 'dry-run',
+        sessionName: 'dry-run 会话',
+        cwd: process.cwd(),
+        turn: 1,
+        step: 1,
+        tool: 'pwsh',
+        callId: 'dry-run-call',
+        content: 'dry-run 模拟内容',
+        timestamp: new Date().toISOString(),
+        ...overrides,
+    };
+}
+/** One-line hook description for report rows. */
+export function describeHook(hook) {
+    const when = hook.when ? ` when=${hook.when}` : '';
+    const match = hook.match && Object.keys(hook.match).length > 0
+        ? ` match=${JSON.stringify(Object.fromEntries(Object.entries(hook.match).map(([key, re]) => [key, re.source])))},`
+        : '';
+    if (hook.run)
+        return `[${hook.on}${when}]${match} run: ${hook.run}`;
+    if (hook.notify)
+        return `[${hook.on}${when}]${match} notify: ${hook.notify.channel}${hook.notify.url ? ` ${hook.notify.url}` : ''}`;
+    return `[${hook.on}${when}]${match} (既无 run 也无 notify)`;
+}
+/** Evaluate every hook against the simulated event/context. */
+export function evaluateHooks(hooks, event, ctx, reasonKind) {
+    return hooks.map((hook, index) => {
+        const summary = describeHook(hook);
+        if (hook.on !== event) {
+            return { index: index + 1, matched: false, why: `事件不匹配（${hook.on} ≠ ${event}）`, summary };
+        }
+        if (event === 'turn/end' && hook.when !== undefined && hook.when !== reasonKind) {
+            return { index: index + 1, matched: false, why: `when 不匹配（期望 ${hook.when}，实际 ${reasonKind ?? '无'}）`, summary };
+        }
+        if (!matchFilters(hook.match, ctx)) {
+            return { index: index + 1, matched: false, why: 'match 过滤未通过', summary };
+        }
+        return { index: index + 1, matched: true, why: '', summary };
+    });
+}
+/** Full dry-run report; optionally executes the matching hooks. */
+export async function runDryRun(options) {
+    const profile = options.profile ?? 'web';
+    const print = options.print ?? console.log;
+    const { hooks, source } = loadHooks(profile, options.paths);
+    const reasonKind = options.reason;
+    const ctx = mockContext(options.event, {
+        reason: reasonKind,
+        tool: options.tool,
+        sessionName: options.sessionName,
+    });
+    print('dsh-hooks dry-run');
+    print(`配置来源：${source}（${hooks.length} 个 hook）`);
+    print(`模拟事件：${options.event}${reasonKind ? `（reason=${reasonKind}）` : ''}`);
+    const lines = evaluateHooks(hooks, options.event, ctx, reasonKind);
+    for (const line of lines) {
+        print(line.matched ? `✅ [${line.index}] ${line.summary}` : `⏭ [${line.index}] ${line.summary} —— ${line.why}`);
+    }
+    const matched = lines.filter((line) => line.matched);
+    if (options.execute) {
+        if (matched.length === 0) {
+            print('没有匹配的 hook 可执行');
+        }
+        const runner = createHookRunner((line) => print(`  ${line}`));
+        for (const line of matched) {
+            const hook = hooks[line.index - 1];
+            if (hook.run) {
+                print(`▶ 执行 [${line.index}] ${describeHook(hook)}`);
+                const outcome = runner.run(hook, ctx);
+                if (!outcome.ok)
+                    print(`  ✗ ${outcome.reason}${outcome.detail ? `: ${outcome.detail}` : ''}`);
+            }
+            else if (hook.notify) {
+                print(`▶ 发送 [${line.index}] notify:${hook.notify.channel}`);
+                await fireNotify(hook.notify, ctx);
+            }
+        }
+        print('（run 命令 fire-and-forget：执行结果见 dsh 日志）');
+    }
+    else if (matched.length > 0) {
+        print(`共 ${matched.length} 个 hook 会触发。加 --execute 实际执行（真实副作用！）`);
+    }
+    return { matched: matched.length, total: hooks.length };
+}