@kintsugi-ai/core 0.1.0

package/dist/recorder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"recorder.js","sourceRoot":"","sources":["../src/recorder.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AACtC,OAAO,EAAE,QAAQ,IAAI,EAAE,EAAE,MAAM,IAAI,CAAC;AACpC,OAAO,IAAI,MAAM,MAAM,CAAC;AAGxB,MAAM,CAAC,KAAK,UAAU,UAAU,CAAC,OAKhC;IACC,MAAM,OAAO,GAAG,MAAM,QAAQ,CAAC,MAAM,CAAC,EAAE,QAAQ,EAAE,KAAK,EAAE,CAAC,CAAC;IAC3D,MAAM,OAAO,GAAG,MAAM,OAAO,CAAC,UAAU,CAAC,EAAE,QAAQ,EAAE,OAAO,CAAC,QAAQ,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,EAAE,CAAC,CAAC;IACzG,MAAM,IAAI,GAAG,MAAM,OAAO,CAAC,OAAO,EAAE,CAAC;IAErC,MAAM,KAAK,GAAe,EAAE,CAAC;IAC7B,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IAE7B,KAAK,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,UAAU,EAAE,GAAG,EAAE,OAAO,CAAC,GAAG,EAAE,CAAC,CAAC;IACrD,MAAM,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IAE7B,MAAM,IAAI,CAAC,cAAc,CAAC,aAAa,EAAE,CAAC,MAAW,EAAE,EAAE;QACvD,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IACrB,CAAC,CAAC,CAAC;IAEH,MAAM,IAAI,CAAC,aAAa,CAAC,GAAG,EAAE;QAC5B,QAAQ,CAAC,gBAAgB,CAAC,OAAO,EAAE,CAAC,CAAC,EAAE,EAAE;YACrC,MAAM,MAAM,GAAG,CAAC,CAAC,MAAqB,CAAC;YACvC,IAAI,QAAgB,CAAC;YACrB,IAAI,MAAM,CAAC,EAAE,EAAE,CAAC;gBACZ,QAAQ,GAAG,IAAI,MAAM,CAAC,EAAE,EAAE,CAAC;YAC/B,CAAC;iBAAM,IAAI,MAAM,CAAC,YAAY,CAAC,aAAa,CAAC,EAAE,CAAC;gBAC5C,QAAQ,GAAG,iBAAiB,MAAM,CAAC,YAAY,CAAC,aAAa,CAAC,IAAI,CAAC;YACvE,CAAC;iBAAM,IAAK,MAA2B,CAAC,IAAI,EAAE,CAAC;gBAC3C,QAAQ,GAAG,GAAG,MAAM,CAAC,OAAO,CAAC,WAAW,EAAE,UAAW,MAA2B,CAAC,IAAI,IAAI,CAAC;YAC9F,CAAC;iBAAM,IAAI,MAAM,CAAC,WAAW,IAAI,MAAM,CAAC,WAAW,CAAC,IAAI,EAAE,CAAC,MAAM,GAAG,CAAC,IAAI,MAAM,CAAC,WAAW,CAAC,IAAI,EAAE,CAAC,MAAM,GAAG,EAAE,IAAI,MAAM,CAAC,QAAQ,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;gBAC7I,QAAQ,GAAG,QAAQ,MAAM,CAAC,WAAW,CAAC,IAAI,EAAE,EAAE,CAAC;YACnD,CAAC;iBAAM,CAAC;gBACJ,MAAM,MAAM,GAAG,MAAM,CAAC,aAAa,CAAC;gBACpC,MAAM,QAAQ,GAAG,MAAM,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,OAAO,KAAK,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;gBACrG,MAAM,GAAG,GAAG,QAAQ,CAAC,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;gBACzC,QAAQ,GAAG,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,MAAM,CAAC,OAAO,CAAC,WAAW,EAAE,gBAAgB,GAAG,GAAG,CAAC,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,WAAW,EAAE,CAAC;YAC1H,CAAC;YACA,MAAc,CAAC,WAAW,CAAC,EAAE,MAAM,EAAE,OAAO,EAAE,QAAQ,EAAE,CAAC,CAAC;QAC/D,CAAC,EAAE,IAAI,CAAC,CAAC;QAET,QAAQ,CAAC,gBAAgB,CAAC,QAAQ,EAAE,CAAC,CAAC,EAAE,EAAE;YACtC,MAAM,MAAM,GAAG,CAAC,CAAC,MAA0B,CAAC;YAC5C,IAAI,QAAgB,CAAC;YACrB,IAAI,MAAM,CAAC,EAAE,EAAE,CAAC;gBACZ,QAAQ,GAAG,IAAI,MAAM,CAAC,EAAE,EAAE,CAAC;YAC/B,CAAC;iBAAM,IAAI,MAAM,CAAC,YAAY,CAAC,aAAa,CAAC,EAAE,CAAC;gBAC5C,QAAQ,GAAG,iBAAiB,MAAM,CAAC,YAAY,CAAC,aAAa,CAAC,IAAI,CAAC;YACvE,CAAC;iBAAM,IAAI,MAAM,CAAC,IAAI,EAAE,CAAC;gBACrB,QAAQ,GAAG,GAAG,MAAM,CAAC,OAAO,CAAC,WAAW,EAAE,UAAU,MAAM,CAAC,IAAI,IAAI,CAAC;YACxE,CAAC;iBAAM,CAAC;gBACJ,QAAQ,GAAG,MAAM,CAAC,OAAO,CAAC,WAAW,EAAE,CAAC;YAC5C,CAAC;YACD,IAAI,MAAM,CAAC,IAAI,KAAK,UAAU,IAAI,MAAM,CAAC,IAAI,KAAK,OAAO,EAAE,CAAC;gBACvD,MAAc,CAAC,WAAW,CAAC,EAAE,MAAM,EAAE,OAAO,EAAE,QAAQ,EAAE,CAAC,CAAC;YAC/D,CAAC;iBAAM,CAAC;gBACH,MAAc,CAAC,WAAW,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,CAAC,KAAK,EAAE,CAAC,CAAC;YACnF,CAAC;QACL,CAAC,EAAE,IAAI,CAAC,CAAC;IACX,CAAC,CAAC,CAAC;IAEH,MAAM,IAAI,CAAC,YAAY,CAAC,OAAO,EAAE,EAAE,OAAO,EAAE,CAAC,EAAE,CAAC,CAAC;IACjD,MAAM,OAAO,CAAC,KAAK,EAAE,CAAC;IAEtB,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS,CAAC;IAExC,MAAM,QAAQ,GAAiB;QAC7B,IAAI,EAAE,OAAO,CAAC,IAAI;QAClB,GAAG,EAAE,OAAO,CAAC,GAAG;QAChB,QAAQ,EAAE,OAAO,CAAC,QAAQ,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE;QAC1D,UAAU,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;QACpC,QAAQ;QACR,SAAS,EAAE,KAAK,CAAC,MAAM;KACxB,CAAC;IAEF,MAAM,SAAS,GAAkB;QAC/B,QAAQ;QACR,KAAK;QACL,eAAe,EAAE,EAAE;KACpB,CAAC;IAEF,MAAM,EAAE,CAAC,KAAK,CAAC,OAAO,CAAC,SAAS,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IACvD,MAAM,EAAE,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,SAAS,EAAE,eAAe,CAAC,EAAE,IAAI,CAAC,SAAS,CAAC,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC;IACrG,MAAM,EAAE,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,SAAS,EAAE,YAAY,CAAC,EAAE,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC;IAE/F,OAAO,SAAS,CAAC;AACnB,CAAC;AAED,MAAM,UAAU,uBAAuB,CAAC,UAAkB;IACxD,OAAO,EAAE,CAAC;AACZ,CAAC"}

package/dist/setupPrompt.d.ts

@@ -0,0 +1,10 @@
+/**
+ * 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 declare function getSetupPrompt(options?: {
+    devServerUrl?: string;
+}): string;
+//# sourceMappingURL=setupPrompt.d.ts.map

package/dist/setupPrompt.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"setupPrompt.d.ts","sourceRoot":"","sources":["../src/setupPrompt.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,OAAO,GAAE;IAAE,YAAY,CAAC,EAAE,MAAM,CAAA;CAAO,GAAG,MAAM,CAmB9E"}

package/dist/setupPrompt.js

@@ -0,0 +1,27 @@
+/**
+ * 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 = {}) {
+    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.`;
+}
+//# sourceMappingURL=setupPrompt.js.map

package/dist/setupPrompt.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"setupPrompt.js","sourceRoot":"","sources":["../src/setupPrompt.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,MAAM,UAAU,cAAc,CAAC,UAAqC,EAAE;IACpE,MAAM,GAAG,GAAG,OAAO,CAAC,YAAY,IAAI,uBAAuB,CAAC;IAC5D,OAAO;;;;;;;kIAOyH,GAAG;;;;;;;;;6IASQ,CAAC;AAC9I,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,144 @@
+/** Result classification from the comparison pipeline */
+export declare 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[];
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types.js

@@ -0,0 +1,12 @@
+/** Result classification from the comparison pipeline */
+export var DiffResult;
+(function (DiffResult) {
+    DiffResult["IDENTICAL"] = "identical";
+    DiffResult["MINOR"] = "minor";
+    DiffResult["CHANGED"] = "changed";
+    DiffResult["BROKEN"] = "broken";
+    DiffResult["ERROR"] = "error";
+    /** Big visual change the vision classifier accepted as intentional — not a regression */
+    DiffResult["INTENTIONAL"] = "intentional";
+})(DiffResult || (DiffResult = {}));
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,yDAAyD;AACzD,MAAM,CAAN,IAAY,UAQX;AARD,WAAY,UAAU;IACpB,qCAAuB,CAAA;IACvB,6BAAe,CAAA;IACf,iCAAmB,CAAA;IACnB,+BAAiB,CAAA;IACjB,6BAAe,CAAA;IACf,yFAAyF;IACzF,yCAA2B,CAAA;AAC7B,CAAC,EARW,UAAU,KAAV,UAAU,QAQrB"}

package/dist/vision.d.ts

@@ -0,0 +1,34 @@
+import type { VisionConfig } from './types.js';
+export interface VisionVerdict {
+    /** The classifier's multiple-choice answer */
+    answer: 'intentional' | 'regression';
+    /** 0..1 certainty reported by the classifier (conservatively derived when absent) */
+    confidence: number;
+    raw: string;
+}
+/**
+ * Classifies a visual change as intentional or a regression using an
+ * OpenAI-compatible vision endpoint (HF Inference router by default, or a
+ * self-hosted Space exposing the same schema).
+ */
+export declare function classifyChange(options: {
+    baselineImage: Buffer;
+    currentImage: Buffer;
+    context?: string;
+    config: VisionConfig;
+    apiToken: string;
+    logger?: {
+        info: (msg: string, data?: unknown) => void;
+        warn: (msg: string, data?: unknown) => void;
+    };
+}): Promise<VisionVerdict>;
+/** Robustly extracts {answer, confidence} from the model output. Fails safe to regression. */
+export declare function parseVerdict(content: string): VisionVerdict;
+/**
+ * Resolves the API token: process env first, then a gitignored
+ * `<projectDir>/.kintsugi/.env` file (KEY=VALUE lines).
+ */
+export declare function resolveApiToken(tokenEnvVar: string, projectDir?: string): string | undefined;
+/** Loads KEY=VALUE pairs from <projectDir>/.kintsugi/.env into process.env (never overrides). */
+export declare function loadKintsugiEnv(projectDir: string): void;
+//# sourceMappingURL=vision.d.ts.map

package/dist/vision.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vision.d.ts","sourceRoot":"","sources":["../src/vision.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE/C,MAAM,WAAW,aAAa;IAC5B,8CAA8C;IAC9C,MAAM,EAAE,aAAa,GAAG,YAAY,CAAC;IACrC,qFAAqF;IACrF,UAAU,EAAE,MAAM,CAAC;IACnB,GAAG,EAAE,MAAM,CAAC;CACb;AAgBD;;;;GAIG;AACH,wBAAsB,cAAc,CAAC,OAAO,EAAE;IAC5C,aAAa,EAAE,MAAM,CAAC;IACtB,YAAY,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,YAAY,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE;QAAE,IAAI,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,KAAK,IAAI,CAAC;QAAC,IAAI,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,KAAK,IAAI,CAAA;KAAE,CAAC;CACvG,GAAG,OAAO,CAAC,aAAa,CAAC,CA0DzB;AAED,8FAA8F;AAC9F,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,aAAa,CA+B3D;AAMD;;;GAGG;AACH,wBAAgB,eAAe,CAAC,WAAW,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAI5F;AAED,iGAAiG;AACjG,wBAAgB,eAAe,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAexD"}

package/dist/vision.js

@@ -0,0 +1,139 @@
+import fs from 'node:fs';
+import path from 'node:path';
+const SYSTEM_PROMPT = [
+    'You are a strict UI visual-regression classifier for an automated QA tool.',
+    'You will see two screenshots of the same user flow: IMAGE 1 is the accepted baseline, IMAGE 2 is the current state after a code change.',
+    'You will also get optional context about what the developer/agent was asked to do in the latest turn.',
+    'Decide whether the visual difference is:',
+    '- "intentional": a deliberate design/feature change consistent with the context (or a benign change like dynamic content), or',
+    '- "regression": something broke — a missing/shifted/broken component, layout collapse, unstyled content, blank regions, or an inconsistency with the context.',
+    'The baseline is the ACCEPTED, WORKING state. Missing UI elements (buttons, forms, prices, text) are regressions even if the remaining design looks clean and coherent.',
+    'If no context is provided, be conservative: significant changes should be classified as "regression" — only classify as "intentional" if the change is clearly benign.',
+    'If context IS provided and IMAGE 2 implements exactly what the context asked for, classify as "intentional" with high confidence — a requested change is not a regression.',
+    'Answer with ONLY a JSON object, no other text:',
+    '{"answer": "intentional" | "regression", "confidence": <number between 0 and 1>}',
+].join('\n');
+/**
+ * Classifies a visual change as intentional or a regression using an
+ * OpenAI-compatible vision endpoint (HF Inference router by default, or a
+ * self-hosted Space exposing the same schema).
+ */
+export async function classifyChange(options) {
+    const { baselineImage, currentImage, context, config, apiToken, logger } = options;
+    const userLines = [
+        'IMAGE 1 = accepted baseline. IMAGE 2 = current state after the latest code change.',
+        context
+            ? `Context from the latest turn (what the agent was asked to do):\n"${context}"`
+            : 'No context available about the intended change.',
+        'Classify the difference between IMAGE 1 and IMAGE 2 as "intentional" or "regression".',
+        'Reply with ONLY the JSON object.',
+    ];
+    const body = {
+        model: config.model,
+        temperature: 0,
+        max_tokens: 60,
+        messages: [
+            { role: 'system', content: SYSTEM_PROMPT },
+            {
+                role: 'user',
+                content: [
+                    { type: 'text', text: userLines.join('\n\n') },
+                    { type: 'image_url', image_url: { url: toDataUrl(baselineImage) } },
+                    { type: 'image_url', image_url: { url: toDataUrl(currentImage) } },
+                ],
+            },
+        ],
+    };
+    const url = `${config.endpoint.replace(/\/$/, '')}/chat/completions`;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), config.timeoutMs);
+    let response;
+    try {
+        response = await fetch(url, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                Authorization: `Bearer ${apiToken}`,
+            },
+            body: JSON.stringify(body),
+            signal: controller.signal,
+        });
+    }
+    finally {
+        clearTimeout(timer);
+    }
+    if (!response.ok) {
+        const detail = await response.text().catch(() => '');
+        throw new Error(`vision endpoint ${response.status}: ${detail.slice(0, 300)}`);
+    }
+    const payload = JSON.parse(await response.text());
+    const content = payload.choices?.[0]?.message?.content ?? '';
+    logger?.info('vision classifier responded', { content: content.slice(0, 200) });
+    return parseVerdict(content);
+}
+/** Robustly extracts {answer, confidence} from the model output. Fails safe to regression. */
+export function parseVerdict(content) {
+    const text = content.trim();
+    // Preferred: the JSON object we asked for
+    const jsonMatch = text.match(/\{[\s\S]*?\}/);
+    if (jsonMatch) {
+        try {
+            const parsed = JSON.parse(jsonMatch[0]);
+            if (parsed.answer === 'intentional' || parsed.answer === 'regression') {
+                const confidence = typeof parsed.confidence === 'number'
+                    ? Math.min(1, Math.max(0, parsed.confidence))
+                    : 0.5;
+                return { answer: parsed.answer, confidence, raw: text };
+            }
+        }
+        catch {
+            // fall through to word matching
+        }
+    }
+    // Fallback: the model answered with the bare word (we prompted for one word
+    // in early iterations; small models sometimes ignore the JSON instruction).
+    const lower = text.toLowerCase();
+    if (/\bintentional\b/.test(lower) && !/\bregression\b/.test(lower)) {
+        return { answer: 'intentional', confidence: 0.8, raw: text };
+    }
+    if (/\bregression\b/.test(lower) && !/\bintentional\b/.test(lower)) {
+        return { answer: 'regression', confidence: 0.8, raw: text };
+    }
+    // Unparseable — fail safe: treat as an unresolved regression
+    return { answer: 'regression', confidence: 0.5, raw: text };
+}
+function toDataUrl(png) {
+    return `data:image/png;base64,${png.toString('base64')}`;
+}
+/**
+ * Resolves the API token: process env first, then a gitignored
+ * `<projectDir>/.kintsugi/.env` file (KEY=VALUE lines).
+ */
+export function resolveApiToken(tokenEnvVar, projectDir) {
+    if (process.env[tokenEnvVar])
+        return process.env[tokenEnvVar];
+    if (projectDir)
+        loadKintsugiEnv(projectDir);
+    return process.env[tokenEnvVar];
+}
+/** Loads KEY=VALUE pairs from <projectDir>/.kintsugi/.env into process.env (never overrides). */
+export function loadKintsugiEnv(projectDir) {
+    const envPath = path.join(projectDir, '.kintsugi', '.env');
+    let content;
+    try {
+        content = fs.readFileSync(envPath, 'utf-8');
+    }
+    catch {
+        return;
+    }
+    for (const line of content.split('\n')) {
+        const match = line.match(/^\s*([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*)\s*$/);
+        if (!match)
+            continue;
+        const key = match[1];
+        const value = match[2].replace(/^["']|["']$/g, '');
+        if (!(key in process.env))
+            process.env[key] = value;
+    }
+}
+//# sourceMappingURL=vision.js.map

package/dist/vision.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"vision.js","sourceRoot":"","sources":["../src/vision.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@kintsugi-ai/core",
+  "version": "0.1.0",
+  "description": "Core visual regression detection engine for Kintsugi",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "pixelmatch": "^6.0.0",
+    "playwright": "^1.50.0",
+    "pngjs": "^7.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "@types/pixelmatch": "^5.2.6",
+    "@types/pngjs": "^6.0.5",
+    "typescript": "^5.7.0"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc",
+    "clean": "rm -rf dist",
+    "typecheck": "tsc --noEmit",
+    "test": "node --test dist/**/*.test.js"
+  }
+}

package/src/auth.ts

@@ -0,0 +1,195 @@
+/**
+ * Hosted-API client lifecycle: anonymous key bootstrap, account status, and
+ * checkout — shared by the hook, the CLI, and the VS Code extension.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { createHash } from 'node:crypto';
+import { resolveApiToken, globalKintsugiEnvPath } from './classifier.js';
+import type { ClassifierContext } from './comparator.js';
+import type { KintsugiConfig } from './types.js';
+
+type Logger = { info: (msg: string, data?: unknown) => void; warn: (msg: string, data?: unknown) => void };
+
+/** Stable per-machine fingerprint used to issue anonymous keys. */
+export function computeDeviceHash(): string {
+  return createHash('sha256').update(`${os.hostname()}|${os.homedir()}`).digest('hex').slice(0, 32);
+}
+
+/** Writes (or replaces) one KEY=VALUE line in ~/.kintsugi/.env, preserving other lines. */
+export function writeGlobalEnvValue(key: string, value: string): string {
+  const envPath = globalKintsugiEnvPath();
+  fs.mkdirSync(path.dirname(envPath), { recursive: true });
+  let content = '';
+  try {
+    content = fs.readFileSync(envPath, 'utf-8');
+  } catch {
+    // no file yet
+  }
+  const line = `${key}=${value}`;
+  const escapedKey = key.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  const re = new RegExp(`^${escapedKey}=.*$`, 'm');
+  const updated = re.test(content)
+    ? content.replace(re, line)
+    : content === '' || content.endsWith('\n')
+      ? content + line
+      : content + '\n' + line;
+  fs.writeFileSync(envPath, updated.endsWith('\n') ? updated : updated + '\n');
+  return envPath;
+}
+
+/**
+ * Returns the hosted-API key, bootstrapping an anonymous free key (written to
+ * ~/.kintsugi/.env) when none exists. Returns undefined on network failure —
+ * callers degrade to classifier-off, never crash.
+ */
+export async function ensureApiKey(options: {
+  endpoint: string;
+  tokenEnvVar: string;
+  projectDir?: string;
+  fetchImpl?: typeof fetch;
+  logger?: Logger;
+}): Promise<string | undefined> {
+  const existing = resolveApiToken(options.tokenEnvVar, options.projectDir);
+  if (existing) return existing;
+
+  const fetchImpl = options.fetchImpl ?? fetch;
+  try {
+    const res = await fetchImpl(`${options.endpoint.replace(/\/$/, '')}/keys`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ deviceHash: computeDeviceHash() }),
+    });
+    if (!res.ok) throw new Error(`key issuance ${res.status}`);
+    const body = (await res.json()) as { key?: string };
+    if (typeof body.key !== 'string' || !body.key.startsWith('knt_')) {
+      throw new Error('key issuance returned no key');
+    }
+    writeGlobalEnvValue(options.tokenEnvVar, body.key);
+    options.logger?.info('issued anonymous kintsugi api key', { envFile: globalKintsugiEnvPath() });
+    return body.key;
+  } catch (err) {
+    options.logger?.warn(`could not obtain a kintsugi api key: ${(err as Error).message}`);
+    return undefined;
+  }
+}
+
+export interface ApiAccountStatus {
+  plan: string;
+  flowsUsed: number;
+  flowLimit: number | null;
+  upgradeUrl?: string;
+}
+
+export async function getAccountStatus(
+  apiKey: string,
+  endpoint: string,
+  fetchImpl?: typeof fetch
+): Promise<ApiAccountStatus | undefined> {
+  try {
+    const res = await (fetchImpl ?? fetch)(`${endpoint.replace(/\/$/, '')}/keys/me`, {
+      headers: { Authorization: `Bearer ${apiKey}` },
+    });
+    if (!res.ok) return undefined;
+    return (await res.json()) as ApiAccountStatus;
+  } catch {
+    return undefined;
+  }
+}
+
+/** Stripe Payment Link URL for the $29/mo Pro upgrade, or undefined when billing is unavailable. */
+export async function createCheckoutUrl(
+  apiKey: string,
+  endpoint: string,
+  fetchImpl?: typeof fetch
+): Promise<string | undefined> {
+  try {
+    const res = await (fetchImpl ?? fetch)(`${endpoint.replace(/\/$/, '')}/billing/checkout`, {
+      method: 'POST',
+      headers: { Authorization: `Bearer ${apiKey}` },
+    });
+    if (!res.ok) return undefined;
+    const body = (await res.json()) as { url?: string };
+    return body.url;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Polls account status until the plan becomes 'pro' (the Stripe webhook flips
+ * it server-side shortly after payment) or the timeout elapses. Called from
+ * the CLI and the VS Code extension after the payment link is opened.
+ */
+export async function waitForPlanUpgrade(
+  apiKey: string,
+  endpoint: string,
+  options: {
+    intervalMs?: number;
+    timeoutMs?: number;
+    fetchImpl?: typeof fetch;
+    shouldContinue?: () => boolean;
+    onPoll?: (status: ApiAccountStatus | undefined) => void;
+  } = {}
+): Promise<ApiAccountStatus | undefined> {
+  const interval = options.intervalMs ?? 3000;
+  const deadline = Date.now() + (options.timeoutMs ?? 180_000);
+  while (Date.now() < deadline && (options.shouldContinue?.() ?? true)) {
+    const status = await getAccountStatus(apiKey, endpoint, options.fetchImpl);
+    if (status?.plan === 'pro') return status;
+    options.onPoll?.(status);
+    await new Promise(resolve => setTimeout(resolve, interval));
+  }
+  return undefined;
+}
+
+/**
+ * Shared classifier-context builder used by the hook, `kintsugi check`, and
+ * the MCP server — one code path decides when classification is active.
+ * With bootstrapKey, an anonymous hosted key is auto-issued on first use.
+ */
+export async function buildClassifierContext(
+  config: KintsugiConfig,
+  options: {
+    context?: string;
+    logger?: Logger;
+    bootstrapKey?: boolean;
+    projectDir?: string;
+    fetchImpl?: typeof fetch;
+  } = {}
+): Promise<ClassifierContext | undefined> {
+  const log = options.logger;
+  if (!config.classifier?.enabled) {
+    log?.info('classifier disabled in config');
+    return undefined;
+  }
+  let apiToken = resolveApiToken(config.classifier.tokenEnvVar, options.projectDir);
+  if (!apiToken && options.bootstrapKey && config.classifier.provider === 'kintsugi') {
+    apiToken = await ensureApiKey({
+      endpoint: config.classifier.endpoint,
+      tokenEnvVar: config.classifier.tokenEnvVar,
+      projectDir: options.projectDir,
+      fetchImpl: options.fetchImpl,
+      logger: log,
+    });
+  }
+  if (!apiToken) {
+    log?.warn(
+      `no API token found (env ${config.classifier.tokenEnvVar}, <project>/.kintsugi/.env, or ~/.kintsugi/.env) — classifier disabled, large diffs will escalate without classification`
+    );
+    return undefined;
+  }
+  log?.info('classifier active', {
+    provider: config.classifier.provider,
+    model: config.classifier.model,
+    endpoint: config.classifier.endpoint,
+    turnContext: options.context || '(none)',
+  });
+  return {
+    config: config.classifier,
+    apiToken,
+    context: options.context,
+    logger: log,
+  };
+}