@pugi/cli 0.1.0-beta.4 → 0.1.0-beta.40

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

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

@@ -0,0 +1,216 @@
+/**
+ * Pugi hooks v2 — config loader (Wave 7 Phase 1).
+ *
+ * Reads two sources and merges them with project-overrides-user
+ * precedence:
+ *
+ *   1. Global user config — `~/.pugi/hooks.json` (or `$PUGI_HOME/hooks.json`)
+ *   2. Project config     — `<workspaceRoot>/.pugi/hooks.json`
+ *
+ * Merge rule: the project file's hooks are CONCATENATED after the
+ * global file's hooks. When the runner walks the merged list, project
+ * hooks therefore run AFTER global hooks for the same event. The
+ * `precedence` term in the docs refers to overrides via matcher /
+ * event-type collision, NOT order-of-evaluation: a project hook on
+ * `PreToolUse|bash` shadows a global hook on the same event+matcher
+ * because the matcher engine deduplicates within the merged config.
+ *
+ * Failure modes:
+ *   - Missing files -> empty entries from that side. Both missing -> the
+ *     loader returns an empty config (`isEmpty()` true).
+ *   - Malformed JSON  -> the loader throws with the file path in the
+ *     error so the operator can find + fix it.
+ *   - Schema violation -> the loader throws with the Zod issue list.
+ *
+ * Brand voice: ASCII only.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { resolve } from 'node:path';
+import { z } from 'zod';
+import { DEFAULT_HOOK_TIMEOUT_MS_V2, MAX_HOOK_TIMEOUT_MS_V2, } from './types.js';
+const hookEventEnum = z.enum([
+    'SessionStart',
+    'SessionEnd',
+    'UserPromptSubmit',
+    'PreToolUse',
+    'PostToolUse',
+    'PostToolUseFailure',
+    'Stop',
+    'PreCompact',
+    'PostCompact',
+    'Notification',
+    'SubagentStart',
+    'SubagentStop',
+    'SubagentToolUse',
+    'PermissionRequest',
+    'PermissionGranted',
+    'PermissionDenied',
+    'PreEdit',
+    'PostEdit',
+    'PreWrite',
+    'PostWrite',
+    'PreRead',
+    'PostRead',
+    'PreBash',
+    'PostBash',
+    'McpServerConnect',
+    'McpServerDisconnect',
+    'McpToolCall',
+    'McpToolResult',
+    'AgentSpawn',
+    'AgentComplete',
+    'TaskCompleted',
+    'PromptInjection',
+]);
+const hookTypeEnum = z.enum(['command', 'http', 'mcp_tool', 'prompt', 'agent']);
+const hookConfigSchema = z
+    .object({
+    event: hookEventEnum,
+    matcher: z.string().min(1),
+    type: hookTypeEnum,
+    command: z.string().min(1).optional(),
+    timeoutMs: z
+        .number()
+        .int()
+        .positive()
+        .max(MAX_HOOK_TIMEOUT_MS_V2)
+        .optional(),
+    description: z.string().min(1).max(200).optional(),
+})
+    .strict()
+    .superRefine((entry, ctx) => {
+    if (entry.type === 'command' && !entry.command) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ['command'],
+            message: '`command` is required when `type === "command"`',
+        });
+    }
+});
+const hooksFileSchema = z
+    .object({
+    version: z.literal(1),
+    hooks: z.array(hookConfigSchema).default([]),
+})
+    .strict();
+/** Default global config location: `~/.pugi/hooks.json` (PUGI_HOME-aware). */
+export function defaultGlobalHooksPath(home) {
+    const root = home ?? process.env.PUGI_HOME ?? resolve(homedir(), '.pugi');
+    return resolve(root, 'hooks.json');
+}
+/** Default project config location: `<workspaceRoot>/.pugi/hooks.json`. */
+export function defaultProjectHooksPath(workspaceRoot) {
+    return resolve(workspaceRoot, '.pugi', 'hooks.json');
+}
+/**
+ * Immutable snapshot of the merged global + project config. Holds the
+ * source paths so audit + doctor surfaces can show "where did this come
+ * from".
+ */
+export class HooksConfigV2 {
+    globalPath;
+    projectPath;
+    globalHooks;
+    projectHooks;
+    constructor(globalPath, projectPath, globalHooks, projectHooks) {
+        this.globalPath = globalPath;
+        this.projectPath = projectPath;
+        this.globalHooks = globalHooks;
+        this.projectHooks = projectHooks;
+    }
+    /** Path of the global config file (may not exist on disk). */
+    globalConfigPath() {
+        return this.globalPath;
+    }
+    /** Path of the project config file (may not exist on disk). */
+    projectConfigPath() {
+        return this.projectPath;
+    }
+    /** All declared hooks (global first, project second). */
+    all() {
+        return [...this.globalHooks, ...this.projectHooks];
+    }
+    /** Hooks declared in the project config only. */
+    projectOnly() {
+        return [...this.projectHooks];
+    }
+    /** Hooks declared in the global config only. */
+    globalOnly() {
+        return [...this.globalHooks];
+    }
+    /** All hooks declared for a given event, project AFTER global. */
+    forEvent(event) {
+        return this.all().filter((h) => h.event === event);
+    }
+    /** True iff no hooks are configured. */
+    isEmpty() {
+        return this.globalHooks.length === 0 && this.projectHooks.length === 0;
+    }
+    /** Empty snapshot for when both files are absent. */
+    static empty(globalPath, projectPath) {
+        return new HooksConfigV2(globalPath, projectPath, [], []);
+    }
+}
+/**
+ * Load + validate the merged hooks config. Returns an empty config
+ * when neither file exists. Throws on JSON / schema errors with the
+ * source path in the message.
+ *
+ * Non-null invariant: returns a `HooksConfigV2` instance in all cases.
+ * Callers may chain `.isEmpty()` without a guard.
+ */
+export function loadHooksConfigV2(opts) {
+    const globalPath = opts.globalPathOverride ?? defaultGlobalHooksPath();
+    const projectPath = opts.projectPathOverride ?? defaultProjectHooksPath(opts.workspaceRoot);
+    const globalHooks = readOne(globalPath);
+    const projectHooks = readOne(projectPath);
+    return new HooksConfigV2(globalPath, projectPath, globalHooks, projectHooks);
+}
+function readOne(path) {
+    if (!existsSync(path)) {
+        return [];
+    }
+    let raw;
+    try {
+        raw = readFileSync(path, 'utf8');
+    }
+    catch (error) {
+        throw new Error(`pugi hooks v2: cannot read ${path}: ${error.message}`);
+    }
+    if (raw.trim() === '') {
+        return [];
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (error) {
+        throw new Error(`pugi hooks v2: ${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('.') || '<root>'} ${issue.message}`)
+            .join('; ');
+        throw new Error(`pugi hooks v2: ${path} failed schema validation: ${issues}`);
+    }
+    return materialize(result.data);
+}
+function materialize(data) {
+    // Apply the default timeout to every entry so downstream code can
+    // assume `timeoutMs` is always set.
+    return data.hooks.map((entry) => ({
+        ...entry,
+        timeoutMs: entry.timeoutMs ?? DEFAULT_HOOK_TIMEOUT_MS_V2,
+    }));
+}
+/** Re-exports for callers that want the literal enum values. */
+export const SUPPORTED_HOOK_TYPES_V2 = [
+    'command',
+    'http',
+    'mcp_tool',
+    'prompt',
+    'agent',
+];
+//# sourceMappingURL=loader.js.map