@kintsugi-ai/hook 0.1.0 → 0.2.0

package/src/index.ts

@@ -1,269 +0,0 @@
-#!/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

@@ -1,62 +0,0 @@
-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

@@ -1,40 +0,0 @@
-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

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