@pugi/cli 0.1.0-alpha.3 → 0.1.0-alpha.5

package/dist/core/hooks.js

@@ -0,0 +1,415 @@
+import { spawn } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { existsSync, readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { resolve } from 'node:path';
+import { z } from 'zod';
+import { recordHookInvoked, recordHookResult, recordHookSkipped, } from './session.js';
+import { isTrustedWorkspace } from './trust.js';
+export const ALL_HOOK_EVENTS = [
+    'SessionStart',
+    'UserPromptSubmit',
+    'PreToolUse',
+    'PermissionRequest',
+    'PostToolUse',
+    'PostToolUseFailure',
+    'Stop',
+    'SessionEnd',
+];
+const hookEventSchema = z.enum([
+    'SessionStart',
+    'UserPromptSubmit',
+    'PreToolUse',
+    'PermissionRequest',
+    'PostToolUse',
+    'PostToolUseFailure',
+    'Stop',
+    'SessionEnd',
+]);
+const hookMatchSchema = z
+    .object({
+    tool: z.string().min(1).optional(),
+    permission: z.enum(['read', 'edit', 'bash', 'network', 'mcp', 'subagent']).optional(),
+    pathGlob: z.string().min(1).optional(),
+})
+    .strict();
+const hookDefinitionSchema = z
+    .object({
+    event: hookEventSchema,
+    match: hookMatchSchema.optional(),
+    run: z.string().min(1),
+    timeoutMs: z.number().int().positive().max(60_000).optional(),
+    onFailure: z.enum(['warn', 'block']).optional(),
+})
+    .strict();
+const hooksFileSchema = z
+    .object({
+    hooks: z.array(hookDefinitionSchema).default([]),
+})
+    .strict();
+const DEFAULT_TIMEOUT_MS = 5_000;
+const SIGKILL_GRACE_MS = 2_000;
+// Cap each captured stream at 1 MiB so a misbehaving hook (`yes`, `cat
+// /dev/urandom | base64`) cannot OOM the parent CLI by buffering
+// unbounded output between data events and the SIGTERM watchdog. 1 MiB
+// is generous headroom over realistic logger output while bounded.
+const HOOK_STREAM_CAP_BYTES = 1024 * 1024;
+export class HookRegistry {
+    options;
+    sources = [];
+    loaded = false;
+    /**
+     * Per-batch dedup memory. The caller is expected to call `resetBatch()`
+     * between independent event batches so hooks fire once per batch even
+     * if multiple identical events are emitted in tight succession from
+     * the same tool dispatch.
+     */
+    batchSeen = new Set();
+    trustedProjects = new Map();
+    constructor(options) {
+        this.options = options;
+    }
+    async load() {
+        this.sources.length = 0;
+        this.loaded = true;
+        const userPath = resolve(this.userHomeRoot(), 'hooks.json');
+        if (existsSync(userPath)) {
+            const userHooks = parseHooksFile(userPath);
+            this.sources.push({ origin: 'user', path: userPath, hooks: userHooks });
+        }
+        const projectPath = resolve(this.options.workspaceRoot, '.pugi/hooks.json');
+        if (existsSync(projectPath)) {
+            const trusted = await isTrustedWorkspace(this.options.workspaceRoot);
+            this.trustedProjects.set(this.options.workspaceRoot, trusted);
+            if (trusted) {
+                const projectHooks = parseHooksFile(projectPath);
+                this.sources.push({ origin: 'project', path: projectPath, hooks: projectHooks });
+            }
+        }
+    }
+    list(event) {
+        this.assertLoaded();
+        const all = this.sources.flatMap((source) => source.hooks);
+        return event ? all.filter((hook) => hook.event === event) : all;
+    }
+    /**
+     * Hooks that match the given event and context. The caller can use this
+     * to correlate hook definitions with `fire()` results positionally for
+     * downstream policy checks (e.g. PreToolUse blocking).
+     */
+    listMatching(ctx) {
+        return this.list(ctx.event).filter((hook) => matchesContext(hook, ctx));
+    }
+    /**
+     * Reset the per-batch dedup memory. Call between independent event
+     * batches (typically once per tool dispatch) so identical hook entries
+     * fire once per batch, not just once per session.
+     */
+    resetBatch() {
+        this.batchSeen.clear();
+    }
+    async fire(ctx) {
+        this.assertLoaded();
+        const candidates = this.listMatching(ctx);
+        // If the project hook file exists but the workspace is untrusted,
+        // emit a `hook.skipped: untrusted-project` once per `fire` so the
+        // audit log explains the gap. We only emit this if the user actually
+        // has a project hooks file on disk — otherwise there is nothing to
+        // skip.
+        const projectPath = resolve(this.options.workspaceRoot, '.pugi/hooks.json');
+        const projectHooksOnDisk = existsSync(projectPath);
+        const projectTrusted = this.trustedProjects.get(this.options.workspaceRoot) ?? false;
+        if (projectHooksOnDisk && !projectTrusted) {
+            this.recordSkipped(ctx, 'untrusted-project');
+        }
+        if (candidates.length === 0) {
+            return [];
+        }
+        const results = [];
+        for (const hook of candidates) {
+            const key = dedupKey(ctx.event, hook);
+            if (this.batchSeen.has(key)) {
+                this.recordSkipped(ctx, 'dedup');
+                results.push({
+                    ok: true,
+                    stdout: '',
+                    stderr: '',
+                    exitCode: 0,
+                    elapsedMs: 0,
+                    skipped: 'dedup',
+                });
+                continue;
+            }
+            this.batchSeen.add(key);
+            this.recordInvoked(ctx, hook);
+            const result = await executeHook(hook, ctx);
+            this.recordResult(ctx, result);
+            results.push(result);
+        }
+        return results;
+    }
+    assertLoaded() {
+        if (!this.loaded) {
+            throw new Error('HookRegistry.load() must be called before use');
+        }
+    }
+    userHomeRoot() {
+        const home = this.options.home ?? process.env.PUGI_HOME ?? resolve(homedir(), '.pugi');
+        return home;
+    }
+    recordInvoked(ctx, hook) {
+        if (!this.options.session)
+            return;
+        recordHookInvoked(this.options.session, {
+            event: ctx.event,
+            matchSummary: summariseMatch(hook.match),
+            runSummary: hook.run.slice(0, 200),
+        });
+    }
+    recordResult(ctx, result) {
+        if (!this.options.session)
+            return;
+        recordHookResult(this.options.session, {
+            event: ctx.event,
+            ok: result.ok,
+            exitCode: result.exitCode,
+            elapsedMs: result.elapsedMs,
+            stdoutLen: result.stdout.length,
+            stderrLen: result.stderr.length,
+        });
+    }
+    recordSkipped(ctx, reason) {
+        if (!this.options.session)
+            return;
+        recordHookSkipped(this.options.session, { event: ctx.event, reason });
+    }
+}
+/**
+ * Convenience helper for firing a SessionStart event from the CLI
+ * bootstrap path. Kept separate so the runtime entry point (cli.ts)
+ * does not need to construct a HookRegistry itself — that wiring lives
+ * in a follow-up PR by the TUI agent.
+ */
+export async function fireSessionStart(registry, ctx) {
+    return registry.fire({ ...ctx, event: 'SessionStart' });
+}
+function parseHooksFile(path) {
+    let raw;
+    try {
+        raw = readFileSync(path, 'utf8');
+    }
+    catch (error) {
+        throw new Error(`hooks: cannot read ${path}: ${error.message}`);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (error) {
+        throw new Error(`hooks: ${path} is not valid JSON: ${error.message}`);
+    }
+    const result = hooksFileSchema.safeParse(parsed);
+    if (!result.success) {
+        const issues = result.error.issues
+            .map((issue) => `${issue.path.join('.')} ${issue.message}`)
+            .join('; ');
+        throw new Error(`hooks: ${path} failed schema validation: ${issues}`);
+    }
+    return result.data.hooks;
+}
+function matchesContext(hook, ctx) {
+    if (!hook.match)
+        return true;
+    const { tool, permission, pathGlob } = hook.match;
+    if (tool !== undefined) {
+        if (!ctx.tool)
+            return false;
+        if (!globMatch(tool, ctx.tool))
+            return false;
+    }
+    if (permission !== undefined) {
+        if (ctx.permission !== permission)
+            return false;
+    }
+    if (pathGlob !== undefined) {
+        if (!ctx.path)
+            return false;
+        if (!globMatch(pathGlob, ctx.path))
+            return false;
+    }
+    return true;
+}
+/**
+ * Tiny glob matcher: supports `*` (any chars except `/`) and `**` (any
+ * chars including `/`). Anchored at both ends. Plain strings without any
+ * wildcards must match exactly. We deliberately avoid pulling in a full
+ * glob lib here because the match grammar is intentionally narrow for M1.
+ */
+function globMatch(pattern, value) {
+    // Escape regex special chars except * and /, then translate ** and *
+    // into their regex equivalents. Order matters: handle ** before *.
+    const escaped = pattern.replace(/[.+?^${}()|[\]\\]/g, '\\$&');
+    const translated = escaped.replace(/\*\*/g, '<<DOUBLESTAR>>').replace(/\*/g, '[^/]*').replace(/<<DOUBLESTAR>>/g, '.*');
+    const regex = new RegExp(`^${translated}$`);
+    return regex.test(value);
+}
+function stableJsonHash(value) {
+    const stringified = stableStringify(value);
+    return createHash('sha256').update(stringified).digest('hex').slice(0, 16);
+}
+function stableStringify(value) {
+    if (value === null || typeof value !== 'object') {
+        return JSON.stringify(value);
+    }
+    if (Array.isArray(value)) {
+        return `[${value.map((v) => stableStringify(v)).join(',')}]`;
+    }
+    const obj = value;
+    const keys = Object.keys(obj).sort();
+    return `{${keys.map((key) => `${JSON.stringify(key)}:${stableStringify(obj[key])}`).join(',')}}`;
+}
+function dedupKey(event, hook) {
+    return `${event}:${stableJsonHash(hook.match ?? null)}:${stableJsonHash(hook.run)}`;
+}
+function summariseMatch(match) {
+    if (!match)
+        return '*';
+    const parts = [];
+    if (match.tool)
+        parts.push(`tool=${match.tool}`);
+    if (match.permission)
+        parts.push(`permission=${match.permission}`);
+    if (match.pathGlob)
+        parts.push(`path=${match.pathGlob}`);
+    return parts.length ? parts.join(',') : '*';
+}
+async function executeHook(hook, ctx) {
+    const timeoutMs = hook.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const startedAt = Date.now();
+    return new Promise((resolvePromise) => {
+        const payloadJson = JSON.stringify(ctx.payload ?? null);
+        const child = spawn('/bin/sh', ['-c', hook.run], {
+            env: {
+                ...process.env,
+                PUGI_HOOK_PAYLOAD: payloadJson,
+                PUGI_HOOK_EVENT: ctx.event,
+                PUGI_HOOK_SESSION_ID: ctx.sessionId,
+            },
+            stdio: ['pipe', 'pipe', 'pipe'],
+        });
+        let stdout = '';
+        let stderr = '';
+        let killedForTimeout = false;
+        let killedForStreamCap = false;
+        let sigKillTimer;
+        const enforceStreamCap = () => {
+            if (killedForStreamCap)
+                return;
+            if (stdout.length + stderr.length <= HOOK_STREAM_CAP_BYTES)
+                return;
+            killedForStreamCap = true;
+            child.kill('SIGTERM');
+            // Reuse the same SIGKILL escalation as the timeout path.
+            if (!sigKillTimer) {
+                sigKillTimer = setTimeout(() => {
+                    if (!child.killed)
+                        child.kill('SIGKILL');
+                }, SIGKILL_GRACE_MS);
+                if (sigKillTimer.unref)
+                    sigKillTimer.unref();
+            }
+        };
+        child.stdout?.on('data', (chunk) => {
+            if (killedForStreamCap)
+                return;
+            stdout += chunk.toString('utf8');
+            enforceStreamCap();
+        });
+        child.stderr?.on('data', (chunk) => {
+            if (killedForStreamCap)
+                return;
+            stderr += chunk.toString('utf8');
+            enforceStreamCap();
+        });
+        // Write the payload to stdin so hooks that prefer reading from stdin
+        // (e.g. `jq .`) work without depending on the env var. Hooks that
+        // do not consume stdin (e.g. `echo done`) close their end of the
+        // pipe immediately; writing then raises EPIPE which we swallow —
+        // payload-via-stdin is best-effort, not required.
+        if (child.stdin) {
+            child.stdin.on('error', () => {
+                // EPIPE / ECONNRESET when the child closed stdin before reading.
+                // Safe to ignore: PUGI_HOOK_PAYLOAD env var still carries the data.
+            });
+            child.stdin.end(payloadJson);
+        }
+        const timer = setTimeout(() => {
+            killedForTimeout = true;
+            child.kill('SIGTERM');
+            // Escalate to SIGKILL if the process refuses to exit.
+            sigKillTimer = setTimeout(() => {
+                if (!child.killed) {
+                    child.kill('SIGKILL');
+                }
+            }, SIGKILL_GRACE_MS);
+            if (sigKillTimer.unref)
+                sigKillTimer.unref();
+        }, timeoutMs);
+        if (timer.unref)
+            timer.unref();
+        child.on('error', (error) => {
+            clearTimeout(timer);
+            if (sigKillTimer)
+                clearTimeout(sigKillTimer);
+            resolvePromise({
+                ok: false,
+                stdout,
+                stderr: stderr || `hook spawn error: ${error.message}`,
+                exitCode: -1,
+                elapsedMs: Date.now() - startedAt,
+            });
+        });
+        child.on('close', (code, signal) => {
+            clearTimeout(timer);
+            if (sigKillTimer)
+                clearTimeout(sigKillTimer);
+            const elapsedMs = Date.now() - startedAt;
+            // When killed by signal, child_process reports code=null, signal=<name>.
+            // Translate to a negative numeric exit code so callers can read it
+            // uniformly (-15 for SIGTERM, -9 for SIGKILL). This matches the
+            // convention several Node tools (cross-spawn, execa) use.
+            let exitCode;
+            if (code !== null) {
+                exitCode = code;
+            }
+            else if (signal === 'SIGTERM') {
+                exitCode = -15;
+            }
+            else if (signal === 'SIGKILL') {
+                exitCode = -9;
+            }
+            else {
+                exitCode = -1;
+            }
+            // `ok` is true iff the hook exited cleanly (exit 0, not killed).
+            // Both `onFailure: 'warn'` and `onFailure: 'block'` produce ok=false
+            // on a non-zero exit — the difference is how the CALLER reacts.
+            // The caller reads `hook.onFailure` (via list()) to decide whether
+            // a non-ok result should warn or block the originating action.
+            // A stream-cap kill is also a failure: the hook produced too much
+            // output and we cannot trust whatever partial result we captured.
+            const ok = exitCode === 0 && !killedForTimeout && !killedForStreamCap;
+            const stderrFinal = killedForStreamCap
+                ? `${stderr}\nhook output exceeded ${HOOK_STREAM_CAP_BYTES} bytes; killed by stream cap.`
+                : stderr;
+            resolvePromise({
+                ok,
+                stdout,
+                stderr: stderrFinal,
+                exitCode,
+                elapsedMs,
+            });
+        });
+    });
+}
+//# sourceMappingURL=hooks.js.map