@ahmedalbarghouti/farq 0.0.1

package/dist/render/json.js

@@ -0,0 +1,3 @@
+export function renderJson(summary, images = []) {
+    return `${JSON.stringify({ ...summary, images }, null, 2)}\n`;
+}

package/dist/render/pr.d.ts

@@ -0,0 +1,7 @@
+import type { ChangeSummary } from "../schema.js";
+export type RenderPrOptions = {
+    summary: ChangeSummary;
+    imagePath?: string | null;
+    imageAlt?: string;
+};
+export declare function renderPr(options: RenderPrOptions): string;

package/dist/render/pr.js

@@ -0,0 +1,48 @@
+import { truncateTitle, GITHUB_TITLE_MAX } from "../title.js";
+const EMOJI = {
+    feature: "\u2728",
+    fix: "\uD83D\uDC1B",
+    improvement: "\uD83D\uDC8E",
+    refactor: "\u267B\uFE0F",
+    chore: "\uD83D\uDD27",
+    docs: "\uD83D\uDCDD",
+    perf: "\u26A1",
+    security: "\uD83D\uDD12",
+};
+export function renderPr(options) {
+    const { title, overflow } = truncateTitle(options.summary.headline, GITHUB_TITLE_MAX);
+    const out = [];
+    out.push(options.summary.overview);
+    if (overflow) {
+        out.push("");
+        out.push(overflow);
+    }
+    if (options.imagePath) {
+        out.push("");
+        out.push("### Before / After");
+        out.push("");
+        const alt = options.imageAlt ?? "before / after";
+        out.push(`![${alt}](${options.imagePath})`);
+        out.push("");
+        out.push("_Local image path - attach the file when pasting into GitHub if it does not render._");
+    }
+    out.push("");
+    out.push("### Changes");
+    out.push("");
+    for (const item of options.summary.items) {
+        const emoji = EMOJI[item.category] ?? "\u2022";
+        const files = item.files.length > 0
+            ? ` <sub>${item.files.join(", ")}</sub>`
+            : "";
+        out.push(`- ${emoji} **${item.title}** \u2014 ${item.description}${files}`);
+    }
+    if (options.summary.breaking_changes.length > 0) {
+        out.push("");
+        out.push("### \u26A0\uFE0F Breaking changes");
+        out.push("");
+        for (const b of options.summary.breaking_changes) {
+            out.push(`- ${b}`);
+        }
+    }
+    return `${title}\n\n${out.join("\n").trim()}\n`;
+}

package/dist/render/slack.d.ts

@@ -0,0 +1,2 @@
+import type { ChangeSummary } from "../schema.js";
+export declare function renderSlack(summary: ChangeSummary): string;

package/dist/render/slack.js

@@ -0,0 +1,25 @@
+const EMOJI = {
+    feature: ":sparkles:",
+    fix: ":bug:",
+    improvement: ":gem:",
+    refactor: ":recycle:",
+    chore: ":wrench:",
+    docs: ":memo:",
+    perf: ":zap:",
+    security: ":lock:",
+};
+export function renderSlack(summary) {
+    const lines = [];
+    lines.push(`*${summary.headline}*`);
+    lines.push(summary.overview);
+    lines.push("");
+    for (const item of summary.items) {
+        const emoji = EMOJI[item.category] ?? ":small_blue_diamond:";
+        lines.push(`${emoji} *${item.title}* — ${item.description}`);
+    }
+    if (summary.breaking_changes.length > 0) {
+        lines.push("");
+        lines.push(`:warning: Breaking: ${summary.breaking_changes.join("; ")}`);
+    }
+    return `${lines.join("\n").trim()}\n`;
+}

package/dist/schema.d.ts

@@ -0,0 +1,74 @@
+import { z } from "zod";
+export declare const CATEGORIES: readonly ["feature", "fix", "improvement", "refactor", "chore", "docs", "perf", "security"];
+export declare const ChangeItemSchema: z.ZodObject<{
+    category: z.ZodEnum<["feature", "fix", "improvement", "refactor", "chore", "docs", "perf", "security"]>;
+    title: z.ZodString;
+    description: z.ZodString;
+    why_it_matters: z.ZodOptional<z.ZodString>;
+    files: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+}, "strip", z.ZodTypeAny, {
+    files: string[];
+    category: "feature" | "fix" | "improvement" | "refactor" | "chore" | "docs" | "perf" | "security";
+    title: string;
+    description: string;
+    why_it_matters?: string | undefined;
+}, {
+    category: "feature" | "fix" | "improvement" | "refactor" | "chore" | "docs" | "perf" | "security";
+    title: string;
+    description: string;
+    files?: string[] | undefined;
+    why_it_matters?: string | undefined;
+}>;
+export declare const ChangeSummarySchema: z.ZodObject<{
+    headline: z.ZodString;
+    overview: z.ZodString;
+    items: z.ZodArray<z.ZodObject<{
+        category: z.ZodEnum<["feature", "fix", "improvement", "refactor", "chore", "docs", "perf", "security"]>;
+        title: z.ZodString;
+        description: z.ZodString;
+        why_it_matters: z.ZodOptional<z.ZodString>;
+        files: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    }, "strip", z.ZodTypeAny, {
+        files: string[];
+        category: "feature" | "fix" | "improvement" | "refactor" | "chore" | "docs" | "perf" | "security";
+        title: string;
+        description: string;
+        why_it_matters?: string | undefined;
+    }, {
+        category: "feature" | "fix" | "improvement" | "refactor" | "chore" | "docs" | "perf" | "security";
+        title: string;
+        description: string;
+        files?: string[] | undefined;
+        why_it_matters?: string | undefined;
+    }>, "many">;
+    breaking_changes: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    visual_notes: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    headline: string;
+    overview: string;
+    items: {
+        files: string[];
+        category: "feature" | "fix" | "improvement" | "refactor" | "chore" | "docs" | "perf" | "security";
+        title: string;
+        description: string;
+        why_it_matters?: string | undefined;
+    }[];
+    breaking_changes: string[];
+    visual_notes?: string | undefined;
+}, {
+    headline: string;
+    overview: string;
+    items: {
+        category: "feature" | "fix" | "improvement" | "refactor" | "chore" | "docs" | "perf" | "security";
+        title: string;
+        description: string;
+        files?: string[] | undefined;
+        why_it_matters?: string | undefined;
+    }[];
+    breaking_changes?: string[] | undefined;
+    visual_notes?: string | undefined;
+}>;
+export type ChangeSummary = z.infer<typeof ChangeSummarySchema>;
+export type ChangeItem = z.infer<typeof ChangeItemSchema>;
+/** Compact schema description embedded in AI prompts. */
+export declare const CHANGE_SUMMARY_SCHEMA_PROMPT = "{\n  \"headline\": \"string <=140 \u2014 one-line summary (PR title)\",\n  \"overview\": \"string \u2014 1-3 sentences in requested tone\",\n  \"items\": [{\n    \"category\": \"feature|fix|improvement|refactor|chore|docs|perf|security\",\n    \"title\": \"string <=120\",\n    \"description\": \"string\",\n    \"why_it_matters\": \"string (optional; required for client tone)\",\n    \"files\": [\"string\"]\n  }],\n  \"breaking_changes\": [\"string\"],\n  \"visual_notes\": \"string (optional)\"\n}";

package/dist/schema.js

@@ -0,0 +1,39 @@
+import { z } from "zod";
+export const CATEGORIES = [
+    "feature",
+    "fix",
+    "improvement",
+    "refactor",
+    "chore",
+    "docs",
+    "perf",
+    "security",
+];
+export const ChangeItemSchema = z.object({
+    category: z.enum(CATEGORIES),
+    title: z.string().min(1).max(120),
+    description: z.string().min(1),
+    why_it_matters: z.string().min(1).optional(),
+    files: z.array(z.string()).default([]),
+});
+export const ChangeSummarySchema = z.object({
+    headline: z.string().min(1).max(140),
+    overview: z.string().min(1),
+    items: z.array(ChangeItemSchema).min(1),
+    breaking_changes: z.array(z.string()).default([]),
+    visual_notes: z.string().min(1).optional(),
+});
+/** Compact schema description embedded in AI prompts. */
+export const CHANGE_SUMMARY_SCHEMA_PROMPT = `{
+  "headline": "string <=140 — one-line summary (PR title)",
+  "overview": "string — 1-3 sentences in requested tone",
+  "items": [{
+    "category": "feature|fix|improvement|refactor|chore|docs|perf|security",
+    "title": "string <=120",
+    "description": "string",
+    "why_it_matters": "string (optional; required for client tone)",
+    "files": ["string"]
+  }],
+  "breaking_changes": ["string"],
+  "visual_notes": "string (optional)"
+}`;

package/dist/summarize.d.ts

@@ -0,0 +1,17 @@
+import { type ChangeSummary } from "./schema.js";
+import type { Provider } from "./providers/index.js";
+import type { ToneName } from "./config.js";
+import type { GatherDiffResult } from "./git.js";
+export declare class SummarizeError extends Error {
+    readonly exitCode = 2;
+    constructor(message: string);
+}
+export type SummarizeOptions = {
+    provider: Provider;
+    diff: GatherDiffResult;
+    tone: ToneName;
+    titleConventionBlurb?: string;
+    model?: string;
+};
+export declare function summarize(options: SummarizeOptions): Promise<ChangeSummary>;
+export declare function buildPrompt(options: SummarizeOptions): string;

package/dist/summarize.js

@@ -0,0 +1,72 @@
+import { extractJson } from "./extract-json.js";
+import { CHANGE_SUMMARY_SCHEMA_PROMPT, ChangeSummarySchema, } from "./schema.js";
+export class SummarizeError extends Error {
+    exitCode = 2;
+    constructor(message) {
+        super(message);
+        this.name = "SummarizeError";
+    }
+}
+export async function summarize(options) {
+    const prompt = buildPrompt(options);
+    let lastError = "";
+    for (let attempt = 0; attempt < 2; attempt++) {
+        const fullPrompt = attempt === 0
+            ? prompt
+            : `${prompt}\n\nYour previous output failed validation:\n${lastError}\nReturn corrected JSON only.`;
+        let raw;
+        try {
+            raw = await options.provider.complete(fullPrompt, {
+                model: options.model,
+            });
+        }
+        catch (err) {
+            throw new SummarizeError(err instanceof Error ? err.message : String(err));
+        }
+        try {
+            const json = extractJson(raw);
+            const parsed = ChangeSummarySchema.parse(json);
+            if (options.tone === "client") {
+                for (const item of parsed.items) {
+                    if (!item.why_it_matters) {
+                        throw new Error(`Item "${item.title}" missing why_it_matters (required for client tone)`);
+                    }
+                }
+            }
+            return parsed;
+        }
+        catch (err) {
+            lastError = err instanceof Error ? err.message : String(err);
+            if (attempt === 1) {
+                throw new SummarizeError(`AI output invalid after retry: ${lastError}`);
+            }
+        }
+    }
+    throw new SummarizeError("AI output invalid after retry");
+}
+export function buildPrompt(options) {
+    const toneRules = options.tone === "client"
+        ? "Tone: plain English for a non-technical client. Avoid jargon. Every item MUST include why_it_matters."
+        : "Tone: technical, concise, accurate for engineers.";
+    const convention = options.titleConventionBlurb
+        ? `\nTitle conventions for this repo:\n${options.titleConventionBlurb}\n`
+        : "";
+    return `You summarize a git diff into a structured change summary.
+
+Rules:
+- Return JSON only. No markdown fences. No prose before or after.
+- Group related edits (never one item per file).
+- Report only what the diff shows. Do not invent work.
+- ${toneRules}
+${convention}
+Schema:
+${CHANGE_SUMMARY_SCHEMA_PROMPT}
+
+Diff range: ${options.diff.range}
+Commits:
+${options.diff.commits.map((c) => `- ${c}`).join("\n") || "(none)"}
+
+Diff:
+${options.diff.diffText}
+`;
+}

package/dist/template.d.ts

@@ -0,0 +1,11 @@
+import type { ChangeSummary } from "./schema.js";
+export declare function findPrTemplate(cwd: string): string | null;
+export declare function fillPrTemplate(options: {
+    template: string | null;
+    summary: ChangeSummary;
+    bodyMarkdown: string;
+    imageUrl?: string | null;
+}): {
+    title: string;
+    body: string;
+};

package/dist/template.js

@@ -0,0 +1,87 @@
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { truncateTitle, GITHUB_TITLE_MAX } from "./title.js";
+export function findPrTemplate(cwd) {
+    const single = join(cwd, ".github", "pull_request_template.md");
+    if (existsSync(single))
+        return readFileSync(single, "utf8");
+    const alt = join(cwd, ".github", "PULL_REQUEST_TEMPLATE.md");
+    if (existsSync(alt))
+        return readFileSync(alt, "utf8");
+    const dir = join(cwd, ".github", "PULL_REQUEST_TEMPLATE");
+    if (existsSync(dir)) {
+        const files = readdirSync(dir).filter((f) => f.endsWith(".md"));
+        if (files[0])
+            return readFileSync(join(dir, files[0]), "utf8");
+    }
+    return null;
+}
+export function fillPrTemplate(options) {
+    const { title, overflow } = truncateTitle(options.summary.headline, GITHUB_TITLE_MAX);
+    let body = options.template?.trim() || "";
+    if (!body) {
+        body = options.bodyMarkdown;
+        if (overflow)
+            body = overflow + "\n\n" + body;
+        if (options.imageUrl) {
+            const re = /\]\((?:\.\/)?\.farq\/[^)]+\)/;
+            if (re.test(body)) {
+                body = body.replace(re, "](" + options.imageUrl + ")");
+            }
+            else {
+                body =
+                    "### Before / After\n\n![before / after](" +
+                        options.imageUrl +
+                        ")\n\n" +
+                        body;
+            }
+        }
+        return { title, body };
+    }
+    body = fillSection(body, /summary/i, options.summary.overview);
+    const changes = options.summary.items
+        .map((i) => "- **" + i.title + "** — " + i.description)
+        .join("\n");
+    body = fillSection(body, /changes?|what('s| is)? changed/i, changes);
+    const testPlan = "_Please add verification steps._\n\n" +
+        options.summary.items.map((i) => "- [ ] Verify: " + i.title).join("\n");
+    body = fillSection(body, /test\s*plan|testing|how to test/i, testPlan);
+    if (overflow)
+        body = overflow + "\n\n" + body;
+    if (options.imageUrl) {
+        if (/before\s*\/\s*after|screenshots?/i.test(body)) {
+            body = fillSection(body, /before\s*\/\s*after|screenshots?/i, "![before / after](" + options.imageUrl + ")");
+        }
+        else {
+            body +=
+                "\n\n### Before / After\n\n![before / after](" +
+                    options.imageUrl +
+                    ")\n";
+        }
+    }
+    return { title, body };
+}
+function fillSection(template, heading, content) {
+    const lines = template.split("\n");
+    let inSection = false;
+    let start = -1;
+    let end = lines.length;
+    for (let i = 0; i < lines.length; i++) {
+        const h = lines[i].match(/^#{1,3}\s+(.*)$/);
+        if (h) {
+            if (inSection) {
+                end = i;
+                break;
+            }
+            if (heading.test(h[1])) {
+                inSection = true;
+                start = i;
+            }
+        }
+    }
+    if (start === -1)
+        return template;
+    const before = lines.slice(0, start + 1);
+    const after = lines.slice(end);
+    return [...before, "", content, "", ...after].join("\n").replace(/\n{3,}/g, "\n\n");
+}

package/dist/title.d.ts

@@ -0,0 +1,12 @@
+export type TruncatedTitle = {
+    title: string;
+    overflow: string;
+};
+export type TitleConvention = {
+    kind: "conventional" | "ticket" | "none";
+    blurb: string;
+};
+/** GitHub PR title hard limit is 256 characters. */
+export declare const GITHUB_TITLE_MAX = 256;
+export declare function truncateTitle(text: string, max?: number): TruncatedTitle;
+export declare function inferTitleConvention(samples: string[]): TitleConvention;

package/dist/title.js

@@ -0,0 +1,37 @@
+/** GitHub PR title hard limit is 256 characters. */
+export const GITHUB_TITLE_MAX = 256;
+export function truncateTitle(text, max = GITHUB_TITLE_MAX) {
+    if (text.length <= max)
+        return { title: text, overflow: "" };
+    const ellipsis = "...";
+    const budget = max - ellipsis.length;
+    let cut = budget;
+    const slice = text.slice(0, budget + 1);
+    const lastSpace = slice.lastIndexOf(" ");
+    if (lastSpace >= Math.floor(budget * 0.6)) {
+        cut = lastSpace;
+    }
+    const title = text.slice(0, cut).trimEnd() + ellipsis;
+    const overflow = text.slice(cut).trimStart();
+    return { title, overflow };
+}
+export function inferTitleConvention(samples) {
+    if (samples.length === 0) {
+        return { kind: "none", blurb: "" };
+    }
+    const conventional = samples.filter((s) => /^(feat|fix|chore|docs|refactor|perf|test|style|ci|build)(\([^)]+\))?:/i.test(s.trim()));
+    const ticket = samples.filter((s) => /^\[[A-Z][A-Z0-9]+-\d+\]/.test(s.trim()));
+    if (conventional.length >= Math.ceil(samples.length * 0.6)) {
+        return {
+            kind: "conventional",
+            blurb: "Repo PR titles usually follow Conventional Commits (e.g. feat:, fix(scope):). Match that style. Prefer titles around 72 characters when possible.",
+        };
+    }
+    if (ticket.length >= Math.ceil(samples.length * 0.6)) {
+        return {
+            kind: "ticket",
+            blurb: "Repo PR titles usually start with a ticket prefix like [PROJ-123]. Match that prefix style when a ticket id is available in the branch or commits; otherwise keep a clear plain title.",
+        };
+    }
+    return { kind: "none", blurb: "" };
+}

package/dist/visual/chrome.d.ts

@@ -0,0 +1,12 @@
+export declare class ChromeError extends Error {
+    constructor(message: string);
+}
+export declare function resolveChrome(env?: NodeJS.ProcessEnv): string;
+export type ScreenshotOptions = {
+    chromePath?: string;
+    url: string;
+    outPath: string;
+    width?: number;
+    height?: number;
+};
+export declare function screenshotHtml(options: ScreenshotOptions): Promise<void>;

package/dist/visual/chrome.js

@@ -0,0 +1,62 @@
+import { existsSync } from "node:fs";
+import { execa } from "execa";
+import { platform } from "node:os";
+const TIMEOUT_MS = 30_000;
+export class ChromeError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "ChromeError";
+    }
+}
+export function resolveChrome(env = process.env) {
+    if (env.CHROME_PATH) {
+        if (existsSync(env.CHROME_PATH))
+            return env.CHROME_PATH;
+        throw new ChromeError(`CHROME_PATH not found: ${env.CHROME_PATH}`);
+    }
+    const candidates = platform() === "win32"
+        ? [
+            "C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe",
+            "C:\\Program Files (x86)\\Google\\Chrome\\Application\\chrome.exe",
+            `${env.LOCALAPPDATA}\\Google\\Chrome\\Application\\chrome.exe`,
+            "C:\\Program Files\\Chromium\\Application\\chrome.exe",
+        ]
+        : platform() === "darwin"
+            ? [
+                "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
+                "/Applications/Chromium.app/Contents/MacOS/Chromium",
+            ]
+            : [
+                "/usr/bin/google-chrome",
+                "/usr/bin/google-chrome-stable",
+                "/usr/bin/chromium",
+                "/usr/bin/chromium-browser",
+            ];
+    for (const c of candidates) {
+        if (c && existsSync(c))
+            return c;
+    }
+    throw new ChromeError("Chrome/Chromium not found — install Google Chrome or set CHROME_PATH");
+}
+export async function screenshotHtml(options) {
+    const chrome = options.chromePath ?? resolveChrome();
+    const width = options.width ?? 1280;
+    const height = options.height ?? 900;
+    try {
+        await execa(chrome, [
+            "--headless=new",
+            "--disable-gpu",
+            "--hide-scrollbars",
+            `--window-size=${width},${height}`,
+            `--screenshot=${options.outPath}`,
+            options.url,
+        ], { timeout: TIMEOUT_MS, reject: true });
+    }
+    catch (err) {
+        const e = err;
+        if (e.timedOut) {
+            throw new ChromeError("Chrome screenshot timed out after 30s");
+        }
+        throw new ChromeError(`Chrome screenshot failed: ${e.message ?? "unknown error"}`);
+    }
+}

package/dist/visual/compose.d.ts

@@ -0,0 +1,16 @@
+import { resolveChrome, ChromeError } from "./chrome.js";
+export type ComposeOptions = {
+    cwd?: string;
+    outDir?: string;
+    beforePath: string;
+    afterPath: string;
+    badge?: "generated preview" | "before / after";
+    chromePath?: string;
+};
+export declare function buildComposeHtml(options: {
+    beforeBase64: string;
+    afterBase64: string;
+    badge: string;
+}): string;
+export declare function composeBeforeAfter(options: ComposeOptions): Promise<string>;
+export { ChromeError, resolveChrome };

package/dist/visual/compose.js

@@ -0,0 +1,58 @@
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import { resolveChrome, screenshotHtml, ChromeError } from "./chrome.js";
+export function buildComposeHtml(options) {
+    const { beforeBase64, afterBase64, badge } = options;
+    return `<!doctype html>
+<html><head><meta charset="utf-8" />
+<style>
+  html,body{margin:0;background:#1b1d21;color:#e8e8e8;font-family:system-ui,sans-serif}
+  .wrap{padding:24px}
+  .badge{position:fixed;top:12px;right:12px;font-size:11px;letter-spacing:.04em;text-transform:uppercase;
+    background:#2a2e35;border:1px solid #3a3f48;padding:4px 8px;border-radius:4px;opacity:.9}
+  .grid{display:grid;grid-template-columns:1fr 1fr;gap:16px}
+  h2{margin:0 0 10px;font-size:14px;font-weight:600;color:#b9c0c9}
+  img{width:100%;height:auto;background:#0f1114;border:1px solid #2f343d;border-radius:6px;display:block}
+</style></head>
+<body>
+  <div class="badge">${escapeHtml(badge)}</div>
+  <div class="wrap"><div class="grid">
+    <section><h2>Before</h2><img alt="Before" src="data:image/png;base64,${beforeBase64}" /></section>
+    <section><h2>After</h2><img alt="After" src="data:image/png;base64,${afterBase64}" /></section>
+  </div></div>
+</body></html>`;
+}
+function escapeHtml(s) {
+    return s
+        .replaceAll("&", "&amp;")
+        .replaceAll("<", "&lt;")
+        .replaceAll(">", "&gt;")
+        .replaceAll('"', "&quot;");
+}
+export async function composeBeforeAfter(options) {
+    const cwd = options.cwd ?? process.cwd();
+    const outDir = resolve(cwd, options.outDir ?? ".farq");
+    mkdirSync(outDir, { recursive: true });
+    const before = readFileSync(options.beforePath);
+    const after = readFileSync(options.afterPath);
+    const badge = options.badge ?? "generated preview";
+    const html = buildComposeHtml({
+        beforeBase64: before.toString("base64"),
+        afterBase64: after.toString("base64"),
+        badge,
+    });
+    const composePath = join(outDir, "compose.html");
+    writeFileSync(composePath, html, "utf8");
+    const outPng = join(outDir, "before-after.png");
+    const chromePath = options.chromePath ?? resolveChrome();
+    await screenshotHtml({
+        chromePath,
+        url: pathToFileURL(composePath).href,
+        outPath: outPng,
+        width: 1400,
+        height: 900,
+    });
+    return outPng;
+}
+export { ChromeError, resolveChrome };

package/dist/visual/diagram.d.ts

@@ -0,0 +1,17 @@
+import type { ChangeSummary } from "../schema.js";
+import type { Provider } from "../providers/index.js";
+export type DiagramResult = {
+    feasible: true;
+    htmlPath: string;
+} | {
+    feasible: false;
+    reason: string;
+};
+export declare function generateDiagram(options: {
+    provider: Provider;
+    summary: ChangeSummary;
+    diffText: string;
+    outDir: string;
+    model?: string;
+    log?: (msg: string) => void;
+}): Promise<DiagramResult>;

package/dist/visual/diagram.js

@@ -0,0 +1,36 @@
+import { mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { extractJson } from "../extract-json.js";
+export async function generateDiagram(options) {
+    const prompt = `You create a conceptual before/after flowchart as one self-contained HTML document.
+
+This is the fallback visual when a pixel UI mockup is not appropriate (API, logic, docs, config, etc.). Prefer a small flowchart or labeled before/after boxes that explain the change at a glance.
+
+Rules:
+- Pure HTML/CSS, no libraries, no external requests, system fonts.
+- Two labeled columns (Before / After) with simple boxes/arrows (flowchart style).
+- Concept-level only: field/endpoint/step names OK. NO code, NO syntax, NO JSON dumps, NO walls of text.
+- Include a small corner badge text: generated preview
+- If you truly cannot produce a faithful conceptual visual from the diff alone, return {"feasible": false, "reason": "..."}. Prefer a simple flowchart over declining.
+
+Return JSON only:
+{"feasible": true, "html": "..."}
+or {"feasible": false, "reason": "..."}
+
+Change summary:
+${JSON.stringify(options.summary, null, 2)}
+
+Diff:
+${options.diffText}
+`;
+    const raw = await options.provider.complete(prompt, { model: options.model });
+    const json = extractJson(raw);
+    if (!json.feasible || !json.html) {
+        options.log?.(json.reason ?? "diagram not feasible");
+        return { feasible: false, reason: json.reason ?? "not feasible" };
+    }
+    mkdirSync(options.outDir, { recursive: true });
+    const htmlPath = join(options.outDir, "diagram.html");
+    writeFileSync(htmlPath, json.html, "utf8");
+    return { feasible: true, htmlPath };
+}

package/dist/visual/gate.d.ts

@@ -0,0 +1,11 @@
+import type { DiffFile } from "../git.js";
+export type GateDecision = "mockup" | "diagram" | "none";
+/**
+ * Prefer a visual whenever possible:
+ * - UI markup/style → mockup
+ * - everything else with real file changes → diagram (flowchart / concept before-after)
+ * - none only when there is nothing to depict
+ *
+ * The model can still return feasible:false so we never invent a bad visual.
+ */
+export declare function decideGate(files: DiffFile[]): GateDecision;