@pugi/cli 0.1.0-beta.9 → 0.1.0-beta.90

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

@@ -0,0 +1,125 @@
+/**
+ * Pugi hooks v2 - matcher grammar .
+ *
+ * The matcher string is compared against the tool name for tool events
+ * (PreToolUse / PostToolUse / PostToolUseFailure) and against the empty
+ * string for non-tool events (matcher is effectively ignored unless it
+ * is the wildcard).
+ *
+ * Grammar (evaluated in order):
+ *
+ *  1. wildcard `*`       - matches anything.
+ *  2. slash-regex literal - `/pattern/flags`. Flags subset of gimsuy.
+ *  3. prefix regex       - starts with `^` (e.g. `^mcp__`).
+ *  4. alternation        - `bash|grep|read`. Each side compiled
+ *                           recursively so `mcp__*|bash` works.
+ *  5. wildcard glob      - any string containing `*` not handled
+ *                           by the regex branches (e.g. `mcp__*`).
+ *  6. exact match        - case-sensitive equality.
+ *
+ * Operators in the wild write `^mcp__` expecting "starts with mcp__".
+ * The the upstream tool docs document this behaviour.
+ *
+ * Brand voice: ASCII only.
+ */
+// Constructed regexes used internally. We avoid `/.../` literals when
+// the pattern contains `${` because some TypeScript parser
+// configurations mis-treat the dollar-brace sequence inside a regex
+// character class as a template-literal opener.
+const REGEX_META_CHARS = new RegExp('[.*+?^${}()|[\\]\\\\]');
+const ESCAPE_REGEX_META = new RegExp('[.*+?^${}()|[\\]\\\\]', 'g');
+const SLASH_REGEX_LITERAL = /^\/(.+)\/([A-Za-z]*)$/;
+const ALLOWED_REGEX_FLAGS = /^[gimsuy]*$/;
+/**
+ * Compile a matcher string into a predicate over a single candidate.
+ * The candidate is the tool name for tool events, or `''` for
+ * non-tool events.
+ *
+ * Throws on a malformed regex literal so the operator sees a clear
+ * error at config-load time rather than at hook-fire time.
+ */
+export function compileMatcher(matcher) {
+    const trimmed = matcher.trim();
+    if (trimmed === '' || trimmed === '*') {
+        return () => true;
+    }
+    // 1. Slash-delimited regex literal.
+    const slashMatch = SLASH_REGEX_LITERAL.exec(trimmed);
+    if (slashMatch) {
+        const body = slashMatch[1] ?? '';
+        const flags = slashMatch[2] ?? '';
+        if (!ALLOWED_REGEX_FLAGS.test(flags)) {
+            throw new Error(`pugi hooks v2: matcher '${matcher}' has unsupported regex flags '${flags}'`);
+        }
+        try {
+            const re = new RegExp(body, flags);
+            return (candidate) => re.test(candidate);
+        }
+        catch (error) {
+            throw new Error(`pugi hooks v2: matcher '${matcher}' is not a valid regex: ${error.message}`);
+        }
+    }
+    // 2. Prefix-rooted regex shortcut: starts with `^` OR ends with `$`
+    //   AND no `|` (alternation handled below). Also a string
+    //   containing regex meta but no `|` and not pure wildcard glob.
+    const looksLikeRegex = (trimmed.startsWith('^') || trimmed.endsWith('$')) &&
+        !trimmed.includes('|');
+    const looksLikeMetaRegex = REGEX_META_CHARS.test(trimmed) &&
+        !trimmed.includes('|') &&
+        !isPureWildcardGlob(trimmed);
+    if (looksLikeRegex || looksLikeMetaRegex) {
+        try {
+            const re = new RegExp(trimmed);
+            return (candidate) => re.test(candidate);
+        }
+        catch (error) {
+            throw new Error(`pugi hooks v2: matcher '${matcher}' is not a valid regex: ${error.message}`);
+        }
+    }
+    // 3. Pipe alternation.
+    if (trimmed.includes('|')) {
+        const alts = trimmed
+            .split('|')
+            .map((s) => s.trim())
+            .filter((s) => s.length > 0);
+        const predicates = alts.map((alt) => compileMatcher(alt));
+        return (candidate) => predicates.some((p) => p(candidate));
+    }
+    // 4. Wildcard glob.
+    if (trimmed.includes('*')) {
+        const pattern = trimmed
+            .split('*')
+            .map((part) => escapeRegex(part))
+            .join('.*');
+        const re = new RegExp(`^${pattern}$`);
+        return (candidate) => re.test(candidate);
+    }
+    // 5. Exact match.
+    return (candidate) => candidate === trimmed;
+}
+/**
+ * True iff the matcher uses ONLY the wildcard sub-grammar (literal
+ * chars + `*`) - no other regex meta. Used to disambiguate `mcp__*`
+ * from `mcp__\d+`.
+ */
+function isPureWildcardGlob(matcher) {
+    for (const ch of matcher) {
+        if (ch === '*')
+            continue;
+        if (REGEX_META_CHARS.test(ch))
+            return false;
+    }
+    return matcher.includes('*');
+}
+function escapeRegex(value) {
+    return value.replace(ESCAPE_REGEX_META, '\\$&');
+}
+/**
+ * Quick predicate over a matcher + candidate. Compiles + executes in
+ * one shot. Use `compileMatcher` directly when the same matcher is
+ * applied to many candidates.
+ */
+export function matches(matcher, candidate) {
+    return compileMatcher(matcher)(candidate);
+}
+//# sourceMappingURL=matcher.js.map

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

@@ -0,0 +1,143 @@
+/**
+ * Pugi hooks v2 — trust ledger .
+ *
+ * Mirrors `core/mcp/trust.ts`. First-run interactive prompt fires
+ * before any hook executes; the operator's decision (allow / deny /
+ * always-allow) is persisted to `~/.pugi/hooks-trust.json` so the
+ * prompt does not re-fire on every REPL boot.
+ *
+ * Why a separate ledger from MCP trust:
+ *  - Hook commands run arbitrary shell as the operator. A trust
+ *    decision for a hook script does not transfer to MCP servers and
+ *    vice-versa; the surfaces should not collide.
+ *  - The hook ledger is keyed by command STRING (with the project
+ *    path scope) — two projects with the same `.pugi/hooks.json`
+ *    content trust independently. This prevents a malicious upstream
+ *    `pugi init` template from inheriting a trust decision from an
+ *    unrelated project on the same machine.
+ *
+ * Schema:
+ *  {
+ *    "schema": 1,
+ *    "entries": {
+ *      "<workspaceRoot>::<command-hash>": {
+ *        "state": "trusted" | "denied" | "pending",
+ *        "decidedAt": "<iso8601>",
+ *        "command": "<truncated command>",
+ *        "workspaceRoot": "<absolute path>"
+ *      }
+ *    }
+ *  }
+ *
+ * Brand voice: ASCII only.
+ */
+import { createHash } from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, resolve } from 'node:path';
+import { z } from 'zod';
+const TRUST_LEDGER_FILENAME = 'hooks-trust.json';
+const ledgerEntrySchema = z.object({
+    state: z.enum(['pending', 'trusted', 'denied']),
+    decidedAt: z.string().datetime(),
+    command: z.string().min(1),
+    workspaceRoot: z.string().min(1),
+});
+const ledgerSchema = z.object({
+    schema: z.literal(1).default(1),
+    entries: z.record(ledgerEntrySchema).default({}),
+});
+/** Override-friendly path resolution. Honors `PUGI_HOME`. */
+export function trustLedgerPath(homeOverride) {
+    const home = homeOverride ?? process.env.PUGI_HOME ?? resolve(homedir(), '.pugi');
+    return resolve(home, TRUST_LEDGER_FILENAME);
+}
+/** Stable key for a (workspace, command) pair. */
+export function trustKey(workspaceRoot, command) {
+    const hash = createHash('sha256')
+        .update(`${workspaceRoot}\0${command}`)
+        .digest('hex')
+        .slice(0, 16);
+    return `${workspaceRoot}::${hash}`;
+}
+function readLedger(homeOverride) {
+    const path = trustLedgerPath(homeOverride);
+    if (!existsSync(path)) {
+        return { schema: 1, entries: {} };
+    }
+    const raw = readFileSync(path, 'utf8');
+    if (raw.trim() === '') {
+        return { schema: 1, entries: {} };
+    }
+    return ledgerSchema.parse(JSON.parse(raw));
+}
+function writeLedger(ledger, homeOverride) {
+    const path = trustLedgerPath(homeOverride);
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, `${JSON.stringify(ledger, null, 2)}\n`, {
+        encoding: 'utf8',
+        mode: 0o600,
+    });
+}
+/**
+ * Look up the trust state for (workspace, command). Returns `pending`
+ * when no decision has been recorded.
+ */
+export function getHookTrust(workspaceRoot, command, homeOverride) {
+    const ledger = readLedger(homeOverride);
+    const entry = ledger.entries[trustKey(workspaceRoot, command)];
+    return entry ? entry.state : 'pending';
+}
+/** Persist a trust decision. */
+export function setHookTrust(workspaceRoot, command, state, homeOverride) {
+    const ledger = readLedger(homeOverride);
+    ledger.entries[trustKey(workspaceRoot, command)] = {
+        state,
+        decidedAt: new Date().toISOString(),
+        command: command.slice(0, 200),
+        workspaceRoot,
+    };
+    writeLedger(ledger, homeOverride);
+}
+/** Bulk listing for `pugi hooks trust list`. */
+export function listHookTrust(homeOverride) {
+    const ledger = readLedger(homeOverride);
+    return Object.values(ledger.entries)
+        .map((entry) => ({
+        workspaceRoot: entry.workspaceRoot,
+        command: entry.command,
+        state: entry.state,
+        decidedAt: entry.decidedAt,
+    }))
+        .sort((a, b) => a.workspaceRoot.localeCompare(b.workspaceRoot));
+}
+/**
+ * Resolve trust for a hook, prompting the operator on first encounter.
+ * `once` answers do NOT persist — the hook runs but the ledger stays
+ * pending so the next session re-prompts.
+ *
+ * The headless behaviour: when `promptFn` is undefined, the result is
+ * `denied`. Non-interactive sessions must NOT execute unknown hooks.
+ */
+export async function ensureHookTrust(input, promptFn, homeOverride) {
+    const known = getHookTrust(input.workspaceRoot, input.command, homeOverride);
+    if (known !== 'pending') {
+        return known;
+    }
+    if (!promptFn) {
+        // Headless mode without prompt = refuse for safety.
+        return 'denied';
+    }
+    const answer = await promptFn(input);
+    if (answer === 'trust') {
+        setHookTrust(input.workspaceRoot, input.command, 'trusted', homeOverride);
+        return 'trusted';
+    }
+    if (answer === 'deny') {
+        setHookTrust(input.workspaceRoot, input.command, 'denied', homeOverride);
+        return 'denied';
+    }
+    // `once` -> run this time but do NOT persist.
+    return 'trusted';
+}
+//# sourceMappingURL=trust.js.map

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

@@ -0,0 +1,86 @@
+/**
+ * Pugi hooks v2 — the upstream tool parity types .
+ *
+ * The v2 surface is a fresh implementation alongside the existing
+ * `core/hooks/` MVP module. It is NOT a replacement — both surfaces
+ * co-exist so the operator's legacy `~/.pugi/hooks-mvp.json` configs
+ * keep working while v2 grows the matcher grammar, the JSON decision
+ * protocol, and the per-project trust ledger.
+ *
+ * Why v2 instead of evolving v1 in-place:
+ *  - The v1 runner spawns hooks via `/bin/sh -c` with the payload in
+ *    env vars + stdin. v2 ships a richer stdin contract (schema_version,
+ *    transcript_path, cwd, permission_mode, agent_id, agent_type) that
+ *    would silently break v1 scripts if we mutated the existing surface.
+ *  - The v1 matcher is exact/star only. v2 adds regex, |-alternation,
+ *    and MCP wildcards. A clean module is easier to reason about than
+ *    a backward-compat branch inside the existing matcher.
+ *  - The v1 trust model is implicit (operator runs `pugi hooks doctor`
+ *    to surface config errors). v2 introduces a first-run interactive
+ *    prompt with a persisted ledger, matching MCP's trust pattern.
+ *
+ * Phase 1 wires 9 of the 31 events the upstream tool exposes. The remaining
+ * 22 land in Phase 2 along with hook chains. The type union below
+ * carries ALL 31 names so chains + future events compile against the
+ * same surface without churn.
+ *
+ * Brand voice: ASCII only, no emoji, no em-dashes.
+ */
+/** All 31 events the v2 surface understands. */
+export const ALL_HOOK_EVENTS_V2 = [
+    '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',
+];
+/**
+ * The 9 events emitted in Phase 1. A separate constant from
+ * `ALL_HOOK_EVENTS_V2` so callers can reason about "what fires today"
+ * without coupling to the entire reservation.
+ */
+export const PHASE_1_HOOK_EVENTS = [
+    'SessionStart',
+    'SessionEnd',
+    'UserPromptSubmit',
+    'PreToolUse',
+    'PostToolUse',
+    'PostToolUseFailure',
+    'Stop',
+    'PreCompact',
+    'PostCompact',
+];
+/** Default per-hook timeout in ms. */
+export const DEFAULT_HOOK_TIMEOUT_MS_V2 = 5_000;
+/** Hard upper bound on per-hook timeout. */
+export const MAX_HOOK_TIMEOUT_MS_V2 = 60_000;
+/** Hook stdout/stderr cap. Hooks emitting more are killed. */
+export const HOOK_OUTPUT_CAP_BYTES_V2 = 1024 * 1024;
+//# sourceMappingURL=types.js.map

package/dist/core/hooks/worktree-events.js

@@ -0,0 +1,158 @@
+/**
+ * Worktree lifecycle hooks - PUGI-487.
+ *
+ * Extends the existing hook lifecycle (`SessionStart` / `PreToolUse` /
+ * etc.) with two new events targeted at the user-facing `--worktree`
+ * flag:
+ *
+ *  - `WorktreeCreate`: fired when the operator runs
+ *    `pugi --worktree <name>` BEFORE git has touched the filesystem.
+ *    Receives a JSON document on stdin describing the requested
+ *    worktree. If the hook's stdout has a JSON envelope with a
+ *    `directory` field, the runtime uses that path instead of the
+ *    default `.claude/worktrees/<name>/` location. Non-zero exit aborts
+ *    worktree creation when `blocking: true` is set.
+ *
+ *  - `WorktreeRemove`: fired when the operator (or the cleanup sweep)
+ *    is about to delete a worktree. Receives a JSON document on stdin
+ *    describing the target. Non-zero exit aborts removal when
+ *    `blocking: true`.
+ *
+ * Both events follow the JSON-on-stdin pattern of the existing v2
+ * hook contract. The dispatcher is intentionally small because the
+ * heavy lifting (file load, schema validation, timeout enforcement)
+ * lives in `core/hooks/registry.ts` and `core/hooks/runner.ts`.
+ *
+ * Brand voice: ASCII only, no emoji, no banned words.
+ */
+import { spawnSync } from 'node:child_process';
+import { DEFAULT_HOOK_TIMEOUT_MS } from './registry.js';
+/**
+ * Fire every hook configured for the given worktree event. Returns the
+ * aggregated outcome including any directory override and the
+ * blocking-failure short circuit.
+ *
+ * Each hook receives the JSON payload on stdin and is expected to
+ * produce its response on stdout. Hooks are run sequentially (not in
+ * parallel) so that ordering across a multi-hook chain stays
+ * deterministic - the first directory override wins.
+ */
+export function fireWorktreeHooks(config, event, payload, options = {}) {
+    const entries = config.list(event);
+    const spawn = options.spawn ?? defaultSpawn;
+    const results = [];
+    let directoryOverride;
+    let anyBlocked = false;
+    const json = JSON.stringify(payload);
+    for (const entry of entries) {
+        const start = Date.now();
+        const ret = spawn(entry.command, {
+            input: json,
+            encoding: 'utf8',
+            shell: '/bin/sh',
+            timeout: entry.timeoutMs ?? DEFAULT_HOOK_TIMEOUT_MS,
+            maxBuffer: 1 * 1024 * 1024,
+        });
+        const elapsedMs = Date.now() - start;
+        const stdout = bufToString(ret.stdout);
+        const stderr = bufToString(ret.stderr);
+        const ok = ret.status === 0;
+        const blocked = !ok && entry.blocking === true;
+        if (blocked)
+            anyBlocked = true;
+        let dirOverride;
+        if (event === 'WorktreeCreate' && ok && stdout.length > 0) {
+            dirOverride = extractDirectoryOverride(stdout);
+            if (dirOverride && !directoryOverride) {
+                directoryOverride = dirOverride;
+            }
+        }
+        results.push({
+            command: entry.command.slice(0, 200),
+            exitCode: ret.status,
+            stdout,
+            stderr,
+            elapsedMs,
+            ok,
+            blocked,
+            ...(dirOverride ? { directoryOverride: dirOverride } : {}),
+        });
+        if (blocked)
+            break;
+    }
+    return {
+        event,
+        results,
+        anyBlocked,
+        ...(directoryOverride ? { directoryOverride } : {}),
+    };
+}
+/**
+ * Extract a `directory` override from hook stdout. Two accepted shapes:
+ *
+ *   1. JSON object with `{ "directory": "<path>" }`.
+ *   2. Bare path string (trimmed first non-empty line) when the hook
+ *      writes plain text. We accept the trimmed line as the override
+ *      ONLY if it looks like a non-flag path (no leading `-`, no `\n`,
+ *      no shell metacharacters).
+ *
+ * Returns undefined when no override is detected.
+ */
+export function extractDirectoryOverride(stdout) {
+    const trimmed = stdout.trim();
+    if (trimmed.length === 0)
+        return undefined;
+    if (trimmed.startsWith('{')) {
+        try {
+            const parsed = JSON.parse(trimmed);
+            if (parsed &&
+                typeof parsed === 'object' &&
+                !Array.isArray(parsed) &&
+                typeof parsed.directory === 'string') {
+                const dir = parsed.directory.trim();
+                if (isSafePathToken(dir))
+                    return dir;
+            }
+        }
+        catch {
+            // fall through to bare-path detection
+        }
+    }
+    const firstLine = trimmed.split(/\r?\n/, 1)[0] ?? '';
+    if (firstLine.length === 0)
+        return undefined;
+    if (isSafePathToken(firstLine))
+        return firstLine;
+    return undefined;
+}
+/**
+ * Cheap defence-in-depth check: a directory override must not look
+ * like a shell injection vector. The override is later validated for
+ * containment (the runtime refuses paths that escape the repo root),
+ * but rejecting obvious metacharacters here surfaces a cleaner error.
+ */
+function isSafePathToken(value) {
+    if (value.length === 0)
+        return false;
+    if (value.startsWith('-'))
+        return false;
+    if (/[;`$&|<>\n\r\t]/.test(value))
+        return false;
+    return true;
+}
+function defaultSpawn(command, options) {
+    const result = spawnSync(command, [], options);
+    return {
+        status: result.status,
+        stdout: result.stdout ?? '',
+        stderr: result.stderr ?? '',
+    };
+}
+function bufToString(v) {
+    if (v === undefined || v === null)
+        return '';
+    if (typeof v === 'string')
+        return v;
+    return v.toString('utf8');
+}
+//# sourceMappingURL=worktree-events.js.map

package/dist/core/image/renderer.js

@@ -0,0 +1,71 @@
+/**
+ * Inline image renderer for Pugi TUI .
+ *
+ * Wraps `terminal-image` (sindresorhus, MIT, ~150K weekly DLs) which
+ * detects iTerm2 / Kitty inline-image protocols, falls back к
+ * Sixel-capable terminals, и finally к chafa-style ANSI block art.
+ *
+ * What this module adds:
+ *  - File-size cap (default 8 MB) — guards against accidental
+ *    screen-fill from a 50 MB raw PNG drop
+ *  - Width/height defaults aligned with Pugi TUI column budget
+ *  - Safe degradation: returns a single-line `[image: <path>]`
+ *    placeholder when the host stream is not a TTY (e.g. piped output,
+ *    CI runs, log captures) instead of dumping raw escape sequences
+ *  - Format allowlist — refuses non-image extensions early без
+ *    decoding the entire file
+ *
+ * Pure-ish: no globals, no shared state. Caller owns the file path и
+ * decides where the rendered string lands (Ink Text node, raw stdout,
+ * fallback chat log).
+ */
+import { readFile, stat } from 'node:fs/promises';
+import path from 'node:path';
+import terminalImage from 'terminal-image';
+const DEFAULT_MAX_BYTES = 8 * 1024 * 1024;
+const DEFAULT_TUI_WIDTH = 80;
+const DEFAULT_TUI_HEIGHT = 30;
+const ALLOWED_EXTENSIONS = new Set([
+    '.png', '.jpg', '.jpeg', '.gif', '.webp', '.bmp', '.tiff', '.tif',
+]);
+export function isImagePath(filePath) {
+    return ALLOWED_EXTENSIONS.has(path.extname(filePath).toLowerCase());
+}
+export async function renderImageFile(filePath, options = {}) {
+    if (!isImagePath(filePath)) {
+        return placeholder(filePath, 'unsupported-format');
+    }
+    const ttyFlag = options.isTTY ?? process.stdout.isTTY ?? false;
+    if (!ttyFlag) {
+        return placeholder(filePath, 'not-a-tty');
+    }
+    const maxBytes = options.maxBytes ?? DEFAULT_MAX_BYTES;
+    if (maxBytes <= 0) {
+        throw new RangeError(`maxBytes must be > 0, got ${maxBytes}`);
+    }
+    try {
+        const stats = await stat(filePath);
+        if (stats.size > maxBytes) {
+            return placeholder(filePath, 'too-large');
+        }
+        const buf = await readFile(filePath);
+        const termOptions = {
+            width: options.width ?? DEFAULT_TUI_WIDTH,
+            height: options.height ?? DEFAULT_TUI_HEIGHT,
+            preserveAspectRatio: options.preserveAspectRatio ?? true,
+        };
+        const content = await terminalImage.buffer(buf, termOptions);
+        return { content, rendered: true, reason: 'rendered' };
+    }
+    catch {
+        return placeholder(filePath, 'read-error');
+    }
+}
+function placeholder(filePath, reason) {
+    return {
+        content: `[image: ${path.basename(filePath)}]`,
+        rendered: false,
+        reason,
+    };
+}
+//# sourceMappingURL=renderer.js.map