@pugi/cli 0.1.0-beta.35 → 0.1.0-beta.37

package/dist/core/hooks/v2/event-emitter.js

@@ -0,0 +1,115 @@
+/**
+ * Pugi hooks v2 — event emitter (Wave 7 Phase 1).
+ *
+ * High-level fire API. Resolves matching hooks for an event, optionally
+ * prompts for trust on first encounter, executes each in declaration
+ * order (global before project), aggregates results, and surfaces
+ * blocking decisions to the caller.
+ *
+ * Sequential (not parallel) execution is intentional: operators chain
+ * `git add` -> `eslint --fix` style hooks that would race otherwise.
+ * Parallel execution lands in Phase 2 as an opt-in field on the hook
+ * declaration.
+ *
+ * Brand voice: ASCII only.
+ */
+import { compileMatcher } from './matcher.js';
+import { executeHook } from './executor.js';
+import { ensureHookTrust } from './trust.js';
+import { isToolEventV2 } from './executor.js';
+/**
+ * Fire all hooks matching `event`. Returns aggregated outcome — caller
+ * inspects `anyBlocked` + `additionalContext` to short-circuit + inject
+ * into the next prompt.
+ *
+ * Untrusted hooks (state === 'denied') are skipped. Hooks pending
+ * trust + no prompt available are also skipped (safety default).
+ */
+export async function fireHookEventV2(opts) {
+    const { config, event } = opts;
+    if (config.isEmpty()) {
+        return { event, results: [], anyBlocked: false };
+    }
+    // Resolve matching hooks. For tool events, match against toolName;
+    // for non-tool events, match against ''. The matcher's `*` and
+    // alternation grammars compile to predicates.
+    const candidate = isToolEventV2(event) ? (opts.toolName ?? '') : '';
+    const matching = config.forEvent(event).filter((hook) => {
+        try {
+            return compileMatcher(hook.matcher)(candidate);
+        }
+        catch {
+            // A malformed matcher should NOT crash the fire. The loader
+            // already validates at config-load time; this branch covers
+            // hooks injected programmatically by buggy test code.
+            return false;
+        }
+    });
+    if (matching.length === 0) {
+        return { event, results: [], anyBlocked: false };
+    }
+    const payload = {
+        schema_version: 1,
+        session_id: opts.sessionId,
+        transcript_path: opts.transcriptPath,
+        cwd: opts.workspaceRoot,
+        hook_event_name: event,
+        permission_mode: opts.permissionMode,
+        ...(opts.toolName !== undefined ? { tool_name: opts.toolName } : {}),
+        ...(opts.toolInput !== undefined ? { tool_input: opts.toolInput } : {}),
+        ...(opts.toolResult !== undefined ? { tool_result: opts.toolResult } : {}),
+        ...(opts.toolError !== undefined ? { tool_error: opts.toolError } : {}),
+        ...(opts.userPrompt !== undefined ? { user_prompt: opts.userPrompt } : {}),
+        agent_id: opts.agentId ?? null,
+        agent_type: opts.agentType ?? null,
+    };
+    const results = [];
+    let anyBlocked = false;
+    const contextParts = [];
+    for (const hook of matching) {
+        const command = hook.command ?? '';
+        const trustState = await ensureHookTrust({
+            workspaceRoot: opts.workspaceRoot,
+            command,
+            event,
+            ...(hook.description !== undefined
+                ? { description: hook.description }
+                : {}),
+        }, opts.promptFn, opts.trustHomeOverride);
+        if (trustState === 'denied') {
+            results.push({
+                hookCommand: command.slice(0, 200),
+                event,
+                exitCode: -1,
+                stdout: '',
+                stderr: 'pugi hooks v2: hook denied by trust ledger',
+                decision: { decision: 'allow' },
+                elapsedMs: 0,
+                timedOut: false,
+                blocked: false,
+            });
+            continue;
+        }
+        const result = await executeHook({
+            hook,
+            payload,
+            ...(opts.env !== undefined ? { env: opts.env } : {}),
+        });
+        if (result.blocked) {
+            anyBlocked = true;
+        }
+        if (result.additionalContext) {
+            contextParts.push(result.additionalContext);
+        }
+        results.push(result);
+    }
+    return {
+        event,
+        results,
+        anyBlocked,
+        ...(contextParts.length > 0
+            ? { additionalContext: contextParts.join('\n\n') }
+            : {}),
+    };
+}
+//# sourceMappingURL=event-emitter.js.map

package/dist/core/hooks/v2/executor.js

@@ -0,0 +1,282 @@
+/**
+ * Pugi hooks v2 — executor (Wave 7 Phase 1).
+ *
+ * Spawns the hook command with the JSON payload on stdin, captures
+ * stdout / stderr, applies the timeout watchdog, and parses the
+ * decision protocol:
+ *
+ *   - Exit 0 + empty stdout                 -> { decision: 'allow' }
+ *   - Exit 0 + JSON `{"decision":"deny"}`   -> blocked
+ *   - Exit 0 + JSON `{"decision":"ask"}`    -> ask operator (TUI) /
+ *                                              refuse in headless
+ *   - Exit 0 + JSON `{"additionalContext"}` -> inject into next prompt
+ *   - Exit 1                                -> log warning, continue
+ *   - Exit 2                                -> block; stderr = reason
+ *                                              (Claude Code compat)
+ *
+ * Safety properties:
+ *   - 1 MiB output cap per stream (configurable). Misbehaving hooks
+ *     that emit unbounded output are killed.
+ *   - SIGTERM then SIGKILL with a 2 s grace window.
+ *   - Spawn failures never crash the parent.
+ *
+ * Brand voice: ASCII only.
+ */
+import { spawn } from 'node:child_process';
+import { HOOK_OUTPUT_CAP_BYTES_V2, } from './types.js';
+const SIGKILL_GRACE_MS = 2_000;
+/**
+ * Execute a single hook + return a typed result. Never throws — every
+ * failure mode (spawn error, timeout, stream cap) lands in a
+ * structured result so the caller can log + continue.
+ */
+export async function executeHook(opts) {
+    const { hook, payload, env, outputCapBytes = HOOK_OUTPUT_CAP_BYTES_V2 } = opts;
+    if (hook.type !== 'command') {
+        // Phase 1 only supports command-type hooks; other types resolve to
+        // an allow-decision so the rest of the pipeline keeps moving.
+        return makeUnsupportedTypeResult(hook);
+    }
+    const command = hook.command ?? '';
+    if (command.trim() === '') {
+        return {
+            hookCommand: '',
+            event: hook.event,
+            exitCode: -1,
+            stdout: '',
+            stderr: 'pugi hooks v2: command hook has empty command',
+            decision: { decision: 'allow' },
+            elapsedMs: 0,
+            timedOut: false,
+            blocked: false,
+        };
+    }
+    const startedAt = Date.now();
+    const timeoutMs = hook.timeoutMs ?? 5_000;
+    const stdinJson = JSON.stringify(payload);
+    const childEnv = {
+        ...(env ?? process.env),
+        PUGI_HOOK_PAYLOAD: stdinJson,
+        PUGI_HOOK_EVENT: payload.hook_event_name,
+        PUGI_HOOK_SESSION_ID: payload.session_id,
+        PUGI_HOOK_CWD: payload.cwd,
+        PUGI_HOOK_TRANSCRIPT_PATH: payload.transcript_path,
+        PUGI_HOOK_PERMISSION_MODE: payload.permission_mode,
+        PUGI_HOOK_TOOL_NAME: payload.tool_name ?? '',
+        PUGI_HOOK_AGENT_ID: payload.agent_id ?? '',
+        PUGI_HOOK_AGENT_TYPE: payload.agent_type ?? '',
+    };
+    return new Promise((resolvePromise) => {
+        const child = spawn('/bin/sh', ['-c', command], {
+            env: childEnv,
+            stdio: ['pipe', 'pipe', 'pipe'],
+        });
+        let stdout = '';
+        let stderr = '';
+        let timedOut = false;
+        let killedForCap = false;
+        let sigKillTimer;
+        const escalateKill = () => {
+            if (sigKillTimer)
+                return;
+            sigKillTimer = setTimeout(() => {
+                if (!child.killed)
+                    child.kill('SIGKILL');
+            }, SIGKILL_GRACE_MS);
+            if (sigKillTimer.unref)
+                sigKillTimer.unref();
+        };
+        const enforceCap = () => {
+            if (killedForCap)
+                return;
+            if (stdout.length + stderr.length <= outputCapBytes)
+                return;
+            killedForCap = true;
+            child.kill('SIGTERM');
+            escalateKill();
+        };
+        child.stdout?.on('data', (chunk) => {
+            if (killedForCap)
+                return;
+            stdout += chunk.toString('utf8');
+            enforceCap();
+        });
+        child.stderr?.on('data', (chunk) => {
+            if (killedForCap)
+                return;
+            stderr += chunk.toString('utf8');
+            enforceCap();
+        });
+        if (child.stdin) {
+            child.stdin.on('error', () => {
+                // EPIPE on a hook that ignores stdin is benign — payload also
+                // arrives via env var PUGI_HOOK_PAYLOAD.
+            });
+            child.stdin.end(stdinJson);
+        }
+        const timer = setTimeout(() => {
+            timedOut = true;
+            child.kill('SIGTERM');
+            escalateKill();
+        }, timeoutMs);
+        if (timer.unref)
+            timer.unref();
+        child.on('error', (error) => {
+            clearTimeout(timer);
+            if (sigKillTimer)
+                clearTimeout(sigKillTimer);
+            resolvePromise({
+                hookCommand: truncate(command, 200),
+                event: hook.event,
+                exitCode: -1,
+                stdout,
+                stderr: stderr || error.message,
+                decision: { decision: 'allow' },
+                elapsedMs: Date.now() - startedAt,
+                timedOut: false,
+                blocked: false,
+            });
+        });
+        child.on('close', (code, signal) => {
+            clearTimeout(timer);
+            if (sigKillTimer)
+                clearTimeout(sigKillTimer);
+            const exitCode = resolveExitCode(code, signal);
+            const decision = parseDecision(exitCode, stdout, stderr);
+            const blocked = isBlocked(exitCode, decision);
+            const blockReason = blocked ? blockReasonOf(exitCode, decision, stderr) : undefined;
+            const additionalContext = readAdditionalContext(decision);
+            resolvePromise({
+                hookCommand: truncate(command, 200),
+                event: hook.event,
+                exitCode,
+                stdout,
+                stderr,
+                decision,
+                elapsedMs: Date.now() - startedAt,
+                timedOut,
+                blocked,
+                ...(blockReason !== undefined ? { blockReason } : {}),
+                ...(additionalContext !== undefined ? { additionalContext } : {}),
+            });
+        });
+    });
+}
+function makeUnsupportedTypeResult(hook) {
+    return {
+        hookCommand: `<${hook.type}>`,
+        event: hook.event,
+        exitCode: 0,
+        stdout: '',
+        stderr: `pugi hooks v2: type '${hook.type}' is not supported in Phase 1`,
+        decision: { decision: 'allow' },
+        elapsedMs: 0,
+        timedOut: false,
+        blocked: false,
+    };
+}
+function resolveExitCode(code, signal) {
+    if (code !== null)
+        return code;
+    if (signal === 'SIGTERM')
+        return -15;
+    if (signal === 'SIGKILL')
+        return -9;
+    return -1;
+}
+/**
+ * Parse the JSON decision protocol. Falls back to `{ decision: 'allow' }`
+ * for any shape we do not recognize so a sloppy hook script does not
+ * silently start blocking tool dispatch.
+ *
+ * Exit-2 is the CC-compat shortcut: stderr is the block reason.
+ */
+export function parseDecision(exitCode, stdout, stderr) {
+    if (exitCode === 2) {
+        const reason = stderr.trim() || 'hook exited 2';
+        return { decision: 'deny', reason };
+    }
+    const trimmed = stdout.trim();
+    if (trimmed === '') {
+        return { decision: 'allow' };
+    }
+    // Try JSON first, but only when the stdout looks like a JSON object —
+    // a hook that prints `hello world` to stdout is not a decision.
+    if (!trimmed.startsWith('{')) {
+        return { decision: 'allow' };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(trimmed);
+    }
+    catch {
+        return { decision: 'allow' };
+    }
+    if (!parsed || typeof parsed !== 'object') {
+        return { decision: 'allow' };
+    }
+    const raw = parsed;
+    const decision = typeof raw.decision === 'string' ? raw.decision : undefined;
+    if (decision === 'deny') {
+        const reason = typeof raw.reason === 'string' && raw.reason.length > 0
+            ? raw.reason
+            : 'hook returned decision=deny';
+        return { decision: 'deny', reason };
+    }
+    if (decision === 'ask') {
+        const prompt = typeof raw.prompt === 'string' && raw.prompt.length > 0
+            ? raw.prompt
+            : 'hook requested operator approval';
+        return { decision: 'ask', prompt };
+    }
+    if (decision === 'allow' && typeof raw.additionalContext === 'string') {
+        return {
+            decision: 'allow',
+            additionalContext: raw.additionalContext,
+        };
+    }
+    if (decision === 'allow') {
+        return { decision: 'allow' };
+    }
+    if (typeof raw.additionalContext === 'string') {
+        return { additionalContext: raw.additionalContext };
+    }
+    return { decision: 'allow' };
+}
+function isBlocked(exitCode, decision) {
+    if (exitCode === 2)
+        return true;
+    if ('decision' in decision && decision.decision === 'deny')
+        return true;
+    return false;
+}
+function blockReasonOf(exitCode, decision, stderr) {
+    if (exitCode === 2) {
+        return stderr.trim() || 'hook exited 2';
+    }
+    if ('decision' in decision && decision.decision === 'deny') {
+        return decision.reason;
+    }
+    return 'hook blocked';
+}
+function readAdditionalContext(decision) {
+    if (!('decision' in decision)) {
+        return decision.additionalContext;
+    }
+    if (decision.decision === 'allow' && 'additionalContext' in decision) {
+        return decision.additionalContext;
+    }
+    return undefined;
+}
+function truncate(value, max) {
+    if (value.length <= max)
+        return value;
+    return `${value.slice(0, max - 3)}...`;
+}
+/** Convenience predicate exported for the event-emitter. */
+export function isToolEventV2(event) {
+    return (event === 'PreToolUse' ||
+        event === 'PostToolUse' ||
+        event === 'PostToolUseFailure');
+}
+//# sourceMappingURL=executor.js.map

package/dist/core/hooks/v2/index.js

@@ -0,0 +1,25 @@
+/**
+ * Pugi hooks v2 — public surface (Wave 7 Phase 1).
+ *
+ * The v2 surface is a Claude Code parity layer that lives alongside
+ * the existing `core/hooks/` MVP module. See `types.ts` for the
+ * design note explaining why both surfaces co-exist.
+ *
+ * Stable imports:
+ *
+ *   import {
+ *     loadHooksConfigV2,
+ *     fireHookEventV2,
+ *     type HookEventV2,
+ *   } from '../core/hooks/v2/index.js';
+ *
+ * Brand voice: ASCII only.
+ */
+export { ALL_HOOK_EVENTS_V2, DEFAULT_HOOK_TIMEOUT_MS_V2, HOOK_OUTPUT_CAP_BYTES_V2, MAX_HOOK_TIMEOUT_MS_V2, PHASE_1_HOOK_EVENTS, } from './types.js';
+export { HooksConfigV2, SUPPORTED_HOOK_TYPES_V2, defaultGlobalHooksPath, defaultProjectHooksPath, loadHooksConfigV2, } from './loader.js';
+export { compileMatcher, matches } from './matcher.js';
+export { executeHook, isToolEventV2, parseDecision } from './executor.js';
+export { ensureHookTrust, getHookTrust, listHookTrust, setHookTrust, trustKey, trustLedgerPath, } from './trust.js';
+export { fireHookEventV2 } from './event-emitter.js';
+export { firePostCompact, firePostToolUse, firePostToolUseFailure, firePreCompact, firePreToolUse, fireSessionEnd, fireSessionStart, fireStop, fireUserPromptSubmit, } from './lifecycle.js';
+//# sourceMappingURL=index.js.map

package/dist/core/hooks/v2/lifecycle.js

@@ -0,0 +1,104 @@
+/**
+ * Pugi hooks v2 - lifecycle integration helpers (Wave 7 Phase 1).
+ *
+ * High-level fire-and-forget wrappers that hide the loader + emitter
+ * plumbing from the callers. Each function:
+ *
+ *   1. Loads the merged hooks config for the workspace.
+ *   2. Returns early when the config is empty (zero-cost when no hooks).
+ *   3. Resolves the trust state (skipping denied hooks).
+ *   4. Fires every matching hook + returns the aggregated outcome.
+ *
+ * The lifecycle helpers are called from:
+ *   - `core/repl/session.ts` (SessionStart, SessionEnd, UserPromptSubmit,
+ *     Stop)
+ *   - `core/engine/tool-bridge.ts` (PreToolUse, PostToolUse,
+ *     PostToolUseFailure)
+ *   - `runtime/commands/compact.ts` (PreCompact, PostCompact)
+ *
+ * Best-effort: all helpers swallow exceptions so a misconfigured hook
+ * NEVER crashes the session boot path. Errors surface via
+ * `pugi hooks doctor` (Phase 2) and the per-session events log.
+ *
+ * Brand voice: ASCII only.
+ */
+import { fireHookEventV2 } from './event-emitter.js';
+import { loadHooksConfigV2 } from './loader.js';
+/** Empty no-op outcome. */
+function noopOutcome(event) {
+    return { event, results: [], anyBlocked: false };
+}
+/** Internal helper that loads + fires + swallows errors. */
+async function fireSafe(ctx, event, extra = {}) {
+    try {
+        const config = loadHooksConfigV2({
+            workspaceRoot: ctx.workspaceRoot,
+        });
+        if (config.isEmpty()) {
+            return noopOutcome(event);
+        }
+        return await fireHookEventV2({
+            config,
+            event,
+            sessionId: ctx.sessionId,
+            workspaceRoot: ctx.workspaceRoot,
+            transcriptPath: ctx.transcriptPath,
+            permissionMode: ctx.permissionMode,
+            ...(ctx.promptFn !== undefined ? { promptFn: ctx.promptFn } : {}),
+            ...extra,
+        });
+    }
+    catch {
+        // Lifecycle helpers MUST NOT crash the session. A malformed config
+        // surfaces via `pugi hooks doctor`.
+        return noopOutcome(event);
+    }
+}
+/** Fire `SessionStart` hooks. Never throws. */
+export function fireSessionStart(ctx) {
+    return fireSafe(ctx, 'SessionStart');
+}
+/** Fire `SessionEnd` hooks. Never throws. */
+export function fireSessionEnd(ctx) {
+    return fireSafe(ctx, 'SessionEnd');
+}
+/** Fire `Stop` hooks. Never throws. */
+export function fireStop(ctx) {
+    return fireSafe(ctx, 'Stop');
+}
+/** Fire `UserPromptSubmit` hooks. Never throws. */
+export function fireUserPromptSubmit(ctx, prompt) {
+    return fireSafe(ctx, 'UserPromptSubmit', { userPrompt: prompt });
+}
+/** Fire `PreToolUse` hooks. Never throws. Caller checks `anyBlocked`. */
+export function firePreToolUse(ctx) {
+    return fireSafe(ctx, 'PreToolUse', {
+        toolName: ctx.toolName,
+        toolInput: ctx.toolInput,
+    });
+}
+/** Fire `PostToolUse` hooks. Never throws. */
+export function firePostToolUse(ctx, toolResult) {
+    return fireSafe(ctx, 'PostToolUse', {
+        toolName: ctx.toolName,
+        toolInput: ctx.toolInput,
+        toolResult,
+    });
+}
+/** Fire `PostToolUseFailure` hooks. Never throws. */
+export function firePostToolUseFailure(ctx, toolError) {
+    return fireSafe(ctx, 'PostToolUseFailure', {
+        toolName: ctx.toolName,
+        toolInput: ctx.toolInput,
+        toolError,
+    });
+}
+/** Fire `PreCompact` hooks. Never throws. */
+export function firePreCompact(ctx) {
+    return fireSafe(ctx, 'PreCompact');
+}
+/** Fire `PostCompact` hooks. Never throws. */
+export function firePostCompact(ctx) {
+    return fireSafe(ctx, 'PostCompact');
+}
+//# sourceMappingURL=lifecycle.js.map