@pugi/cli 0.1.0-beta.99 → 1.0.0-alpha.2

package/dist/core/hooks/index.js

@@ -1,15 +0,0 @@
-/**
- * Public surface of the MVP hooks module ().
- *
- * Re-exports the registry, runner, and event types so callers can do
- *
- *  import { loadHooksConfig, fireHooks } from '../core/hooks/index.js';
- *
- * without reaching into individual files. See `events.ts` for the
- * scope note explaining why this MVP module co-exists with the older
- * `src/core/hooks.ts` surface.
- */
-export { DEFAULT_HOOK_TIMEOUT_MS, HooksConfig, MAX_HOOK_TIMEOUT_MS, defaultHooksMvpPath, isToolEvent, loadHooksConfig, matchesTool, } from './registry.js';
-export { fireHooks } from './runner.js';
-export { ALL_HOOK_EVENTS_V2, MVP_HOOK_EVENTS, } from './events.js';
-//# sourceMappingURL=index.js.map

package/dist/core/hooks/registry.js

@@ -1,216 +0,0 @@
-/**
- * Pugi hooks MVP — registry (, first pass).
- *
- * Reads `<home>/hooks-mvp.json` and validates its shape with Zod. The
- * file uses the the upstream tool-style nested config:
- *
- *  {
- *    "hooks": {
- *      "SessionStart": [{ "command": "echo session-start" }],
- *      "PreToolUse":  [{ "matcher": "bash", "command": "echo bash-pre", "blocking": true }]
- *    }
- *  }
- *
- * Schema constraints:
- *  - Each hook entry MUST have a `command` (non-empty string).
- *  - `matcher` is optional. Defaults to `*` (any tool / any payload).
- *    For tool events, `matcher` is compared against the tool name.
- *    For non-tool events (SessionStart), `matcher` is ignored.
- *  - `timeoutMs` is optional. Defaults to 30 000 ms (per task spec).
- *    Capped at 60 000 ms to prevent operator-defined deadlocks.
- *  - `blocking` is optional. When true AND the hook exits non-zero,
- *    the registry surfaces an `anyBlocked: true` outcome so the
- *    caller can refuse the originating action. Only honoured for
- *    `PreToolUse` in the MVP — other events log but do not block.
- *
- * Failure modes:
- *  - File missing -> the registry is `empty()`. `list()` returns []
- *    and `fire()` is a no-op. This matches the the upstream tool default
- *    (hooks are opt-in).
- *  - File present but invalid JSON / fails schema -> `load()` throws.
- *    The CLI surface (`pugi hooks doctor`) reports the error
- *    verbatim so the operator can fix the config.
- *
- * Brand voice: ASCII only, no emoji, no em-dashes.
- */
-import { existsSync, readFileSync } from 'node:fs';
-import { homedir } from 'node:os';
-import { resolve } from 'node:path';
-import { z } from 'zod';
-import { ALL_HOOK_EVENTS_V2 } from './events.js';
-/** Default per-hook timeout when the operator does not set `timeoutMs`. */
-export const DEFAULT_HOOK_TIMEOUT_MS = 30_000;
-/** Hard upper bound on `timeoutMs`. Prevents config-defined deadlocks. */
-export const MAX_HOOK_TIMEOUT_MS = 60_000;
-const hookEntrySchema = z
-    .object({
-    /**
-     * Tool-name matcher. `*` matches any tool. Plain strings match
-     * exactly (no glob in the MVP — fast-follow widens to glob). Ignored
-     * for non-tool events such as `SessionStart`.
-     */
-    matcher: z.string().min(1).optional(),
-    /** Shell command. Spawned via `/bin/sh -c <command>`. */
-    command: z.string().min(1),
-    /** Per-hook timeout override. Defaults to 30 000 ms. */
-    timeoutMs: z.number().int().positive().max(MAX_HOOK_TIMEOUT_MS).optional(),
-    /**
-     * When true, a non-zero exit code from this hook blocks the
-     * originating action (currently `PreToolUse` only). Other events
-     * log the exit but do not block.
-     */
-    blocking: z.boolean().optional(),
-})
-    .strict();
-const hookEventEnum = z.enum([
-    'SessionStart',
-    'PreToolUse',
-    'PostToolUse',
-    'UserPromptSubmit',
-    'Stop',
-    'SubagentStop',
-    'PreCompact',
-    'Notification',
-    // PUGI-487 - user-facing worktree lifecycle events.
-    'WorktreeCreate',
-    'WorktreeRemove',
-]);
-const hooksFileSchema = z
-    .object({
-    hooks: z.record(hookEventEnum, z.array(hookEntrySchema)).default({}),
-})
-    .strict();
-/** Default config file location — `~/.pugi/hooks-mvp.json`. */
-export function defaultHooksMvpPath(home) {
-    const root = home ?? process.env.PUGI_HOME ?? resolve(homedir(), '.pugi');
-    return resolve(root, 'hooks-mvp.json');
-}
-/**
- * In-memory snapshot of the operator's `hooks-mvp.json`. Construct
- * via `loadHooksConfig(path)` — `new HooksConfig()` is intentionally
- * not exported so all production code paths go through the loader.
- */
-export class HooksConfig {
-    path;
-    entries;
-    constructor(path, entries) {
-        this.path = path;
-        this.entries = entries;
-    }
-    /** Absolute path of the config file this snapshot was loaded from. */
-    configPath() {
-        return this.path;
-    }
-    /** All hooks declared for a given event. Returns [] when none. */
-    list(event) {
-        return this.entries[event] ?? [];
-    }
-    /**
-     * Hooks that match the (event, toolName?) tuple. For tool events
-     * (`PreToolUse`), `matcher` is compared against the tool name with
-     * `*` matching any. For non-tool events, all entries are returned
-     * regardless of `matcher`.
-     */
-    listMatching(event, toolName) {
-        const all = this.list(event);
-        if (!isToolEvent(event))
-            return all;
-        return all.filter((entry) => matchesTool(entry.matcher, toolName));
-    }
-    /** Flat list of (event, entry) pairs across every configured event. */
-    flatten() {
-        const out = [];
-        for (const event of ALL_HOOK_EVENTS_V2) {
-            for (const entry of this.list(event)) {
-                out.push({ event, entry });
-            }
-        }
-        return out;
-    }
-    /** True iff at least one hook is registered for any event. */
-    isEmpty() {
-        return this.flatten().length === 0;
-    }
-    /** A no-op snapshot used when the config file is absent. */
-    static empty(path) {
-        return new HooksConfig(path, {});
-    }
-}
-/**
- * Load + validate `hooks-mvp.json`. Returns a no-op snapshot when the
- * file is absent. Throws on invalid JSON or schema violations — the
- * caller is expected to surface the error to the operator via
- * `pugi hooks doctor`.
- *
- * Contract (non-null invariant): this function ALWAYS returns a
- * `HooksConfig` instance. It never returns `null` / `undefined`. When
- * the config file is missing, callers receive `HooksConfig.empty(path)`
- * — a truthy snapshot for which `isEmpty()` returns `true` and `list()`
- * returns `[]`. Callers may safely chain `.isEmpty()` without a null
- * guard. Asserted by `registry-empty.spec.ts`.
- */
-export function loadHooksConfig(pathOverride) {
-    const path = pathOverride ?? defaultHooksMvpPath();
-    if (!existsSync(path)) {
-        return HooksConfig.empty(path);
-    }
-    let raw;
-    try {
-        raw = readFileSync(path, 'utf8');
-    }
-    catch (error) {
-        throw new Error(`pugi hooks: cannot read ${path}: ${error.message}`);
-    }
-    let parsed;
-    try {
-        parsed = JSON.parse(raw);
-    }
-    catch (error) {
-        throw new Error(`pugi 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('.') || '<root>'} ${issue.message}`)
-            .join('; ');
-        throw new Error(`pugi hooks: ${path} failed schema validation: ${issues}`);
-    }
-    // Zod's `z.record(enum, value)` returns `Partial<Record<...>>` shape
-    // — keys that the operator did not include are `undefined`. Coerce
-    // explicitly into the same shape `HooksConfig` expects.
-    const entries = {};
-    for (const event of ALL_HOOK_EVENTS_V2) {
-        const list = result.data.hooks[event];
-        if (list && list.length > 0) {
-            entries[event] = list;
-        }
-    }
-    return new HooksConfig(path, entries);
-}
-/**
- * `isToolEvent(event)` -> true for events where `matcher` is compared
- * against the tool name. SessionStart / Stop / Notification / etc. do
- * not have an associated tool so matcher is ignored.
- */
-export function isToolEvent(event) {
-    return event === 'PreToolUse' || event === 'PostToolUse';
-}
-/**
- * Tool-name match grammar for the MVP. Intentionally narrow:
- *  - matcher missing or `*` -> matches any tool name (and the
- *    `bash`/`read`/... shape).
- *  - matcher === toolName   -> exact match.
- *
- * Fast-follow widens this to glob via `picomatch` so operators can
- * write `mcp__*` patterns. Deliberately not pulling in a glob lib for
- * the MVP — the narrow grammar is enough to land the surface and the
- * test matrix stays small.
- */
-export function matchesTool(matcher, toolName) {
-    if (!matcher || matcher === '*')
-        return true;
-    if (!toolName)
-        return false;
-    return matcher === toolName;
-}
-//# sourceMappingURL=registry.js.map

package/dist/core/hooks/runner.js

@@ -1,236 +0,0 @@
-/**
- * Pugi hooks MVP — runner (, first pass).
- *
- * Spawns the shell command declared in `hooks-mvp.json`, applies the
- * timeout watchdog, captures stdout / stderr, and surfaces a
- * structured result. Two events are wired in the MVP (SessionStart,
- * PreToolUse); the runner itself is event-agnostic so the fast-follow
- * PR can attach the remaining 6 events without changing this file.
- *
- * Safety properties:
- *  - 30 s default timeout (per task spec); SIGTERM then SIGKILL with
- *    a 2 s grace window.
- *  - 1 MiB output cap per stream — a misbehaving hook (`yes`) cannot
- *    OOM the parent CLI by buffering unbounded data.
- *  - Spawn failures are caught + logged; the session never crashes
- *    because of a missing binary or a syntax error in the command.
- *  - Hook errors are atomic-appended to `<workspaceRoot>/.pugi/logs/
- *    hooks.log`. Multiple sessions can write concurrently without
- *    interleaving because `appendFileSync` opens with O_APPEND.
- *
- * Brand voice: ASCII only.
- */
-import { spawn } from 'node:child_process';
-import { appendFileSync, existsSync, mkdirSync } from 'node:fs';
-import { resolve } from 'node:path';
-import { DEFAULT_HOOK_TIMEOUT_MS, isToolEvent, } from './registry.js';
-const HOOK_STREAM_CAP_BYTES = 1024 * 1024;
-const SIGKILL_GRACE_MS = 2_000;
-/**
- * Fire every matching hook for `event` sequentially. Sequential (not
- * parallel) is the intentional default — operators frequently chain
- * `git add` -> `eslint --fix` style hooks that would race otherwise.
- * Returns a `HookFireOutcome` with the per-invocation results.
- */
-export async function fireHooks(opts) {
-    const { config, event, payload, toolName, workspaceRoot, env } = opts;
-    const matching = config.listMatching(event, toolName);
-    if (matching.length === 0) {
-        return { event, results: [], anyBlocked: false };
-    }
-    const logger = workspaceRoot ? new HookLogger(workspaceRoot) : undefined;
-    const results = [];
-    let anyBlocked = false;
-    for (const entry of matching) {
-        const timeoutMs = entry.timeoutMs ?? DEFAULT_HOOK_TIMEOUT_MS;
-        const result = await executeOne(entry.command, payload, timeoutMs, env);
-        // Blocking semantics only honored for PreToolUse in the MVP.
-        // Other events can declare `blocking: true` but the runner just
-        // logs that intent — it does NOT short-circuit. The fast-follow
-        // PR threads PostToolUse + UserPromptSubmit blocking through.
-        const blockable = entry.blocking === true && event === 'PreToolUse';
-        const blocked = blockable && !result.ok;
-        if (blocked) {
-            anyBlocked = true;
-            result.blocked = true;
-            result.blockSentinel = `HOOK_BLOCKED: ${truncate(entry.command, 80)} exited ${result.exitCode}`;
-        }
-        if (logger && !result.ok) {
-            logger.recordFailure(event, entry.command, result);
-        }
-        results.push(result);
-    }
-    return { event, results, anyBlocked };
-}
-async function executeOne(command, payload, timeoutMs, env) {
-    const startedAt = Date.now();
-    return new Promise((resolvePromise) => {
-        const payloadJson = JSON.stringify(payload);
-        const childEnv = {
-            ...(env ?? process.env),
-            PUGI_HOOK_PAYLOAD: payloadJson,
-            PUGI_HOOK_EVENT: payload.event,
-            PUGI_HOOK_SESSION_ID: payload.sessionId,
-        };
-        const child = spawn('/bin/sh', ['-c', command], {
-            env: childEnv,
-            stdio: ['pipe', 'pipe', 'pipe'],
-        });
-        const state = {
-            stdout: '',
-            stderr: '',
-            killedForTimeout: false,
-            killedForStreamCap: false,
-        };
-        const escalateKill = () => {
-            if (state.sigKillTimer)
-                return;
-            state.sigKillTimer = setTimeout(() => {
-                if (!child.killed)
-                    child.kill('SIGKILL');
-            }, SIGKILL_GRACE_MS);
-            if (state.sigKillTimer.unref)
-                state.sigKillTimer.unref();
-        };
-        const enforceStreamCap = () => {
-            if (state.killedForStreamCap)
-                return;
-            if (state.stdout.length + state.stderr.length <= HOOK_STREAM_CAP_BYTES)
-                return;
-            state.killedForStreamCap = true;
-            child.kill('SIGTERM');
-            escalateKill();
-        };
-        child.stdout?.on('data', (chunk) => {
-            if (state.killedForStreamCap)
-                return;
-            state.stdout += chunk.toString('utf8');
-            enforceStreamCap();
-        });
-        child.stderr?.on('data', (chunk) => {
-            if (state.killedForStreamCap)
-                return;
-            state.stderr += chunk.toString('utf8');
-            enforceStreamCap();
-        });
-        // Best-effort stdin payload — hook scripts that want to read it can
-        // (e.g. `jq .`); scripts that ignore stdin will EPIPE on our write
-        // which we swallow because the env var carries the same data.
-        if (child.stdin) {
-            child.stdin.on('error', () => {
-                // EPIPE is benign — see above.
-            });
-            child.stdin.end(payloadJson);
-        }
-        const timer = setTimeout(() => {
-            state.killedForTimeout = true;
-            child.kill('SIGTERM');
-            escalateKill();
-        }, timeoutMs);
-        if (timer.unref)
-            timer.unref();
-        child.on('error', (error) => {
-            clearTimeout(timer);
-            if (state.sigKillTimer)
-                clearTimeout(state.sigKillTimer);
-            resolvePromise({
-                command: truncate(command, 200),
-                exitCode: -1,
-                stdoutBytes: state.stdout.length,
-                stderrBytes: state.stderr.length,
-                elapsedMs: Date.now() - startedAt,
-                ok: false,
-                blocked: false,
-                timedOut: false,
-                // No blockSentinel here — spawn errors are not the same as
-                // blocking-failure semantics. The caller logs them generically.
-            });
-        });
-        child.on('close', (code, signal) => {
-            clearTimeout(timer);
-            if (state.sigKillTimer)
-                clearTimeout(state.sigKillTimer);
-            let exitCode;
-            if (code !== null) {
-                exitCode = code;
-            }
-            else if (signal === 'SIGTERM') {
-                exitCode = -15;
-            }
-            else if (signal === 'SIGKILL') {
-                exitCode = -9;
-            }
-            else {
-                exitCode = -1;
-            }
-            const ok = exitCode === 0 &&
-                !state.killedForTimeout &&
-                !state.killedForStreamCap;
-            resolvePromise({
-                command: truncate(command, 200),
-                exitCode,
-                stdoutBytes: state.stdout.length,
-                stderrBytes: state.stderr.length,
-                elapsedMs: Date.now() - startedAt,
-                ok,
-                blocked: false,
-                timedOut: state.killedForTimeout,
-            });
-        });
-    });
-}
-/**
- * Append-only failure log at `<workspaceRoot>/.pugi/logs/hooks.log`.
- * Each line is a JSON record so log scrapers can `jq` over it.
- */
-class HookLogger {
-    path;
-    prepared = false;
-    constructor(workspaceRoot) {
-        this.path = resolve(workspaceRoot, '.pugi', 'logs', 'hooks.log');
-    }
-    recordFailure(event, command, result) {
-        this.prepareDir();
-        const line = JSON.stringify({
-            ts: new Date().toISOString(),
-            event,
-            command: truncate(command, 200),
-            exitCode: result.exitCode,
-            timedOut: result.timedOut,
-            elapsedMs: result.elapsedMs,
-            stdoutBytes: result.stdoutBytes,
-            stderrBytes: result.stderrBytes,
-            toolEvent: isToolEvent(event),
-        });
-        try {
-            appendFileSync(this.path, `${line}\n`, 'utf8');
-        }
-        catch {
-            // Logging is best-effort — the session must not crash when the
-            // disk is full or the directory is read-only. The runner has
-            // already returned the result; dropping the log line is the
-            // safe fallback.
-        }
-    }
-    prepareDir() {
-        if (this.prepared)
-            return;
-        const dir = resolve(this.path, '..');
-        if (!existsSync(dir)) {
-            try {
-                mkdirSync(dir, { recursive: true });
-            }
-            catch {
-                // ignored — appendFileSync will surface a fresh error on the
-                // write path, which we also swallow.
-            }
-        }
-        this.prepared = true;
-    }
-}
-function truncate(value, max) {
-    if (value.length <= max)
-        return value;
-    return `${value.slice(0, max - 3)}...`;
-}
-//# sourceMappingURL=runner.js.map

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

@@ -1,115 +0,0 @@
-/**
- * Pugi hooks v2 — event emitter .
- *
- * 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