@kintsugi-ai/core 0.1.0

package/src/config.ts

@@ -0,0 +1,83 @@
+import { promises as fs } from 'fs';
+import path from 'path';
+import type { KintsugiConfig } from './types.js';
+
+export function getDefaultConfig(): KintsugiConfig {
+  return {
+    version: 1,
+    devServerUrl: 'http://localhost:3000',
+    viewport: { width: 1280, height: 720 },
+    thresholds: {
+      pixelDiffPercent: 0.1,
+      ssimScore: 0.98,
+      maxCheckLatencyMs: 5000,
+    },
+    llm: {
+      provider: 'claude',
+      model: 'claude-3-5-sonnet-20241022',
+      apiKeyEnvVar: 'ANTHROPIC_API_KEY',
+    },
+    classifier: {
+      enabled: true,
+      provider: 'kintsugi',
+      endpoint: process.env.KINTSUGI_API_URL ?? 'https://api.kintsugi.dev/v1',
+      model: 'kintsugi-hosted',
+      tokenEnvVar: 'KINTSUGI_API_KEY',
+      pixelDiffThreshold: 0.5,
+      confidenceThreshold: 0.7,
+      timeoutMs: 20000,
+    },
+    agent: {
+      type: 'auto',
+      maxRetries: 3,
+    },
+    recording: {
+      passive: true,
+      collectorPort: 4321,
+    },
+    uiFilePatterns: ['src/**/*.tsx', 'src/**/*.ts', 'src/**/*.jsx', 'src/**/*.js'],
+  };
+}
+
+export async function ensureKintsugiDir(projectDir: string): Promise<void> {
+  const kintsugiDir = path.join(projectDir, '.kintsugi');
+  const flowsDir = path.join(kintsugiDir, 'flows');
+  const recordingsDir = path.join(kintsugiDir, 'recordings');
+  
+  await fs.mkdir(kintsugiDir, { recursive: true });
+  await fs.mkdir(flowsDir, { recursive: true });
+  await fs.mkdir(recordingsDir, { recursive: true });
+}
+
+export async function loadConfig(projectDir: string): Promise<KintsugiConfig> {
+  const configPath = path.join(projectDir, '.kintsugi', 'config.json');
+  const defaultConfig = getDefaultConfig();
+  try {
+    const data = await fs.readFile(configPath, 'utf-8');
+    const userConfig = JSON.parse(data) as Partial<KintsugiConfig>;
+    const classifier = {
+      ...defaultConfig.classifier,
+      ...(userConfig.classifier ?? {}),
+    } as KintsugiConfig['classifier'];
+    // Migration: configs written before the provider field pointed at
+    // OpenAI-compatible endpoints (HF router). Keep them working unchanged.
+    if (userConfig.classifier && userConfig.classifier.provider === undefined) {
+      if (!classifier.endpoint.includes('kintsugi')) {
+        classifier.provider = 'openai-compatible';
+      }
+    }
+    return {
+      ...defaultConfig,
+      ...userConfig,
+      classifier,
+    } as KintsugiConfig;
+  } catch (error) {
+    return defaultConfig;
+  }
+}
+
+export async function saveConfig(projectDir: string, config: KintsugiConfig): Promise<void> {
+  await ensureKintsugiDir(projectDir);
+  const configPath = path.join(projectDir, '.kintsugi', 'config.json');
+  await fs.writeFile(configPath, JSON.stringify(config, null, 2), 'utf-8');
+}

package/src/domdiff.ts

@@ -0,0 +1,62 @@
+/**
+ * Line diff for Playwright aria snapshots (YAML). Produces a compact
+ * removed/added summary suitable as classifier input.
+ */
+
+const MAX_DIFF_LINES = 80;
+
+export function diffAriaSnapshots(baseline: string, current: string): string {
+  const a = baseline.split('\n');
+  const b = current.split('\n');
+
+  // LCS table (snapshots are small — a few hundred lines max)
+  const m = a.length, n = b.length;
+  const dp: number[][] = Array.from({ length: m + 1 }, () => new Array(n + 1).fill(0));
+  for (let i = m - 1; i >= 0; i--) {
+    for (let j = n - 1; j >= 0; j--) {
+      dp[i][j] = a[i] === b[j] ? dp[i + 1][j + 1] + 1 : Math.max(dp[i + 1][j], dp[i][j + 1]);
+    }
+  }
+
+  // Walk the table, grouping consecutive changes into hunks with nearest context
+  type Op = { type: ' ' | '-' | '+'; line: string };
+  const ops: Op[] = [];
+  let i = 0, j = 0;
+  while (i < m && j < n) {
+    if (a[i] === b[j]) { ops.push({ type: ' ', line: a[i] }); i++; j++; }
+    else if (dp[i + 1][j] >= dp[i][j + 1]) { ops.push({ type: '-', line: a[i] }); i++; }
+    else { ops.push({ type: '+', line: b[j] }); j++; }
+  }
+  while (i < m) { ops.push({ type: '-', line: a[i++] }); }
+  while (j < n) { ops.push({ type: '+', line: b[j++] }); }
+
+  // Emit only changed hunks (with 1 line of context), trimmed.
+  // Prefixes are words, not +/-, because aria snapshot lines themselves
+  // start with YAML list markers ("- ").
+  const out: string[] = [];
+  let changes = 0;
+  let lastContextIndex = -1;
+  for (let k = 0; k < ops.length; k++) {
+    if (ops[k].type === ' ') continue;
+    if (out.length > 0 && out[out.length - 1] !== '…' && ops[k - 1]?.type === ' ' && (k - 1) !== lastContextIndex) {
+      out.push('  ctx: ' + ops[k - 1].line);
+    }
+    while (k < ops.length && ops[k].type !== ' ') {
+      out.push((ops[k].type === '-' ? 'REMOVED: ' : 'ADDED:   ') + ops[k].line);
+      changes++;
+      k++;
+    }
+    if (k < ops.length) {
+      out.push('  ctx: ' + ops[k].line);
+      lastContextIndex = k;
+    }
+    out.push('');
+    if (out.length >= MAX_DIFF_LINES) {
+      out.push('… (diff truncated, more changes below)');
+      break;
+    }
+  }
+
+  if (changes === 0) return '(no line-level differences — change is purely visual/rendered)';
+  return out.join('\n').trim();
+}

package/src/feedback.ts

@@ -0,0 +1,64 @@
+import { DiffResult, type ComparisonResult } from './types.js';
+
+/**
+ * Fix-it feedback in the agent-facing format:
+ * "{flow name} is broken, aria diffs: [...], [sets of (new image and old image)],
+ *   suggested fixes: [fixes from the classifier per image pair]"
+ */
+export function formatAgentFeedback(result: ComparisonResult, flowName: string): string {
+  const lines: string[] = [];
+  lines.push(`${flowName} is broken.`);
+
+  // aria diffs per classified pair
+  lines.push('aria diffs:');
+  const classifications = result.classifications ?? [];
+  if (classifications.length === 0) {
+    lines.push('  (none captured — flow failed during replay; check selectors and page load)');
+  }
+  for (const c of classifications) {
+    lines.push(`  step ${c.step}:`);
+    for (const line of c.ariaDiff.split('\n')) {
+      lines.push(`    ${line}`);
+    }
+  }
+
+  // sets of (old image, new image)
+  lines.push('image pairs (old image | new image):');
+  if (classifications.length === 0) {
+    lines.push('  (none — flow failed during replay)');
+  }
+  for (const c of classifications) {
+    lines.push(`  step ${c.step}: ${c.oldImagePath ?? '(unavailable)'} | ${c.newImagePath ?? '(unavailable)'}`);
+  }
+
+  // suggested fixes — the classifier's reasoning per non-intentional pair
+  lines.push('suggested fixes:');
+  const regressions = classifications.filter(c => !c.intentional || c.confidence <= 0.7);
+  if (classifications.length === 0) {
+    lines.push('  - re-run the flow and verify the page loads; an element selector likely changed');
+  }
+  for (const c of regressions) {
+    lines.push(`  step ${c.step}: ${c.reasoning}`);
+  }
+  if (classifications.length > 0 && regressions.length === 0) {
+    lines.push('  - (classifier found no intentional-only pairs, but the flow still failed — see replay errors)');
+  }
+
+  if (result.diffImagePath) {
+    lines.push(`diff heatmap: ${result.diffImagePath}`);
+  }
+  return lines.join('\n');
+}
+
+export function formatUserSummary(result: ComparisonResult, flowName: string): string {
+  if (result.result === DiffResult.IDENTICAL) {
+    return `✅ Flow "${flowName}" passed. No visual differences detected.`;
+  }
+
+  let summary = `⚠️ Flow "${flowName}" resulted in ${result.result.toUpperCase()}.\n`;
+  if (result.failedStep !== undefined) {
+    summary += `Step ${result.failedStep} failed with a pixel difference of ${result.pixelDiffPercent.toFixed(2)}%.`;
+  }
+
+  return summary;
+}

package/src/flowid.ts

@@ -0,0 +1,14 @@
+/**
+ * Stable per-flow fingerprint used by the hosted API's flow gate: hashed from
+ * the flow name + step actions/selectors/urls — NOT from screenshots or
+ * timestamps — so replays count once and renames can't evade the limit.
+ */
+import { createHash } from 'node:crypto';
+import type { FlowStep } from './types.js';
+
+export function flowFingerprint(name: string, steps: FlowStep[]): string {
+  const canonical = JSON.stringify(
+    steps.map(s => [s.action, s.selector ?? null, s.url ?? null, s.value ?? null])
+  );
+  return createHash('sha256').update(`${name}\n${canonical}`).digest('hex').slice(0, 40);
+}

package/src/index.ts

@@ -0,0 +1,13 @@
+export * from './types.js';
+export * from './config.js';
+export * from './setupPrompt.js';
+export * from './baseline.js';
+export * from './capturer.js';
+export * from './comparator.js';
+export * from './feedback.js';
+export * from './recorder.js';
+export * from './benchmark.js';
+export * from './classifier.js';
+export * from './auth.js';
+export * from './flowid.js';
+export * from './domdiff.js';

package/src/recorder.ts

@@ -0,0 +1,96 @@
+import { chromium } from 'playwright';
+import { promises as fs } from 'fs';
+import path from 'path';
+import type { FlowRecording, FlowStep, FlowMetadata } from './types.js';
+
+export async function recordFlow(options: {
+  name: string;
+  url: string;
+  outputDir: string;
+  viewport?: { width: number; height: number };
+}): Promise<FlowRecording> {
+  const browser = await chromium.launch({ headless: false });
+  const context = await browser.newContext({ viewport: options.viewport || { width: 1280, height: 720 } });
+  const page = await context.newPage();
+  
+  const steps: FlowStep[] = [];
+  const startTime = Date.now();
+  
+  steps.push({ action: 'navigate', url: options.url });
+  await page.goto(options.url);
+  
+  await page.exposeFunction('trackAction', (action: any) => {
+    steps.push(action);
+  });
+  
+  await page.addInitScript(() => {
+    document.addEventListener('click', (e) => {
+        const target = e.target as HTMLElement;
+        let selector: string;
+        if (target.id) {
+            selector = `#${target.id}`;
+        } else if (target.getAttribute('data-testid')) {
+            selector = `[data-testid="${target.getAttribute('data-testid')}"]`;
+        } else if ((target as HTMLInputElement).name) {
+            selector = `${target.tagName.toLowerCase()}[name="${(target as HTMLInputElement).name}"]`;
+        } else if (target.textContent && target.textContent.trim().length > 0 && target.textContent.trim().length < 80 && target.children.length === 0) {
+            selector = `text=${target.textContent.trim()}`;
+        } else {
+            const parent = target.parentElement;
+            const siblings = parent ? Array.from(parent.children).filter(c => c.tagName === target.tagName) : [];
+            const idx = siblings.indexOf(target) + 1;
+            selector = siblings.length > 1 ? `${target.tagName.toLowerCase()}:nth-of-type(${idx})` : target.tagName.toLowerCase();
+        }
+        (window as any).trackAction({ action: 'click', selector });
+    }, true);
+
+    document.addEventListener('change', (e) => {
+        const target = e.target as HTMLInputElement;
+        let selector: string;
+        if (target.id) {
+            selector = `#${target.id}`;
+        } else if (target.getAttribute('data-testid')) {
+            selector = `[data-testid="${target.getAttribute('data-testid')}"]`;
+        } else if (target.name) {
+            selector = `${target.tagName.toLowerCase()}[name="${target.name}"]`;
+        } else {
+            selector = target.tagName.toLowerCase();
+        }
+        if (target.type === 'checkbox' || target.type === 'radio') {
+            (window as any).trackAction({ action: 'click', selector });
+        } else {
+            (window as any).trackAction({ action: 'type', selector, value: target.value });
+        }
+    }, true);
+  });
+
+  await page.waitForEvent('close', { timeout: 0 });
+  await browser.close();
+  
+  const duration = Date.now() - startTime;
+  
+  const metadata: FlowMetadata = {
+    name: options.name,
+    url: options.url,
+    viewport: options.viewport || { width: 1280, height: 720 },
+    recordedAt: new Date().toISOString(),
+    duration,
+    stepCount: steps.length,
+  };
+  
+  const recording: FlowRecording = {
+    metadata,
+    steps,
+    screenshotPaths: [],
+  };
+  
+  await fs.mkdir(options.outputDir, { recursive: true });
+  await fs.writeFile(path.join(options.outputDir, 'metadata.json'), JSON.stringify(metadata, null, 2));
+  await fs.writeFile(path.join(options.outputDir, 'steps.json'), JSON.stringify(steps, null, 2));
+  
+  return recording;
+}
+
+export function generateStepsFromScript(scriptPath: string): FlowStep[] {
+  return [];
+}

package/src/setupPrompt.ts

@@ -0,0 +1,26 @@
+/**
+ * The agent setup prompt — the single source of truth for the "initialize your
+ * flows" instruction users paste into claude / codex / agy after installing.
+ * Shared by `kintsugi init` (written to .kintsugi/setup-prompt.md) and the
+ * VS Code onboarding panel.
+ */
+export function getSetupPrompt(options: { devServerUrl?: string } = {}): string {
+  const url = options.devServerUrl || 'http://localhost:3000';
+  return `Record the visual regression baselines for this project using the kintsugi MCP tools.
+
+You have two groups of tools from the "kintsugi" MCP server:
+- Browser tools (Playwright): browser_navigate, browser_snapshot, browser_click, browser_type, browser_take_screenshot, ... — drive a real browser to explore the app.
+- Flow tools (Kintsugi): save_flow, capture_baseline, list_flows, check_flows — record and verify visual flows.
+
+Do this:
+1. If the dev server is not running yet, start it in the background (the project's dev script, e.g. npm run dev) and wait until ${url} responds.
+2. Explore the app with browser_navigate + browser_snapshot and identify the 3-5 most important user flows (e.g. landing page, navigation to a key section, the primary action such as signup, search, or checkout).
+3. For each flow, call save_flow with:
+   - name: a short snake_case identifier (e.g. "add_to_cart")
+   - steps: the ordered navigate / click / type / wait steps, using stable selectors ("text=Add to cart", "#email", "[data-testid=submit]") — never auto-generated or nth-child selectors. Keep each flow under 8 steps.
+4. Call capture_baseline for each flow — it replays the flow headlessly and stores the screenshots and aria snapshots Kintsugi will guard.
+5. Call check_flows to confirm every flow passes against the fresh baseline.
+6. Finish with a short summary: flow names, step counts, and anything you deliberately skipped.
+
+From now on, Kintsugi automatically replays these flows at the end of every agent turn and blocks the stop when a visual regression appears.`;
+}

package/src/types.ts

@@ -0,0 +1,144 @@
+/** Result classification from the comparison pipeline */
+export enum DiffResult {
+  IDENTICAL = 'identical',
+  MINOR = 'minor',
+  CHANGED = 'changed',
+  BROKEN = 'broken',
+  ERROR = 'error',
+  /** Big visual change the vision classifier accepted as intentional — not a regression */
+  INTENTIONAL = 'intentional',
+}
+
+/** A single step in a recorded user flow */
+export interface FlowStep {
+  action: 'navigate' | 'click' | 'type' | 'scroll' | 'wait' | 'screenshot';
+  selector?: string;
+  url?: string;
+  value?: string;
+  position?: { x: number; y: number };
+  timeout?: number;
+  description?: string;
+}
+
+/** Metadata about a recorded flow */
+export interface FlowMetadata {
+  name: string;
+  url: string;
+  viewport: { width: number; height: number };
+  recordedAt: string;
+  duration: number;
+  stepCount: number;
+}
+
+/** A complete flow recording with steps and baseline screenshots */
+export interface FlowRecording {
+  metadata: FlowMetadata;
+  steps: FlowStep[];
+  screenshotPaths: string[];
+  /** Baseline aria snapshots per step (semantic DOM state) */
+  ariaSnapshotPaths?: string[];
+  videoPath?: string;
+}
+
+/** Result of capturing the current UI state */
+export interface CaptureResult {
+  screenshots: Buffer[];
+  screenshotPaths: string[];
+  /** Playwright aria snapshot (semantic YAML) of the page after each step */
+  ariaSnapshots: string[];
+  videoPath?: string;
+  completedSteps: number;
+  totalSteps: number;
+  errors: string[];
+}
+
+/** Classifier output for one baseline/current screenshot pair */
+export interface StepClassification {
+  step: number;
+  intentional: boolean;
+  confidence: number;
+  /** One sentence from the classifier — the suggested fix when not intentional */
+  reasoning: string;
+  /** aria-snapshot diff for this pair */
+  ariaDiff: string;
+  oldImagePath?: string;
+  newImagePath?: string;
+}
+
+/** Result of comparing baseline vs current */
+export interface ComparisonResult {
+  result: DiffResult;
+  pixelDiffPercent: number;
+  ssimScore: number;
+  diffImagePath?: string;
+  semanticAnalysis?: string;
+  failedStep?: number;
+  stepResults: StepComparisonResult[];
+  /** Classifier detail for every step large enough to be classified */
+  classifications?: StepClassification[];
+  clipPath?: string;
+}
+
+/** Per-step comparison detail */
+export interface StepComparisonResult {
+  step: number;
+  pixelDiffPercent: number;
+  ssimScore: number;
+  result: DiffResult;
+  diffImagePath?: string;
+}
+
+/** Which transport classifyChange uses */
+export type ClassifierProvider =
+  /** Hosted kintsugi classifier API (default) — server picks the model */
+  | 'kintsugi'
+  /** Any OpenAI-compatible /chat/completions endpoint (HF router, Groq, local llama.cpp, …) */
+  | 'openai-compatible';
+
+/** Configuration for the change classifier (intentional vs regression) */
+export interface ClassifierConfig {
+  enabled: boolean;
+  provider: ClassifierProvider;
+  /**
+   * API base URL. For provider 'kintsugi': the hosted API (override with the
+   * KINTSUGI_API_URL env var, e.g. http://localhost:8787/v1 in dev). For
+   * 'openai-compatible': a base URL exposing POST {endpoint}/chat/completions.
+   */
+  endpoint: string;
+  /** Only used by the 'openai-compatible' provider; the kintsugi API picks its own model */
+  model: string;
+  tokenEnvVar: string;
+  /** Pixel-diff % above which the classifier is consulted */
+  pixelDiffThreshold: number;
+  /** Required confidence for an "intentional" verdict to be accepted */
+  confidenceThreshold: number;
+  timeoutMs: number;
+}
+
+/** Project-level Kintsugi configuration */
+export interface KintsugiConfig {
+  version: number;
+  devServerUrl: string;
+  viewport: { width: number; height: number };
+  thresholds: {
+    pixelDiffPercent: number;
+    ssimScore: number;
+    maxCheckLatencyMs: number;
+  };
+  llm: {
+    provider: 'claude' | 'openai';
+    model: string;
+    apiKeyEnvVar: string;
+  };
+  /** Change classifier: aria-snapshot diff + turn context → intentional or regression */
+  classifier: ClassifierConfig;
+  agent: {
+    type: 'auto' | 'claude-code' | 'codex' | 'agy';
+    maxRetries: number;
+  };
+  recording: {
+    passive: boolean;
+    collectorPort: number;
+  };
+  uiFilePatterns: string[];
+}

package/tsconfig.json

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