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

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

@@ -1,125 +0,0 @@
-/**
- * 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

@@ -1,143 +0,0 @@
-/**
- * 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

@@ -1,86 +0,0 @@
-/**
- * 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

@@ -1,158 +0,0 @@
-/**
- * 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