dsh-hooks 0.4.0 → 0.6.0

package/lib/history.js

@@ -2,8 +2,14 @@
  * Hook execution history: an in-memory ring buffer plus a best-effort
  * JSONL append log under ~/.dsh/dsh-hooks/ (0600, owner-only). History is
  * strictly best-effort — a failed write never breaks a hook.
+ *
+ * The buffer is not process-private memory only: it seeds from the JSONL at
+ * startup and `sync()` incrementally ingests bytes appended since the last
+ * read, so records written before a restart (or by another dsh process
+ * sharing the file, e.g. a task-board Host) surface in the web GUI instead
+ * of vanishing with the process.
  */
-import { appendFileSync, chmodSync, mkdirSync } from 'node:fs';
+import { appendFileSync, chmodSync, closeSync, existsSync, mkdirSync, openSync, readFileSync, readSync, statSync, } from 'node:fs';
 import { homedir } from 'node:os';
 import { dirname, join } from 'node:path';
 export const DEFAULT_HISTORY_PATH = join(homedir(), '.dsh', 'dsh-hooks', 'history.jsonl');
@@ -15,11 +21,101 @@ export function createHistorySink(options = {}) {
     const buffer = [];
     let dirReady = false;
     let chmodded = false;
-    function record(partial) {
-        const entry = { ...partial, ts: Date.now() };
+    /** Bytes of `file` already ingested into the buffer. */
+    let syncedBytes = 0;
+    /** Trailing fragment of the last read that did not end with a newline. */
+    let pending = '';
+    function push(entry) {
         buffer.push(entry);
         if (buffer.length > max)
             buffer.splice(0, buffer.length - max);
+    }
+    /** Parse complete JSONL lines into the ring buffer; incomplete tails stay pending. */
+    function ingest(text) {
+        pending += text;
+        const lines = pending.split('\n');
+        pending = lines.pop() ?? '';
+        for (const line of lines) {
+            if (line === '')
+                continue;
+            try {
+                const entry = JSON.parse(line);
+                if (typeof entry !== 'object' || entry === null || typeof entry.ts !== 'number')
+                    continue;
+                push(entry);
+            }
+            catch {
+                // Broken line (mid-write or foreign content): skip, never fail.
+            }
+        }
+    }
+    /** Rebuild the buffer from the whole file (startup seed / truncated file). */
+    function rebuild() {
+        buffer.length = 0;
+        pending = '';
+        syncedBytes = 0;
+        const text = readFileSync(file, 'utf8');
+        syncedBytes = Buffer.byteLength(text, 'utf8');
+        ingest(text);
+    }
+    /** Seed the ring buffer from an existing JSONL log (best-effort). */
+    function seed() {
+        if (!enabled)
+            return;
+        try {
+            if (!existsSync(file))
+                return;
+            rebuild();
+        }
+        catch {
+            // Seeding is best-effort; recording starts from an empty buffer.
+        }
+    }
+    /** Ingest every byte appended since the last read (own writes included). */
+    function sync() {
+        if (!enabled)
+            return;
+        try {
+            if (!existsSync(file))
+                return;
+            const size = statSync(file).size;
+            if (size === syncedBytes)
+                return;
+            if (size < syncedBytes) {
+                // The file shrank (rotation/truncation): rebuild from its tail.
+                rebuild();
+                return;
+            }
+            const deltaBytes = size - syncedBytes;
+            const fd = openSync(file, 'r');
+            try {
+                const chunk = Buffer.allocUnsafe(deltaBytes);
+                let total = 0;
+                while (total < deltaBytes) {
+                    const n = readSync(fd, chunk, total, deltaBytes - total, syncedBytes + total);
+                    if (n <= 0)
+                        break;
+                    total += n;
+                }
+                ingest(chunk.subarray(0, total).toString('utf8'));
+            }
+            finally {
+                closeSync(fd);
+            }
+            syncedBytes = size;
+        }
+        catch {
+            // Sync is best-effort; the next call retries.
+        }
+    }
+    function record(partial) {
+        const entry = { ...partial, ts: Date.now() };
+        // Ingest other processes' appends BEFORE our own entry so the buffer
+        // stays in file order, and `syncedBytes` stays a true prefix of the
+        // file (otherwise our own advance would skip the foreign appends).
+        if (enabled)
+            sync();
+        push(entry);
         if (!enabled)
             return;
         try {
@@ -28,6 +124,7 @@ export function createHistorySink(options = {}) {
                 dirReady = true;
             }
             appendFileSync(file, JSON.stringify(entry) + '\n', 'utf8');
+            syncedBytes = statSync(file).size;
             if (!chmodded) {
                 try {
                     chmodSync(file, 0o600);
@@ -42,9 +139,11 @@ export function createHistorySink(options = {}) {
             // History is best-effort: a failed write never breaks a hook.
         }
     }
+    seed();
     return {
         record,
         recent: () => buffer,
+        sync,
         dispose: () => { },
     };
 }

package/lib/index.js

@@ -5,6 +5,7 @@ import { eventLabel } from './context.js';
 import { createHookRunner } from './runner.js';
 import { fireNotify } from './notify.js';
 import { createHistorySink } from './history.js';
+import { createFeishuSetupManager } from './feishu-session.js';
 import { registerHookRoutes } from './server.js';
 export const name = 'dsh-hooks';
 // Dependency on the session service: `session/event` only exists once a
@@ -22,12 +23,20 @@ export function apply(ctx, config = {}) {
     const hooks = config.hooks ?? [];
     const history = createHistorySink(config.history ?? undefined);
     const runner = createHookRunner((line) => ctx.logger?.info(line), (record) => history.record(record));
-    // Web-profile extras: /dsh-hooks routes and the agent announcement. Both
-    // services are optional — CLI/headless profiles provide neither, and the
-    // plugin keeps working there untouched.
+    // Web-profile extras: /dsh-hooks routes (incl. the Feishu connect flow)
+    // and the agent announcement. Both services are optional — CLI/headless
+    // profiles provide neither, and the plugin keeps working there untouched.
     const webServer = ctx.get('webServer', false);
     if (webServer !== undefined) {
-        ctx.effect(() => registerHookRoutes(webServer, { hooks, history }), 'dsh-hooks: /dsh-hooks routes');
+        const feishu = createFeishuSetupManager();
+        ctx.effect(() => {
+            const unregister = registerHookRoutes(webServer, { hooks, history, runner, feishu: { manager: feishu } });
+            return () => {
+                unregister();
+                // Abort an in-flight QR scan so it never outlives the plugin.
+                feishu.dispose();
+            };
+        }, 'dsh-hooks: /dsh-hooks routes');
     }
     const systemPrompt = ctx.get('systemPrompt', false);
     if (systemPrompt !== undefined) {

package/lib/notify.d.ts

@@ -24,5 +24,5 @@ export declare function sendWebhook(spec: NotifySpec, ctx: HookContext, env?: No
  * through shell-string interpolation.
  */
 export declare function sendDesktop(spec: NotifySpec, ctx: HookContext): Promise<NotifyResult>;
-/** Fire a built-in notification; failures only warn. */
-export declare function fireNotify(spec: NotifySpec, ctx: HookContext, record?: NotifyRecord): Promise<void>;
+/** Fire a built-in notification; failures only warn and surface in the result. */
+export declare function fireNotify(spec: NotifySpec, ctx: HookContext, record?: NotifyRecord): Promise<NotifyResult>;

package/lib/notify.js

@@ -196,7 +196,7 @@ function runAndWait(argv, env, timeoutMs) {
         });
     });
 }
-/** Fire a built-in notification; failures only warn. */
+/** Fire a built-in notification; failures only warn and surface in the result. */
 export async function fireNotify(spec, ctx, record) {
     const startedAt = Date.now();
     const result = spec.channel === 'webhook' ? await sendWebhook(spec, ctx) : await sendDesktop(spec, ctx);
@@ -212,7 +212,7 @@ export async function fireNotify(spec, ctx, record) {
             durationMs: Date.now() - startedAt,
             error: result.error,
         });
-        return;
+        return result;
     }
     record?.({
         kind: 'notify',
@@ -223,4 +223,5 @@ export async function fireNotify(spec, ctx, record) {
         outcome: 'sent',
         durationMs: Date.now() - startedAt,
     });
+    return result;
 }

package/lib/patch-config.d.ts

@@ -0,0 +1,47 @@
+/** Wire shape for one hook as the settings panel sends it (string regexes). */
+export interface HookWireSpec {
+    on: string;
+    when?: string;
+    match?: Record<string, string>;
+    run?: string;
+    notify?: {
+        channel: 'webhook' | 'desktop';
+        url?: string;
+        slack?: boolean;
+    } | null;
+    input?: 'env' | 'stdin';
+    timeoutMs?: number;
+    retries?: number;
+    retryDelayMs?: number;
+}
+/** Parse a patch list; throws a user-facing error on malformed YAML. */
+export declare function parsePatchText(text: string): unknown[];
+/**
+ * Validate the wire hooks before they ever touch a file. Returns a
+ * user-facing error message, or null when every hook is valid.
+ */
+export declare function validateHookWire(hooks: HookWireSpec[]): string | null;
+/**
+ * Replace the dsh-hooks block's hooks in a patch list. Other entries and
+ * other config of the dsh-hooks entry (e.g. `history`) stay untouched; a
+ * missing dsh-hooks entry is appended.
+ */
+export declare function patchTextWithHooks(existingText: string, hooks: HookWireSpec[]): string;
+/** Timestamped backup path for a patch file. */
+export declare function backupPathFor(patchFile: string, now?: Date): string;
+export interface WriteHooksResult {
+    patchFile: string;
+    backupPath: string;
+    hookCount: number;
+}
+/**
+ * Validate and persist the hook list into a profile's cordis.patch.yml.
+ * The previous content is backed up beside the file first.
+ */
+export declare function writeHooksConfig(patchFile: string, hooks: HookWireSpec[]): WriteHooksResult;
+/**
+ * Drop every hook whose `run` references the given script (the stable
+ * notify-feishu.mjs copy), used by the Feishu disconnect flow. Other
+ * entries and config stay untouched.
+ */
+export declare function removeScriptHooks(patchFile: string, scriptMarker: string): void;

package/lib/patch-config.js

@@ -0,0 +1,141 @@
+/**
+ * Patch-file plumbing for the settings-panel hook editor and the Feishu
+ * disconnect flow: read a profile's cordis.patch.yml, replace the dsh-hooks
+ * block's hooks while keeping every other entry (and other dsh-hooks
+ * config, e.g. `history`) untouched, and write back with a timestamped
+ * backup. The profile layer is hot-reloaded by the harness's patch watcher,
+ * so a save applies without a restart.
+ */
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import YAML from 'yaml';
+import { HOOK_EVENTS, TURN_END_REASONS } from './config.js';
+/** Parse a patch list; throws a user-facing error on malformed YAML. */
+export function parsePatchText(text) {
+    let entries;
+    try {
+        entries = YAML.parse(text || '[]\n');
+    }
+    catch {
+        throw new Error('cordis.patch.yml 解析失败，请先修复该文件');
+    }
+    if (!Array.isArray(entries))
+        throw new Error('cordis.patch.yml 顶层必须是 YAML 数组');
+    return entries;
+}
+/**
+ * Validate the wire hooks before they ever touch a file. Returns a
+ * user-facing error message, or null when every hook is valid.
+ */
+export function validateHookWire(hooks) {
+    for (const [i, hook] of hooks.entries()) {
+        const label = `hook #${i + 1}`;
+        if (!HOOK_EVENTS.includes(hook.on)) {
+            return `${label}：无效事件 ${hook.on}`;
+        }
+        if (hook.when !== undefined && !TURN_END_REASONS.includes(hook.when)) {
+            return `${label}：无效 when 原因 ${hook.when}`;
+        }
+        if (hook.match !== undefined) {
+            for (const [field, pattern] of Object.entries(hook.match)) {
+                if (field === '')
+                    return `${label}：match 字段名不能为空`;
+                try {
+                    new RegExp(pattern);
+                }
+                catch (error) {
+                    return `${label}：match.${field} 正则无效（${error instanceof Error ? error.message : String(error)}）`;
+                }
+            }
+        }
+        const hasRun = typeof hook.run === 'string' && hook.run.trim() !== '';
+        const hasNotify = hook.notify !== undefined && hook.notify !== null;
+        if (hasRun === hasNotify) {
+            return `${label}：run 与 notify 必须且只能声明一个`;
+        }
+        if (hasNotify && hook.notify.channel !== 'webhook' && hook.notify.channel !== 'desktop') {
+            return `${label}：无效通知渠道 ${hook.notify.channel}`;
+        }
+        for (const key of ['timeoutMs', 'retries', 'retryDelayMs']) {
+            const value = hook[key];
+            if (value !== undefined && (!Number.isFinite(value) || value < 0)) {
+                return `${label}：${key} 必须是非负数字`;
+            }
+        }
+    }
+    return null;
+}
+/**
+ * Replace the dsh-hooks block's hooks in a patch list. Other entries and
+ * other config of the dsh-hooks entry (e.g. `history`) stay untouched; a
+ * missing dsh-hooks entry is appended.
+ */
+export function patchTextWithHooks(existingText, hooks) {
+    const entries = parsePatchText(existingText);
+    let found = false;
+    for (const entry of entries) {
+        if (entry !== null && typeof entry === 'object' && entry.id === 'dsh-hooks') {
+            const target = entry;
+            target.name = 'dsh-hooks';
+            target.config = { ...(target.config ?? {}), hooks };
+            found = true;
+            break;
+        }
+    }
+    if (!found)
+        entries.push({ id: 'dsh-hooks', name: 'dsh-hooks', config: { hooks } });
+    return YAML.stringify(entries);
+}
+/** Timestamped backup path for a patch file. */
+export function backupPathFor(patchFile, now = new Date()) {
+    const pad = (n) => String(n).padStart(2, '0');
+    const stamp = `${now.getFullYear()}${pad(now.getMonth() + 1)}${pad(now.getDate())}-${pad(now.getHours())}${pad(now.getMinutes())}${pad(now.getSeconds())}`;
+    return `${patchFile}.bak-${stamp}`;
+}
+/**
+ * Validate and persist the hook list into a profile's cordis.patch.yml.
+ * The previous content is backed up beside the file first.
+ */
+export function writeHooksConfig(patchFile, hooks) {
+    const invalid = validateHookWire(hooks);
+    if (invalid !== null)
+        throw new Error(invalid);
+    const existing = existsSync(patchFile) ? readFileSync(patchFile, 'utf8') : '[]\n';
+    const backupPath = backupPathFor(patchFile);
+    writeFileSync(backupPath, existing, 'utf8');
+    writeFileSync(patchFile, patchTextWithHooks(existing, hooks), 'utf8');
+    return { patchFile, backupPath, hookCount: hooks.length };
+}
+/**
+ * Drop every hook whose `run` references the given script (the stable
+ * notify-feishu.mjs copy), used by the Feishu disconnect flow. Other
+ * entries and config stay untouched.
+ */
+export function removeScriptHooks(patchFile, scriptMarker) {
+    if (!existsSync(patchFile))
+        return;
+    const existing = readFileSync(patchFile, 'utf8');
+    const entries = parsePatchText(existing);
+    let changed = false;
+    for (const entry of entries) {
+        if (entry === null || typeof entry !== 'object' || entry.id !== 'dsh-hooks')
+            continue;
+        const config = entry.config;
+        const hooks = Array.isArray(config?.hooks) ? config.hooks : [];
+        const kept = hooks.filter((hook) => {
+            if (typeof hook.run !== 'string')
+                return true;
+            if (hook.run.includes(scriptMarker)) {
+                changed = true;
+                return false;
+            }
+            return true;
+        });
+        if (changed) {
+            config.hooks = kept;
+            const backupPath = backupPathFor(patchFile);
+            writeFileSync(backupPath, existing, 'utf8');
+            writeFileSync(patchFile, YAML.stringify(entries), 'utf8');
+        }
+        break;
+    }
+}

package/lib/runner.d.ts

@@ -10,8 +10,16 @@ export interface RunOutcome {
 /** Track in-flight hook runs so a missing parent never outlives teardown. */
 export interface HookRunner {
     run(spec: HookSpec, ctx: HookContext): RunOutcome;
+    /** Live counters for the web-panel diagnostics. */
+    stats(): HookRunnerStats;
     dispose(): void;
 }
+export interface HookRunnerStats {
+    /** Spawned children still running (waiting for their exit). */
+    inFlight: number;
+    /** Retry timers scheduled in the background. */
+    pendingRetries: number;
+}
 export type RunRecord = (record: Omit<HookRunRecord, 'ts'>) => void;
 export declare const DEFAULT_TIMEOUT_MS = 10000;
 export declare const DEFAULT_RETRY_DELAY_MS = 500;

package/lib/runner.js

@@ -142,5 +142,8 @@ export function createHookRunner(log = console.log, record) {
             terminate(child);
         children.clear();
     }
-    return { run, dispose };
+    function stats() {
+        return { inFlight: children.size, pendingRetries: pendingRetries.size };
+    }
+    return { run, stats, dispose };
 }

package/lib/server.d.ts

@@ -1,14 +1,20 @@
 /**
- * /dsh-hooks/* HTTP routes for the web profile: status, execution history,
- * and a dry-run-style test trigger. Registered only when the shared
- * webserver service exists (web profile) — CLI/headless environments never
- * see them. Loopback-only with JSON envelopes; POSTs require an explicit
- * application/json content-type (CSRF hardening, same posture as
- * dsh-aionui-panel).
+ * /dsh-hooks/* HTTP routes for the web profile: status (incl. the hook
+ * list and live runner stats), execution history, a dry-run-style test
+ * trigger, notify-channel quick tests, the hook-list editor (writes back
+ * to the profile's cordis.patch.yml with a backup), and the Feishu connect
+ * flow (QR setup / cancel / config / test card / disconnect). Registered
+ * only when the shared webserver service exists (web profile) — CLI/headless
+ * environments never see them. Loopback-only with JSON envelopes; POSTs
+ * require an explicit application/json content-type (CSRF hardening, same
+ * posture as dsh-aionui-panel).
  */
 import type { IncomingMessage, ServerResponse } from 'node:http';
 import type { HookSpec } from './config.js';
 import type { HistorySink } from './history.js';
+import { type HookRunner } from './runner.js';
+import { type FeishuSetupManager } from './feishu-session.js';
+import { runFeishuTest } from './feishu.js';
 /** Minimal structural shape of the shared web server (dsh-host-webserver). */
 export interface WebServerLike {
     register(spec: {
@@ -21,11 +27,43 @@ export interface WebServerLike {
 export declare function pluginVersion(): string;
 /** Loopback fence: never let a LAN client reach /dsh-hooks operations. */
 export declare function isLoopbackRequest(req: IncomingMessage): boolean;
+export interface FeishuRouteDeps {
+    /** QR-scan session manager (one in-flight flow at a time). */
+    manager: FeishuSetupManager;
+    /** Test-card sender, injectable for tests. */
+    runTest?: typeof runFeishuTest;
+    /** Credential file the status route summarizes. */
+    configPath?: string;
+}
 export interface HookRoutesOptions {
     hooks: readonly HookSpec[];
     history: HistorySink;
     version?: string;
+    feishu?: FeishuRouteDeps;
+    /** Live runner counters for the diagnostics badge. */
+    runner?: Pick<HookRunner, 'stats'>;
+    /** Profile → patch-file resolver, injectable so tests never touch the real home. */
+    resolvePatchFile?: (profile: string) => string;
 }
+/** Sanitized per-hook description for the settings panel (regex sources, no RegExp objects). */
+export declare function describeHooks(hooks: readonly HookSpec[]): {
+    index: number;
+    on: "agent/created" | "agent/disposed" | "agent/error" | "agent/status" | "approval/asked" | "session/created" | "session/disposed" | "session/title" | "step/end" | "tool/call" | "tool/result" | "turn/end" | "turn/start" | "user/message";
+    when: "aborted" | "blocked" | "completed" | "error" | "interrupted" | "max-tokens" | undefined;
+    match: {
+        [k: string]: string;
+    } | undefined;
+    run: string | undefined;
+    notify: {
+        channel: "desktop" | "webhook";
+        url: string | undefined;
+        slack: boolean | undefined;
+    } | undefined;
+    input: "env" | "stdin" | undefined;
+    timeoutMs: number | undefined;
+    retries: number | undefined;
+    retryDelayMs: number | undefined;
+}[];
 /** Create the /dsh-hooks route handler (exported for tests). */
 export declare function createHookHandler(options: HookRoutesOptions): (req: IncomingMessage, res: ServerResponse) => Promise<void>;
 /** Register the /dsh-hooks prefix route on the shared web server. */