@kintsugi-ai/hook 0.1.0

package/src/context.ts

@@ -0,0 +1,80 @@
+import fs from 'node:fs';
+import type { HookInput } from './agent-detect.js';
+
+const MAX_CONTEXT_CHARS = 600;
+
+/**
+ * Best-effort extraction of "what was the agent asked to do" from the latest
+ * turn, to give the vision classifier intent context. Claude Code Stop
+ * payloads carry `transcript_path` (JSONL); Antigravity carries
+ * `transcriptPath`. Codex has none — return empty and let the classifier
+ * decide without context.
+ */
+export function extractTurnContext(input: HookInput): string {
+    const transcriptPath =
+        (typeof input.transcript_path === 'string' && input.transcript_path) ||
+        input.transcriptPath;
+    if (!transcriptPath) return '';
+
+    try {
+        const content = fs.readFileSync(transcriptPath, 'utf-8');
+        const userTexts: string[] = [];
+
+        for (const line of content.split('\n')) {
+            const trimmed = line.trim();
+            if (!trimmed) continue;
+            let entry: any;
+            try {
+                entry = JSON.parse(trimmed);
+            } catch {
+                continue;
+            }
+            const text = extractUserText(entry);
+            if (text) userTexts.push(text);
+        }
+
+        const context = userTexts.slice(-2).join(' | ');
+        return context.length > MAX_CONTEXT_CHARS
+            ? context.slice(0, MAX_CONTEXT_CHARS) + '…'
+            : context;
+    } catch (err: unknown) {
+        // ENOENT is expected when the agent has no transcript — everything else is unusual
+        const isNotFound = typeof err === 'object' && err !== null && 'code' in err && (err as { code: string }).code === 'ENOENT';
+        if (!isNotFound) {
+            console.warn(`kintsugi: failed to read transcript at ${transcriptPath}:`, err);
+        }
+        return '';
+    }
+}
+
+function extractUserText(entry: any): string | undefined {
+    // Claude Code transcript entries: { type: "user", message: { role: "user", content: string | [{type:"text",text}] } }
+    const message = entry?.message ?? entry;
+    const role = message?.role ?? entry?.type;
+    if (role !== 'user' && role !== 'human') return undefined;
+    // Skip tool results / interrupt notices — only real instructions help
+    if (entry?.type === 'tool_result') return undefined;
+
+    const content = message?.content;
+    if (typeof content === 'string' && content.trim()) {
+        return isNoise(content) ? undefined : content.trim();
+    }
+    if (Array.isArray(content)) {
+        const text = content
+            .filter((c: any) => c?.type === 'text' && typeof c.text === 'string')
+            .map((c: any) => c.text)
+            .join(' ')
+            .trim();
+        return text && !isNoise(text) ? text : undefined;
+    }
+    return undefined;
+}
+
+/** Filters transcript noise like system-injected reminders and empty interrupts. */
+function isNoise(text: string): boolean {
+    const t = text.trim();
+    if (!t) return true;
+    if (t.startsWith('<')) return true;
+    if (t === '[Request interrupted by user]') return true;
+    return false;
+}

package/src/escalation.ts

@@ -0,0 +1,60 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import type { ComparisonResult } from '@kintsugi-ai/core';
+
+export interface EscalationSignal {
+    flowName: string;
+    result: ComparisonResult;
+    oldVideoPath?: string;
+    newVideoPath?: string;
+    timestamp: string;
+    attempt: number;
+    maxAttempts: number;
+}
+
+function getEscalationFilePath(projectDir: string): string {
+    return path.join(projectDir, '.kintsugi', '.escalation.json');
+}
+
+/**
+ * Writes an escalation signal for the VS Code extension.
+ * @param projectDir The project directory.
+ * @param signal The escalation signal data.
+ */
+export async function writeEscalation(projectDir: string, signal: EscalationSignal): Promise<void> {
+    const filePath = getEscalationFilePath(projectDir);
+    const dir = path.dirname(filePath);
+    await fs.mkdir(dir, { recursive: true });
+    await fs.writeFile(filePath, JSON.stringify(signal, null, 2), 'utf-8');
+}
+
+/**
+ * Reads the current escalation signal.
+ * @param projectDir The project directory.
+ * @returns The current escalation signal or null if not found.
+ */
+export async function readEscalation(projectDir: string): Promise<EscalationSignal | null> {
+    const filePath = getEscalationFilePath(projectDir);
+    try {
+        const content = await fs.readFile(filePath, 'utf-8');
+        return JSON.parse(content) as EscalationSignal;
+    } catch {
+        return null;
+    }
+}
+
+/**
+ * Clears the escalation signal.
+ * @param projectDir The project directory.
+ */
+export async function clearEscalation(projectDir: string): Promise<void> {
+    const filePath = getEscalationFilePath(projectDir);
+    try {
+        await fs.unlink(filePath);
+    } catch (err: unknown) {
+        const isNotFound = typeof err === 'object' && err !== null && 'code' in err && (err as { code: string }).code === 'ENOENT';
+        if (!isNotFound) {
+            throw err;
+        }
+    }
+}

package/src/flow-matcher.ts

@@ -0,0 +1,13 @@
+import type { FlowMetadata } from '@kintsugi-ai/core';
+
+/**
+ * Determines which flows are affected by a file change.
+ * @param filePath The modified file path.
+ * @param flows The list of available flows.
+ * @returns Array of affected flow names.
+ */
+export function findAffectedFlows(filePath: string, flows: FlowMetadata[]): string[] {
+    // A conservative approach: for now, assume all flows might be affected by the UI change.
+    // Future enhancements can check if the file path matches explicit mappings.
+    return flows.map(f => f.name);
+}

package/src/index.ts

@@ -0,0 +1,269 @@
+#!/usr/bin/env node
+
+import fs from 'node:fs';
+import path from 'node:path';
+import {
+    loadConfig,
+    listFlows,
+    loadFlow,
+    captureCurrentState,
+    compareFlow,
+    formatAgentFeedback,
+    buildClassifierContext,
+    loadKintsugiEnv,
+    DiffResult,
+    type ComparisonResult,
+    type KintsugiConfig
+} from '@kintsugi-ai/core';
+import {
+    detectAgent,
+    outputFeedback,
+    exitWithResult,
+    type AgentType,
+    type HookInput
+} from './agent-detect.js';
+import { extractTurnContext } from './context.js';
+import { writeEscalation, readEscalation, clearEscalation } from './escalation.js';
+import { createLogger } from './logger.js';
+
+async function main() {
+    const earlyWarnings: string[] = [];
+
+    // Check command line arguments for explicit event flags (e.g. --event stop)
+    const isExplicitStopEvent = process.argv.includes('stop') ||
+                                process.argv.some(arg => arg.toLowerCase().includes('stop'));
+
+    let stdinData = '';
+    try {
+        stdinData = fs.readFileSync(0, 'utf-8');
+    } catch {
+        // stdin may not be available
+        earlyWarnings.push('could not read stdin (no piped hook payload?)');
+    }
+
+    let input: HookInput = {};
+    if (stdinData.trim()) {
+        try {
+            input = JSON.parse(stdinData);
+        } catch (e) {
+            earlyWarnings.push(`stdin is not valid JSON: ${(e as Error).message} preview=${stdinData.slice(0, 500)}`);
+        }
+    } else {
+        earlyWarnings.push('stdin was empty — agent sent no hook payload');
+    }
+
+    const agent = detectAgent(input);
+    // Stop events arrive as terminationReason (agy), hook_event_name: "Stop"
+    // (Claude Code), or the explicit --event stop flag in registered configs.
+    const eventName = typeof input.hook_event_name === 'string'
+        ? input.hook_event_name.toLowerCase()
+        : undefined;
+    const isStopEvent = isExplicitStopEvent || Boolean(input.terminationReason) || eventName === 'stop';
+
+    // Some agents (Antigravity/agy) run hooks with cwd set to their config
+    // dir (e.g. <workspace>/.agents) rather than the workspace root. Resolve
+    // the real project dir from the payload's workspacePaths when available.
+    const projectDir = input.workspacePaths?.[0] ?? process.cwd();
+    const log = createLogger(projectDir);
+    log.info('hook invoked', {
+        argv: process.argv.slice(2),
+        cwd: process.cwd(),
+        projectDir,
+        stdinBytes: stdinLength(),
+    });
+    for (const w of earlyWarnings) log.warn(w);
+    log.info('agent detected', { agent, isStopEvent, isExplicitStopEvent, inputKeys: Object.keys(input) });
+
+    if (!isStopEvent) {
+        // Kintsugi checks once per turn (Stop event), not on every file edit —
+        // per-edit checks would replay flows dozens of times per turn.
+        log.info('non-stop event — deferring visual check to turn end');
+        outputFeedback(agent, '', { isStopEvent: false, hasRegression: false });
+        process.exit(0);
+    }
+
+    await runTurnEndCheck(agent, input, projectDir, log);
+}
+
+interface FlowCheckOutcome {
+    flowName: string;
+    isRegression: boolean;
+    comparisonResult?: ComparisonResult;
+    oldPath?: string;
+    newPath?: string;
+}
+
+/**
+ * Turn-end visual check: verifies every recorded flow in parallel (each in
+ * its own browser context), classifies oversized diffs in parallel, and on a
+ * regression blocks the agent's stop with fix-it feedback until it passes or
+ * maxAttempts is reached.
+ */
+async function runTurnEndCheck(
+    agent: AgentType,
+    input: HookInput,
+    projectDir: string,
+    log: ReturnType<typeof createLogger>
+): Promise<void> {
+    // Pick up gitignored <project>/.kintsugi/.env before resolving the token
+    loadKintsugiEnv(projectDir);
+    const config: KintsugiConfig = await loadConfig(projectDir);
+    log.info('config loaded', { devServerUrl: config.devServerUrl, classifierModel: config.classifier.model });
+
+    // Shared builder (also used by `kintsugi check` and MCP) — bootstraps an
+    // anonymous hosted key on first use so the classifier is never silently dark.
+    const classifierContext = await buildClassifierContext(config, {
+        context: extractTurnContext(input),
+        logger: log,
+        bootstrapKey: true,
+        projectDir,
+    });
+
+    const flows = await listFlows(projectDir);
+    log.info('flows discovered', {
+        flowsDir: path.join(projectDir, '.kintsugi', 'flows'),
+        count: flows.length,
+        names: flows.map(f => f.name),
+    });
+
+    if (flows.length === 0) {
+        log.info('no recorded flows — nothing to check');
+        outputFeedback(agent, '', { isStopEvent: true, hasRegression: false });
+        process.exit(0);
+    }
+
+    const maxAttempts = config.agent.maxRetries;
+    const outcomes = await Promise.all(
+        flows.map(async flow => {
+            try {
+                return await checkFlow(flow.name, config, classifierContext, projectDir, log);
+            } catch (err) {
+                log.error('flow check crashed', { flowName: flow.name, error: (err as Error).message });
+                return { flowName: flow.name, isRegression: false } as FlowCheckOutcome;
+            }
+        })
+    );
+
+    const broken = outcomes.filter(o => o.isRegression);
+
+    if (broken.length === 0) {
+        // Clean pass — either nothing broke or the agent just fixed the
+        // previous regression. Either way the agent may stop.
+        log.info('turn-end check passed — clearing any previous escalation');
+        await clearEscalation(projectDir);
+        outputFeedback(agent, '', { isStopEvent: true, hasRegression: false });
+        process.exit(0);
+    }
+
+    // The fresh check above is the source of truth; only treat a pending
+    // escalation as "still unfixed" now that the current state is known broken.
+    const pendingEscalation = await readEscalation(projectDir);
+    if (pendingEscalation && pendingEscalation.attempt >= maxAttempts) {
+        log.info('max fix attempts reached — allowing agent to stop', {
+            flowName: pendingEscalation.flowName,
+            attempt: pendingEscalation.attempt,
+            maxAttempts,
+        });
+        await clearEscalation(projectDir);
+        outputFeedback(agent, '', { isStopEvent: true, hasRegression: false });
+        process.exit(0);
+    }
+
+    const first = broken[0];
+    const attempt = (pendingEscalation?.attempt || 0) + 1;
+    await writeEscalation(projectDir, {
+        flowName: first.flowName,
+        result: first.comparisonResult!,
+        oldVideoPath: first.oldPath ?? '',
+        newVideoPath: first.newPath ?? '',
+        timestamp: new Date().toISOString(),
+        attempt,
+        maxAttempts,
+    });
+
+    // Fix-it feedback covers every broken flow: aria diffs, image pairs, per-pair fixes
+    const combinedFeedback = broken
+        .map(o => formatAgentFeedback(o.comparisonResult!, o.flowName))
+        .join('\n\n');
+
+    log.warn('turn-end regression — blocking agent stop with feedback', {
+        flows: broken.map(b => b.flowName),
+        attempt,
+        maxAttempts,
+    });
+    outputFeedback(agent, combinedFeedback, { isStopEvent: true, hasRegression: true });
+    exitWithResult(agent, true);
+}
+
+/** Replays one flow and compares it against its baseline. */
+async function checkFlow(
+    flowName: string,
+    config: KintsugiConfig,
+    classifierContext: Awaited<ReturnType<typeof buildClassifierContext>>,
+    projectDir: string,
+    log: ReturnType<typeof createLogger>
+): Promise<FlowCheckOutcome> {
+    const flowRecord = await loadFlow(projectDir, flowName);
+    if (!flowRecord) {
+        log.warn('flow metadata listed but could not be loaded', { flowName });
+        return { flowName, isRegression: false };
+    }
+    log.info('checking flow', { flowName, stepCount: flowRecord.steps.length, baselineScreenshots: flowRecord.screenshotPaths.length });
+
+    const outputDir = path.join(projectDir, '.kintsugi', '.tmp', flowName);
+    fs.mkdirSync(outputDir, { recursive: true });
+
+    const currentState = await captureCurrentState({
+        url: config.devServerUrl,
+        flow: flowRecord,
+        outputDir,
+        viewport: config.viewport,
+    });
+    log.info('current state captured', { flowName, url: config.devServerUrl, screenshots: currentState.screenshots.length, errors: currentState.errors.length });
+
+    const comparisonResult = await compareFlow(flowRecord, currentState, { outputDir, classifier: classifierContext });
+    log.info('comparison finished', { flowName, result: comparisonResult.result });
+
+    // Any definite visual change (CHANGED) or broken capture is a regression —
+    // the baseline flow no longer matches the live page. INTENTIONAL means the
+    // classifier accepted the change.
+    const isRegression = comparisonResult.result !== DiffResult.IDENTICAL &&
+                         comparisonResult.result !== DiffResult.MINOR &&
+                         comparisonResult.result !== DiffResult.INTENTIONAL;
+
+    if (!isRegression) {
+        if (comparisonResult.result === DiffResult.INTENTIONAL) {
+            log.info('large visual change accepted as intentional by classifier', { flowName });
+        }
+        return { flowName, isRegression: false, comparisonResult };
+    }
+
+    log.warn('REGRESSION detected', { flowName, result: comparisonResult.result });
+    const failedIndex = comparisonResult.failedStep ?? 0;
+    return {
+        flowName,
+        isRegression: true,
+        comparisonResult,
+        oldPath: flowRecord.screenshotPaths[failedIndex] ?? flowRecord.screenshotPaths[0] ?? '',
+        newPath: currentState.screenshotPaths[failedIndex] ?? currentState.screenshotPaths[0] ?? '',
+    };
+}
+
+function stdinLength(): number {
+    try {
+        return fs.fstatSync(0).size;
+    } catch {
+        return -1;
+    }
+}
+
+main().catch((e) => {
+    try {
+        const log = createLogger(process.cwd());
+        log.error('hook crashed', e);
+    } catch { /* ignore */ }
+    // Exit non-zero so the agent knows something went wrong.
+    // Write a diagnostic to stderr for agents that capture it.
+    process.stderr.write(`kintsugi hook crashed: ${e instanceof Error ? e.message : String(e)}\n`);
+    process.exit(1);
+});

package/src/logger.ts

@@ -0,0 +1,62 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+/**
+ * Debug logging for the kintsugi hook.
+ *
+ * The #1 failure mode for agent hooks is silent early-exit: the hook runs,
+ * decides "nothing to do", and exits 0 without any trace. To debug why a
+ * regression was NOT caught, we log every decision point to
+ * `<projectDir>/.kintsugi/logs/hook.log` (always) and to stderr (when
+ * KINTSUGI_DEBUG=1, since agent CLIs may otherwise swallow or misrender
+ * unexpected stderr).
+ */
+
+const LOG_DIRNAME = path.join('.kintsugi', 'logs');
+const LOG_FILENAME = 'hook.log';
+
+export function createLogger(projectDir: string) {
+    const debugToStderr = process.env.KINTSUGI_DEBUG === '1';
+    const logPath = path.join(projectDir, LOG_DIRNAME, LOG_FILENAME);
+
+    function write(line: string): void {
+        const entry = `[${new Date().toISOString()}] ${line}\n`;
+        try {
+            fs.mkdirSync(path.dirname(logPath), { recursive: true });
+            fs.appendFileSync(logPath, entry);
+        } catch {
+            // Never let logging break the hook
+        }
+        if (debugToStderr) {
+            process.stderr.write(`[kintsugi-hook] ${entry}`);
+        }
+    }
+
+    return {
+        info: (message: string, data?: unknown) => {
+            write(data === undefined ? message : `${message} ${safeStringify(data)}`);
+        },
+        warn: (message: string, data?: unknown) => {
+            write(`WARN: ${data === undefined ? message : `${message} ${safeStringify(data)}`}`);
+        },
+        error: (message: string, error?: unknown) => {
+            write(`ERROR: ${message}${error ? ` ${formatError(error)}` : ''}`);
+        },
+        logPath,
+    };
+}
+
+function safeStringify(data: unknown): string {
+    try {
+        return JSON.stringify(data);
+    } catch {
+        return String(data);
+    }
+}
+
+function formatError(error: unknown): string {
+    if (error instanceof Error) {
+        return `${error.message}\n${error.stack ?? ''}`;
+    }
+    return safeStringify(error);
+}

package/src/ui-file-detector.ts

@@ -0,0 +1,40 @@
+import path from 'node:path';
+
+export const DEFAULT_UI_PATTERNS = [
+    '**/*.tsx', '**/*.jsx', '**/*.vue', '**/*.svelte', 
+    '**/*.html', '**/*.css', '**/*.scss'
+];
+
+const UI_EXTENSIONS = new Set(['.tsx', '.jsx', '.vue', '.svelte', '.html', '.css', '.scss']);
+const NON_UI_SUBSTRINGS = ['.test.', '.spec.', '.config.', '/test/', '/tests/'];
+
+/**
+ * Detects if a file is a UI file that might require visual regression testing.
+ * @param filePath The path to the modified file.
+ * @param patterns Optional array of glob patterns to match against.
+ * @returns True if the file is considered a UI file.
+ */
+export function isUIFile(filePath: string, patterns: string[] = DEFAULT_UI_PATTERNS): boolean {
+    const ext = path.extname(filePath).toLowerCase();
+    
+    for (const sub of NON_UI_SUBSTRINGS) {
+        if (filePath.includes(sub)) {
+            return false;
+        }
+    }
+
+    if (UI_EXTENSIONS.has(ext)) {
+        return true;
+    }
+
+    // Simplified pattern matching if not matched by extension
+    for (const pattern of patterns) {
+        // Extract extension from glob patterns like '**/*.tsx' or '*.css'
+        const extMatch = pattern.match(/\*\.([a-zA-Z0-9]+)$/);
+        if (extMatch && ext === '.' + extMatch[1]) {
+            return true;
+        }
+    }
+
+    return false;
+}

package/tsconfig.json

@@ -0,0 +1,8 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "./dist",
+    "rootDir": "./src"
+  },
+  "include": ["src/**/*"]
+}