@pugi/cli 0.1.0-alpha.10

package/dist/core/hooks.js

@@ -0,0 +1,415 @@
+import { spawn } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { existsSync, readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { resolve } from 'node:path';
+import { z } from 'zod';
+import { recordHookInvoked, recordHookResult, recordHookSkipped, } from './session.js';
+import { isTrustedWorkspace } from './trust.js';
+export const ALL_HOOK_EVENTS = [
+    'SessionStart',
+    'UserPromptSubmit',
+    'PreToolUse',
+    'PermissionRequest',
+    'PostToolUse',
+    'PostToolUseFailure',
+    'Stop',
+    'SessionEnd',
+];
+const hookEventSchema = z.enum([
+    'SessionStart',
+    'UserPromptSubmit',
+    'PreToolUse',
+    'PermissionRequest',
+    'PostToolUse',
+    'PostToolUseFailure',
+    'Stop',
+    'SessionEnd',
+]);
+const hookMatchSchema = z
+    .object({
+    tool: z.string().min(1).optional(),
+    permission: z.enum(['read', 'edit', 'bash', 'network', 'mcp', 'subagent']).optional(),
+    pathGlob: z.string().min(1).optional(),
+})
+    .strict();
+const hookDefinitionSchema = z
+    .object({
+    event: hookEventSchema,
+    match: hookMatchSchema.optional(),
+    run: z.string().min(1),
+    timeoutMs: z.number().int().positive().max(60_000).optional(),
+    onFailure: z.enum(['warn', 'block']).optional(),
+})
+    .strict();
+const hooksFileSchema = z
+    .object({
+    hooks: z.array(hookDefinitionSchema).default([]),
+})
+    .strict();
+const DEFAULT_TIMEOUT_MS = 5_000;
+const SIGKILL_GRACE_MS = 2_000;
+// Cap each captured stream at 1 MiB so a misbehaving hook (`yes`, `cat
+// /dev/urandom | base64`) cannot OOM the parent CLI by buffering
+// unbounded output between data events and the SIGTERM watchdog. 1 MiB
+// is generous headroom over realistic logger output while bounded.
+const HOOK_STREAM_CAP_BYTES = 1024 * 1024;
+export class HookRegistry {
+    options;
+    sources = [];
+    loaded = false;
+    /**
+     * Per-batch dedup memory. The caller is expected to call `resetBatch()`
+     * between independent event batches so hooks fire once per batch even
+     * if multiple identical events are emitted in tight succession from
+     * the same tool dispatch.
+     */
+    batchSeen = new Set();
+    trustedProjects = new Map();
+    constructor(options) {
+        this.options = options;
+    }
+    async load() {
+        this.sources.length = 0;
+        this.loaded = true;
+        const userPath = resolve(this.userHomeRoot(), 'hooks.json');
+        if (existsSync(userPath)) {
+            const userHooks = parseHooksFile(userPath);
+            this.sources.push({ origin: 'user', path: userPath, hooks: userHooks });
+        }
+        const projectPath = resolve(this.options.workspaceRoot, '.pugi/hooks.json');
+        if (existsSync(projectPath)) {
+            const trusted = await isTrustedWorkspace(this.options.workspaceRoot);
+            this.trustedProjects.set(this.options.workspaceRoot, trusted);
+            if (trusted) {
+                const projectHooks = parseHooksFile(projectPath);
+                this.sources.push({ origin: 'project', path: projectPath, hooks: projectHooks });
+            }
+        }
+    }
+    list(event) {
+        this.assertLoaded();
+        const all = this.sources.flatMap((source) => source.hooks);
+        return event ? all.filter((hook) => hook.event === event) : all;
+    }
+    /**
+     * Hooks that match the given event and context. The caller can use this
+     * to correlate hook definitions with `fire()` results positionally for
+     * downstream policy checks (e.g. PreToolUse blocking).
+     */
+    listMatching(ctx) {
+        return this.list(ctx.event).filter((hook) => matchesContext(hook, ctx));
+    }
+    /**
+     * Reset the per-batch dedup memory. Call between independent event
+     * batches (typically once per tool dispatch) so identical hook entries
+     * fire once per batch, not just once per session.
+     */
+    resetBatch() {
+        this.batchSeen.clear();
+    }
+    async fire(ctx) {
+        this.assertLoaded();
+        const candidates = this.listMatching(ctx);
+        // If the project hook file exists but the workspace is untrusted,
+        // emit a `hook.skipped: untrusted-project` once per `fire` so the
+        // audit log explains the gap. We only emit this if the user actually
+        // has a project hooks file on disk — otherwise there is nothing to
+        // skip.
+        const projectPath = resolve(this.options.workspaceRoot, '.pugi/hooks.json');
+        const projectHooksOnDisk = existsSync(projectPath);
+        const projectTrusted = this.trustedProjects.get(this.options.workspaceRoot) ?? false;
+        if (projectHooksOnDisk && !projectTrusted) {
+            this.recordSkipped(ctx, 'untrusted-project');
+        }
+        if (candidates.length === 0) {
+            return [];
+        }
+        const results = [];
+        for (const hook of candidates) {
+            const key = dedupKey(ctx.event, hook);
+            if (this.batchSeen.has(key)) {
+                this.recordSkipped(ctx, 'dedup');
+                results.push({
+                    ok: true,
+                    stdout: '',
+                    stderr: '',
+                    exitCode: 0,
+                    elapsedMs: 0,
+                    skipped: 'dedup',
+                });
+                continue;
+            }
+            this.batchSeen.add(key);
+            this.recordInvoked(ctx, hook);
+            const result = await executeHook(hook, ctx);
+            this.recordResult(ctx, result);
+            results.push(result);
+        }
+        return results;
+    }
+    assertLoaded() {
+        if (!this.loaded) {
+            throw new Error('HookRegistry.load() must be called before use');
+        }
+    }
+    userHomeRoot() {
+        const home = this.options.home ?? process.env.PUGI_HOME ?? resolve(homedir(), '.pugi');
+        return home;
+    }
+    recordInvoked(ctx, hook) {
+        if (!this.options.session)
+            return;
+        recordHookInvoked(this.options.session, {
+            event: ctx.event,
+            matchSummary: summariseMatch(hook.match),
+            runSummary: hook.run.slice(0, 200),
+        });
+    }
+    recordResult(ctx, result) {
+        if (!this.options.session)
+            return;
+        recordHookResult(this.options.session, {
+            event: ctx.event,
+            ok: result.ok,
+            exitCode: result.exitCode,
+            elapsedMs: result.elapsedMs,
+            stdoutLen: result.stdout.length,
+            stderrLen: result.stderr.length,
+        });
+    }
+    recordSkipped(ctx, reason) {
+        if (!this.options.session)
+            return;
+        recordHookSkipped(this.options.session, { event: ctx.event, reason });
+    }
+}
+/**
+ * Convenience helper for firing a SessionStart event from the CLI
+ * bootstrap path. Kept separate so the runtime entry point (cli.ts)
+ * does not need to construct a HookRegistry itself — that wiring lives
+ * in a follow-up PR by the TUI agent.
+ */
+export async function fireSessionStart(registry, ctx) {
+    return registry.fire({ ...ctx, event: 'SessionStart' });
+}
+function parseHooksFile(path) {
+    let raw;
+    try {
+        raw = readFileSync(path, 'utf8');
+    }
+    catch (error) {
+        throw new Error(`hooks: cannot read ${path}: ${error.message}`);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (error) {
+        throw new Error(`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('.')} ${issue.message}`)
+            .join('; ');
+        throw new Error(`hooks: ${path} failed schema validation: ${issues}`);
+    }
+    return result.data.hooks;
+}
+function matchesContext(hook, ctx) {
+    if (!hook.match)
+        return true;
+    const { tool, permission, pathGlob } = hook.match;
+    if (tool !== undefined) {
+        if (!ctx.tool)
+            return false;
+        if (!globMatch(tool, ctx.tool))
+            return false;
+    }
+    if (permission !== undefined) {
+        if (ctx.permission !== permission)
+            return false;
+    }
+    if (pathGlob !== undefined) {
+        if (!ctx.path)
+            return false;
+        if (!globMatch(pathGlob, ctx.path))
+            return false;
+    }
+    return true;
+}
+/**
+ * Tiny glob matcher: supports `*` (any chars except `/`) and `**` (any
+ * chars including `/`). Anchored at both ends. Plain strings without any
+ * wildcards must match exactly. We deliberately avoid pulling in a full
+ * glob lib here because the match grammar is intentionally narrow for M1.
+ */
+function globMatch(pattern, value) {
+    // Escape regex special chars except * and /, then translate ** and *
+    // into their regex equivalents. Order matters: handle ** before *.
+    const escaped = pattern.replace(/[.+?^${}()|[\]\\]/g, '\\$&');
+    const translated = escaped.replace(/\*\*/g, '<<DOUBLESTAR>>').replace(/\*/g, '[^/]*').replace(/<<DOUBLESTAR>>/g, '.*');
+    const regex = new RegExp(`^${translated}$`);
+    return regex.test(value);
+}
+function stableJsonHash(value) {
+    const stringified = stableStringify(value);
+    return createHash('sha256').update(stringified).digest('hex').slice(0, 16);
+}
+function stableStringify(value) {
+    if (value === null || typeof value !== 'object') {
+        return JSON.stringify(value);
+    }
+    if (Array.isArray(value)) {
+        return `[${value.map((v) => stableStringify(v)).join(',')}]`;
+    }
+    const obj = value;
+    const keys = Object.keys(obj).sort();
+    return `{${keys.map((key) => `${JSON.stringify(key)}:${stableStringify(obj[key])}`).join(',')}}`;
+}
+function dedupKey(event, hook) {
+    return `${event}:${stableJsonHash(hook.match ?? null)}:${stableJsonHash(hook.run)}`;
+}
+function summariseMatch(match) {
+    if (!match)
+        return '*';
+    const parts = [];
+    if (match.tool)
+        parts.push(`tool=${match.tool}`);
+    if (match.permission)
+        parts.push(`permission=${match.permission}`);
+    if (match.pathGlob)
+        parts.push(`path=${match.pathGlob}`);
+    return parts.length ? parts.join(',') : '*';
+}
+async function executeHook(hook, ctx) {
+    const timeoutMs = hook.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const startedAt = Date.now();
+    return new Promise((resolvePromise) => {
+        const payloadJson = JSON.stringify(ctx.payload ?? null);
+        const child = spawn('/bin/sh', ['-c', hook.run], {
+            env: {
+                ...process.env,
+                PUGI_HOOK_PAYLOAD: payloadJson,
+                PUGI_HOOK_EVENT: ctx.event,
+                PUGI_HOOK_SESSION_ID: ctx.sessionId,
+            },
+            stdio: ['pipe', 'pipe', 'pipe'],
+        });
+        let stdout = '';
+        let stderr = '';
+        let killedForTimeout = false;
+        let killedForStreamCap = false;
+        let sigKillTimer;
+        const enforceStreamCap = () => {
+            if (killedForStreamCap)
+                return;
+            if (stdout.length + stderr.length <= HOOK_STREAM_CAP_BYTES)
+                return;
+            killedForStreamCap = true;
+            child.kill('SIGTERM');
+            // Reuse the same SIGKILL escalation as the timeout path.
+            if (!sigKillTimer) {
+                sigKillTimer = setTimeout(() => {
+                    if (!child.killed)
+                        child.kill('SIGKILL');
+                }, SIGKILL_GRACE_MS);
+                if (sigKillTimer.unref)
+                    sigKillTimer.unref();
+            }
+        };
+        child.stdout?.on('data', (chunk) => {
+            if (killedForStreamCap)
+                return;
+            stdout += chunk.toString('utf8');
+            enforceStreamCap();
+        });
+        child.stderr?.on('data', (chunk) => {
+            if (killedForStreamCap)
+                return;
+            stderr += chunk.toString('utf8');
+            enforceStreamCap();
+        });
+        // Write the payload to stdin so hooks that prefer reading from stdin
+        // (e.g. `jq .`) work without depending on the env var. Hooks that
+        // do not consume stdin (e.g. `echo done`) close their end of the
+        // pipe immediately; writing then raises EPIPE which we swallow —
+        // payload-via-stdin is best-effort, not required.
+        if (child.stdin) {
+            child.stdin.on('error', () => {
+                // EPIPE / ECONNRESET when the child closed stdin before reading.
+                // Safe to ignore: PUGI_HOOK_PAYLOAD env var still carries the data.
+            });
+            child.stdin.end(payloadJson);
+        }
+        const timer = setTimeout(() => {
+            killedForTimeout = true;
+            child.kill('SIGTERM');
+            // Escalate to SIGKILL if the process refuses to exit.
+            sigKillTimer = setTimeout(() => {
+                if (!child.killed) {
+                    child.kill('SIGKILL');
+                }
+            }, SIGKILL_GRACE_MS);
+            if (sigKillTimer.unref)
+                sigKillTimer.unref();
+        }, timeoutMs);
+        if (timer.unref)
+            timer.unref();
+        child.on('error', (error) => {
+            clearTimeout(timer);
+            if (sigKillTimer)
+                clearTimeout(sigKillTimer);
+            resolvePromise({
+                ok: false,
+                stdout,
+                stderr: stderr || `hook spawn error: ${error.message}`,
+                exitCode: -1,
+                elapsedMs: Date.now() - startedAt,
+            });
+        });
+        child.on('close', (code, signal) => {
+            clearTimeout(timer);
+            if (sigKillTimer)
+                clearTimeout(sigKillTimer);
+            const elapsedMs = Date.now() - startedAt;
+            // When killed by signal, child_process reports code=null, signal=<name>.
+            // Translate to a negative numeric exit code so callers can read it
+            // uniformly (-15 for SIGTERM, -9 for SIGKILL). This matches the
+            // convention several Node tools (cross-spawn, execa) use.
+            let exitCode;
+            if (code !== null) {
+                exitCode = code;
+            }
+            else if (signal === 'SIGTERM') {
+                exitCode = -15;
+            }
+            else if (signal === 'SIGKILL') {
+                exitCode = -9;
+            }
+            else {
+                exitCode = -1;
+            }
+            // `ok` is true iff the hook exited cleanly (exit 0, not killed).
+            // Both `onFailure: 'warn'` and `onFailure: 'block'` produce ok=false
+            // on a non-zero exit — the difference is how the CALLER reacts.
+            // The caller reads `hook.onFailure` (via list()) to decide whether
+            // a non-ok result should warn or block the originating action.
+            // A stream-cap kill is also a failure: the hook produced too much
+            // output and we cannot trust whatever partial result we captured.
+            const ok = exitCode === 0 && !killedForTimeout && !killedForStreamCap;
+            const stderrFinal = killedForStreamCap
+                ? `${stderr}\nhook output exceeded ${HOOK_STREAM_CAP_BYTES} bytes; killed by stream cap.`
+                : stderr;
+            resolvePromise({
+                ok,
+                stdout,
+                stderr: stderrFinal,
+                exitCode,
+                elapsedMs,
+            });
+        });
+    });
+}
+//# sourceMappingURL=hooks.js.map

package/dist/core/index-store.js

@@ -0,0 +1,260 @@
+import { existsSync, readFileSync, readdirSync, statSync, writeFileSync } from 'node:fs';
+import { resolve, relative } from 'node:path';
+import { z } from 'zod';
+import { auditEventSchema } from '@pugi/sdk';
+/**
+ * `.pugi/index.json` — materialized session + artifact index.
+ *
+ * The append-only event log at `.pugi/events.jsonl` is the source of truth.
+ * `index.json` is a cached projection rebuilt on demand. Reads prefer the
+ * cached view; writes (idea/plan/build/review/handoff/resume) update both.
+ *
+ * Local-first invariant: this file is regenerable from events.jsonl plus
+ * filesystem scan of artifacts/handoffs. Deleting it never loses data.
+ */
+export const pugiIndexArtifactSchema = z.object({
+    id: z.string().min(1),
+    kind: z.enum([
+        'idea',
+        'plan',
+        'build',
+        'review',
+        'triple-review',
+        'resume',
+        'handoff',
+        'other',
+    ]),
+    path: z.string().min(1),
+    sessionId: z.string().min(1).nullable(),
+    createdAt: z.string().datetime(),
+    files: z.array(z.string()).default([]),
+});
+export const pugiIndexSessionSchema = z.object({
+    id: z.string().min(1),
+    startedAt: z.string().datetime(),
+    endedAt: z.string().datetime().nullable(),
+    commandCount: z.number().int().nonnegative(),
+    commands: z.array(z.object({
+        command: z.string().min(1),
+        status: z.enum(['started', 'success', 'error']),
+        timestamp: z.string().datetime(),
+    })),
+    artifactIds: z.array(z.string()).default([]),
+});
+export const pugiIndexSchema = z.object({
+    schema: z.literal(1),
+    updatedAt: z.string().datetime(),
+    artifacts: z.array(pugiIndexArtifactSchema),
+    sessions: z.array(pugiIndexSessionSchema),
+});
+export function indexPath(root) {
+    return resolve(root, '.pugi', 'index.json');
+}
+export function readIndex(root) {
+    const path = indexPath(root);
+    if (!existsSync(path))
+        return null;
+    try {
+        const raw = JSON.parse(readFileSync(path, 'utf8'));
+        const parsed = pugiIndexSchema.safeParse(raw);
+        return parsed.success ? parsed.data : null;
+    }
+    catch {
+        return null;
+    }
+}
+export function writeIndex(root, index) {
+    const path = indexPath(root);
+    writeFileSync(path, `${JSON.stringify(index, null, 2)}\n`, { encoding: 'utf8', mode: 0o600 });
+}
+export function emptyIndex() {
+    return {
+        schema: 1,
+        updatedAt: new Date().toISOString(),
+        artifacts: [],
+        sessions: [],
+    };
+}
+/**
+ * Rebuild the index from the event log + filesystem.
+ *
+ * This is the canonical recovery path: even if `.pugi/index.json` is
+ * deleted or corrupt, we can always reconstruct it.
+ */
+export function rebuildIndex(root) {
+    const events = readEvents(root);
+    const sessions = groupSessionsFromEvents(events);
+    const artifacts = scanArtifacts(root, events);
+    return {
+        schema: 1,
+        updatedAt: new Date().toISOString(),
+        artifacts,
+        sessions,
+    };
+}
+/**
+ * Append an artifact to the index, dedup by id. Touches `updatedAt`.
+ */
+export function upsertArtifact(index, artifact) {
+    const next = { ...index };
+    const existing = next.artifacts.findIndex((a) => a.id === artifact.id);
+    if (existing >= 0) {
+        next.artifacts = next.artifacts.map((a, i) => (i === existing ? artifact : a));
+    }
+    else {
+        next.artifacts = [...next.artifacts, artifact];
+    }
+    next.updatedAt = new Date().toISOString();
+    // Attach to session bucket if we know the sessionId.
+    if (artifact.sessionId) {
+        next.sessions = next.sessions.map((session) => session.id === artifact.sessionId
+            ? {
+                ...session,
+                artifactIds: session.artifactIds.includes(artifact.id)
+                    ? session.artifactIds
+                    : [...session.artifactIds, artifact.id],
+            }
+            : session);
+    }
+    return next;
+}
+export function readEvents(root) {
+    const eventsPath = resolve(root, '.pugi', 'events.jsonl');
+    if (!existsSync(eventsPath))
+        return [];
+    const raw = readFileSync(eventsPath, 'utf8');
+    const out = [];
+    for (const line of raw.split('\n')) {
+        const trimmed = line.trim();
+        if (!trimmed)
+            continue;
+        try {
+            const parsed = auditEventSchema.safeParse(JSON.parse(trimmed));
+            if (parsed.success)
+                out.push(parsed.data);
+        }
+        catch {
+            // Tolerate corrupt single lines so the rest of the log keeps loading.
+        }
+    }
+    return out;
+}
+function groupSessionsFromEvents(events) {
+    const map = new Map();
+    for (const event of events) {
+        if (event.type !== 'session')
+            continue;
+        let session = map.get(event.sessionId);
+        if (!session) {
+            session = {
+                id: event.sessionId,
+                startedAt: event.timestamp,
+                endedAt: null,
+                commandCount: 0,
+                commands: [],
+                artifactIds: [],
+            };
+            map.set(event.sessionId, session);
+        }
+        if (event.name === 'command_started' && event.command) {
+            session.commandCount += 1;
+            session.commands.push({
+                command: event.command,
+                status: 'started',
+                timestamp: event.timestamp,
+            });
+        }
+        else if (event.name === 'command_completed' && event.command) {
+            session.commands.push({
+                command: event.command,
+                status: event.status === 'error' ? 'error' : 'success',
+                timestamp: event.timestamp,
+            });
+            session.endedAt = event.timestamp;
+        }
+        else if (event.name === 'created') {
+            session.startedAt = event.timestamp;
+        }
+    }
+    return [...map.values()].sort((a, b) => b.startedAt.localeCompare(a.startedAt));
+}
+function scanArtifacts(root, events) {
+    const artifactsDir = resolve(root, '.pugi', 'artifacts');
+    const handoffsDir = resolve(root, '.pugi', 'handoffs');
+    const out = [];
+    // Map artifact dir names to sessionIds via tool_call events (best-effort).
+    // Artifact ids are timestamped slugs (e.g. `2026-05-22T03-51-37-260Z-triple-review`);
+    // tool_call records the `inputSummary` which often contains the prompt.
+    // We attach sessionId by mtime proximity to the closest tool_call event.
+    const toolCallTimes = events
+        .filter((e) => e.type === 'tool_call')
+        .map((e) => ({ sessionId: e.sessionId, timestamp: Date.parse(e.timestamp) }))
+        .filter((entry) => Number.isFinite(entry.timestamp));
+    if (existsSync(artifactsDir)) {
+        for (const entry of readdirSync(artifactsDir, { withFileTypes: true })) {
+            if (!entry.isDirectory())
+                continue;
+            const dir = resolve(artifactsDir, entry.name);
+            const files = readdirSync(dir, { withFileTypes: true })
+                .filter((file) => file.isFile())
+                .map((file) => file.name)
+                .sort();
+            const stat = statSync(dir);
+            out.push({
+                id: entry.name,
+                kind: inferKindFromFiles(files),
+                path: relative(root, dir),
+                sessionId: nearestSessionId(stat.mtimeMs, toolCallTimes),
+                createdAt: stat.mtime.toISOString(),
+                files,
+            });
+        }
+    }
+    if (existsSync(handoffsDir)) {
+        for (const entry of readdirSync(handoffsDir, { withFileTypes: true })) {
+            if (!entry.isFile() || !entry.name.endsWith('.json'))
+                continue;
+            const path = resolve(handoffsDir, entry.name);
+            const stat = statSync(path);
+            out.push({
+                id: entry.name.replace(/\.json$/, ''),
+                kind: 'handoff',
+                path: relative(root, path),
+                sessionId: nearestSessionId(stat.mtimeMs, toolCallTimes),
+                createdAt: stat.mtime.toISOString(),
+                files: [entry.name],
+            });
+        }
+    }
+    return out.sort((a, b) => b.createdAt.localeCompare(a.createdAt));
+}
+function inferKindFromFiles(files) {
+    if (files.some((f) => f === 'triple-review-request.json' || f === 'triple-review.md')) {
+        return 'triple-review';
+    }
+    if (files.includes('brief.md') && files.includes('execution-graph.json'))
+        return 'idea';
+    if (files.includes('plan.md'))
+        return 'plan';
+    if (files.includes('build.md'))
+        return 'build';
+    if (files.includes('review.md'))
+        return 'review';
+    if (files.includes('resume.md'))
+        return 'resume';
+    return 'other';
+}
+function nearestSessionId(mtimeMs, toolCallTimes) {
+    if (toolCallTimes.length === 0)
+        return null;
+    let best = null;
+    for (const entry of toolCallTimes) {
+        const delta = Math.abs(entry.timestamp - mtimeMs);
+        if (!best || delta < best.delta)
+            best = { sessionId: entry.sessionId, delta };
+    }
+    // Cap attribution to a 5-minute window so unrelated sessions do not collect
+    // each other's artifacts on long-lived repos.
+    return best && best.delta <= 5 * 60 * 1000 ? best.sessionId : null;
+}
+//# sourceMappingURL=index-store.js.map