@pugi/cli 0.1.0-beta.98 → 1.0.0-alpha.1

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

@@ -1,282 +0,0 @@
-/**
- * Pugi hooks v2 — executor .
- *
- * 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
- *                                             (the upstream tool 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 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

@@ -1,25 +0,0 @@
-/**
- * Pugi hooks v2 — public surface .
- *
- * The v2 surface is a the upstream tool 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

@@ -1,104 +0,0 @@
-/**
- * Pugi hooks v2 - lifecycle integration helpers .
- *
- * 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

@@ -1,216 +0,0 @@
-/**
- * Pugi hooks v2 — config loader .
- *
- * 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