@ahmedalbarghouti/farq 0.0.1 → 0.0.3

package/dist/render/pr.d.ts

@@ -1,7 +1,13 @@
 import type { ChangeSummary } from "../schema.js";
+export type PrImage = {
+    path: string;
+    title?: string;
+};
 export type RenderPrOptions = {
     summary: ChangeSummary;
+    /** @deprecated prefer images */
     imagePath?: string | null;
     imageAlt?: string;
+    images?: PrImage[];
 };
 export declare function renderPr(options: RenderPrOptions): string;

package/dist/render/pr.js

@@ -1,4 +1,5 @@
 import { truncateTitle, GITHUB_TITLE_MAX } from "../title.js";
+import { isHostedImageUrl, LOCAL_IMAGE_NOTE } from "../tools.js";
 const EMOJI = {
     feature: "\u2728",
     fix: "\uD83D\uDC1B",
@@ -17,14 +18,30 @@ export function renderPr(options) {
         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._");
+    const images = normalizeImages(options);
+    if (images.length > 0) {
+        const anyLocal = images.some((img) => !isHostedImageUrl(img.path));
+        if (images.length === 1) {
+            out.push("");
+            out.push("### Before / After");
+            out.push("");
+            const alt = images[0].title ?? options.imageAlt ?? "before / after";
+            out.push(`![${alt}](${images[0].path})`);
+        }
+        else {
+            out.push("");
+            out.push("### Visuals");
+            for (const img of images) {
+                out.push("");
+                out.push(`#### ${img.title ?? "Before / After"}`);
+                out.push("");
+                out.push(`![${img.title ?? "before / after"}](${img.path})`);
+            }
+        }
+        if (anyLocal) {
+            out.push("");
+            out.push(LOCAL_IMAGE_NOTE);
+        }
     }
     out.push("");
     out.push("### Changes");
@@ -46,3 +63,11 @@ export function renderPr(options) {
     }
     return `${title}\n\n${out.join("\n").trim()}\n`;
 }
+function normalizeImages(options) {
+    if (options.images && options.images.length > 0)
+        return options.images;
+    if (options.imagePath) {
+        return [{ path: options.imagePath, title: options.imageAlt }];
+    }
+    return [];
+}

package/dist/template.d.ts

@@ -1,10 +1,16 @@
 import type { ChangeSummary } from "./schema.js";
 export declare function findPrTemplate(cwd: string): string | null;
+export type TemplateImage = {
+    url: string;
+    title?: string;
+};
 export declare function fillPrTemplate(options: {
     template: string | null;
     summary: ChangeSummary;
     bodyMarkdown: string;
+    /** @deprecated prefer images */
     imageUrl?: string | null;
+    images?: TemplateImage[];
 }): {
     title: string;
     body: string;

package/dist/template.js

@@ -1,6 +1,7 @@
 import { existsSync, readdirSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { truncateTitle, GITHUB_TITLE_MAX } from "./title.js";
+import { stripLocalImageNote } from "./tools.js";
 export function findPrTemplate(cwd) {
     const single = join(cwd, ".github", "pull_request_template.md");
     if (existsSync(single))
@@ -18,23 +19,18 @@ export function findPrTemplate(cwd) {
 }
 export function fillPrTemplate(options) {
     const { title, overflow } = truncateTitle(options.summary.headline, GITHUB_TITLE_MAX);
+    const images = normalizeTemplateImages(options);
     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;
+        if (images.length > 0) {
+            body = replaceLocalImages(body, images);
+            if (!hasMarkdownImage(body)) {
+                body = renderImageMarkdown(images) + "\n\n" + body;
             }
+            body = stripLocalImageNote(body);
         }
         return { title, body };
     }
@@ -48,19 +44,48 @@ export function fillPrTemplate(options) {
     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 + ")");
+    if (images.length > 0) {
+        const md = renderImageMarkdown(images);
+        if (/before\s*\/\s*after|screenshots?|visuals?/i.test(body)) {
+            body = fillSection(body, /before\s*\/\s*after|screenshots?|visuals?/i, md.replace(/^###[^\n]+\n+/, "").trim());
         }
         else {
-            body +=
-                "\n\n### Before / After\n\n![before / after](" +
-                    options.imageUrl +
-                    ")\n";
+            body += "\n\n" + md + "\n";
         }
+        body = stripLocalImageNote(body);
     }
     return { title, body };
 }
+function normalizeTemplateImages(options) {
+    if (options.images && options.images.length > 0)
+        return options.images;
+    if (options.imageUrl)
+        return [{ url: options.imageUrl }];
+    return [];
+}
+function hasMarkdownImage(body) {
+    return /!\[[^\]]*\]\([^)]+\)/.test(body);
+}
+function replaceLocalImages(body, images) {
+    let i = 0;
+    return body.replace(/!\[([^\]]*)\]\((?!https?:\/\/)[^)]+\)/g, (_m, alt) => {
+        const img = images[Math.min(i, images.length - 1)];
+        i += 1;
+        return `![${alt || img.title || "before / after"}](${img.url})`;
+    });
+}
+function renderImageMarkdown(images) {
+    if (images.length === 1) {
+        const alt = images[0].title ?? "before / after";
+        return `### Before / After\n\n![${alt}](${images[0].url})`;
+    }
+    const parts = ["### Visuals"];
+    for (const img of images) {
+        const alt = img.title ?? "before / after";
+        parts.push("", `#### ${alt}`, "", `![${alt}](${img.url})`);
+    }
+    return parts.join("\n");
+}
 function fillSection(template, heading, content) {
     const lines = template.split("\n");
     let inSection = false;

package/dist/tools.d.ts

@@ -0,0 +1,21 @@
+export declare class ToolNotFoundError extends Error {
+    constructor(message: string);
+}
+/** True when the image reference is already a hosted URL. */
+export declare function isHostedImageUrl(ref: string): boolean;
+/** Italic note appended for local-only image paths in PR markdown. */
+export declare const LOCAL_IMAGE_NOTE = "_Local image path - attach the file when pasting into GitHub if it does not render._";
+/** Strip the local-image attach note from PR markdown. */
+export declare function stripLocalImageNote(body: string): string;
+/**
+ * Resolve an executable: env override, then PATH, then extra candidate paths.
+ */
+export declare function resolveExecutable(names: string[], options: {
+    env?: NodeJS.ProcessEnv;
+    envKey?: string;
+    extraPaths?: string[];
+    notFoundMessage: string;
+}): string;
+export declare function resolveGh(env?: NodeJS.ProcessEnv): string;
+/** Reset cache (tests). */
+export declare function resetGhCache(): void;

package/dist/tools.js

@@ -0,0 +1,95 @@
+import { existsSync } from "node:fs";
+import { delimiter, join } from "node:path";
+import { platform } from "node:os";
+export class ToolNotFoundError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "ToolNotFoundError";
+    }
+}
+/** True when the image reference is already a hosted URL. */
+export function isHostedImageUrl(ref) {
+    return /^https?:\/\//i.test(ref.trim());
+}
+/** Italic note appended for local-only image paths in PR markdown. */
+export const LOCAL_IMAGE_NOTE = "_Local image path - attach the file when pasting into GitHub if it does not render._";
+/** Strip the local-image attach note from PR markdown. */
+export function stripLocalImageNote(body) {
+    return body
+        .replace(/\n*_Local image path[^\n]*_\s*/g, "\n")
+        .replace(/\n{3,}/g, "\n\n");
+}
+/**
+ * Resolve an executable: env override, then PATH, then extra candidate paths.
+ */
+export function resolveExecutable(names, options) {
+    const env = options.env ?? process.env;
+    if (options.envKey && env[options.envKey]) {
+        const forced = env[options.envKey];
+        if (existsSync(forced))
+            return forced;
+        throw new ToolNotFoundError(`${options.envKey} not found: ${forced}`);
+    }
+    const pathEnv = env.PATH ?? env.Path ?? "";
+    const dirs = pathEnv.split(delimiter).filter(Boolean);
+    const win = platform() === "win32";
+    const exts = win
+        ? (env.PATHEXT ?? ".EXE;.CMD;.BAT;.COM")
+            .split(";")
+            .map((e) => e.toLowerCase())
+        : [""];
+    const tryName = (dir, name) => {
+        if (win) {
+            if (name.includes(".")) {
+                const p = join(dir, name);
+                return existsSync(p) ? p : null;
+            }
+            for (const ext of exts) {
+                const p = join(dir, name + ext);
+                if (existsSync(p))
+                    return p;
+            }
+            return null;
+        }
+        const p = join(dir, name);
+        return existsSync(p) ? p : null;
+    };
+    for (const dir of dirs) {
+        for (const name of names) {
+            const hit = tryName(dir, name);
+            if (hit)
+                return hit;
+        }
+    }
+    for (const candidate of options.extraPaths ?? []) {
+        if (candidate && existsSync(candidate))
+            return candidate;
+    }
+    throw new ToolNotFoundError(options.notFoundMessage);
+}
+let cachedGh;
+export function resolveGh(env = process.env) {
+    if (cachedGh)
+        return cachedGh;
+    const local = env.LOCALAPPDATA ?? "";
+    const pf = env.ProgramFiles ?? "C:\\Program Files";
+    const pf86 = env["ProgramFiles(x86)"] ?? "C:\\Program Files (x86)";
+    cachedGh = resolveExecutable(["gh", "gh.exe"], {
+        env,
+        envKey: "GH_PATH",
+        extraPaths: [
+            join(pf, "GitHub CLI", "gh.exe"),
+            join(pf86, "GitHub CLI", "gh.exe"),
+            join(local, "Programs", "GitHub CLI", "gh.exe"),
+            "/usr/local/bin/gh",
+            "/opt/homebrew/bin/gh",
+            "/usr/bin/gh",
+        ],
+        notFoundMessage: "gh not found — install GitHub CLI (https://cli.github.com) or set GH_PATH",
+    });
+    return cachedGh;
+}
+/** Reset cache (tests). */
+export function resetGhCache() {
+    cachedGh = undefined;
+}

package/dist/ui/index.d.ts

@@ -0,0 +1,2 @@
+export { createUi, type Ui } from "./logger.js";
+export { brand, isInteractive } from "./theme.js";

package/dist/ui/index.js

@@ -0,0 +1,2 @@
+export { createUi } from "./logger.js";
+export { brand, isInteractive } from "./theme.js";

package/dist/ui/lines.d.ts

@@ -0,0 +1,3 @@
+import type { ProviderName } from "../config.js";
+export type LineBank = "summarize" | "visual" | "open" | "diff";
+export declare function linesFor(bank: LineBank, provider?: ProviderName): string[];

package/dist/ui/lines.js

@@ -0,0 +1,48 @@
+const SUMMARIZE = {
+    claude: [
+        "claude is reading the diff…",
+        "claude is grouping the mess…",
+        "claude is writing the blurb…",
+    ],
+    opencode: [
+        "opencode is reading the diff…",
+        "opencode is grouping the mess…",
+        "opencode is writing the blurb…",
+    ],
+    fake: [
+        "fake is vibing on hard mode…",
+        "fake is inventing nothing new…",
+        "fake is shipping canned vibes…",
+    ],
+};
+const VISUAL = {
+    claude: [
+        "claude is sketching a mockup…",
+        "claude is boxing a flowchart…",
+        "chrome is taking the shot…",
+    ],
+    opencode: [
+        "opencode is sketching a mockup…",
+        "opencode is boxing a flowchart…",
+        "chrome is taking the shot…",
+    ],
+    fake: [
+        "fake is drawing boxes…",
+        "fake is pretending to design…",
+        "chrome is taking the shot…",
+    ],
+};
+const OPEN = [
+    "talking to gh…",
+    "shipping the PR body…",
+    "almost there…",
+];
+export function linesFor(bank, provider) {
+    if (bank === "diff") {
+        return ["gathering the diff…", "asking git politely…"];
+    }
+    if (bank === "open")
+        return OPEN;
+    const p = provider ?? "claude";
+    return bank === "summarize" ? SUMMARIZE[p] : VISUAL[p];
+}

package/dist/ui/logger.d.ts

@@ -0,0 +1,12 @@
+import type { ProviderName } from "../config.js";
+import { type LineBank } from "./lines.js";
+import { type SpinnerHandle } from "./spinner.js";
+export type Ui = {
+    /** Plain note (no spinner). */
+    note: (text: string) => void;
+    /** Start a spinning stage with optional rotating witty lines. */
+    stage: (bank: LineBank, provider?: ProviderName) => SpinnerHandle;
+    error: (text: string) => void;
+    success: (text: string) => void;
+};
+export declare function createUi(): Ui;

package/dist/ui/logger.js

@@ -0,0 +1,20 @@
+import { linesFor } from "./lines.js";
+import { startSpinner } from "./spinner.js";
+import { brand, fail, muted, ok } from "./theme.js";
+export function createUi() {
+    return {
+        note(text) {
+            process.stderr.write(`${brand()} ${muted(text)}\n`);
+        },
+        stage(bank, provider) {
+            const lines = linesFor(bank, provider);
+            return startSpinner(lines[0] ?? "working…", lines);
+        },
+        error(text) {
+            process.stderr.write(`${brand()} ${fail(text)}\n`);
+        },
+        success(text) {
+            process.stderr.write(`${brand()} ${ok(text)}\n`);
+        },
+    };
+}

package/dist/ui/spinner.d.ts

@@ -0,0 +1,7 @@
+export type SpinnerHandle = {
+    update: (text: string) => void;
+    succeed: (text: string) => void;
+    fail: (text: string) => void;
+    stop: () => void;
+};
+export declare function startSpinner(initial: string, rotateLines?: string[]): SpinnerHandle;

package/dist/ui/spinner.js

@@ -0,0 +1,57 @@
+import { brand, accent, isInteractive, muted, ok, fail } from "./theme.js";
+const FRAMES = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+export function startSpinner(initial, rotateLines) {
+    const interactive = isInteractive();
+    let text = initial;
+    let i = 0;
+    let lineIdx = 0;
+    let timer = null;
+    let lineTimer = null;
+    let stopped = false;
+    const render = () => {
+        if (!interactive || stopped)
+            return;
+        const frame = accent(FRAMES[i % FRAMES.length]);
+        process.stderr.write(`\r\x1b[2K${brand()} ${frame} ${text}`);
+        i++;
+    };
+    if (interactive) {
+        render();
+        timer = setInterval(render, 80);
+        if (rotateLines && rotateLines.length > 1) {
+            lineTimer = setInterval(() => {
+                lineIdx = (lineIdx + 1) % rotateLines.length;
+                text = rotateLines[lineIdx];
+            }, 2000);
+        }
+    }
+    else {
+        process.stderr.write(`${brand()} ${muted(text)}\n`);
+    }
+    return {
+        update(next) {
+            text = next;
+            if (!interactive)
+                process.stderr.write(`${brand()} ${muted(text)}\n`);
+        },
+        succeed(next) {
+            this.stop();
+            process.stderr.write(`${brand()} ${ok(next)}\n`);
+        },
+        fail(next) {
+            this.stop();
+            process.stderr.write(`${brand()} ${fail(next)}\n`);
+        },
+        stop() {
+            if (stopped)
+                return;
+            stopped = true;
+            if (timer)
+                clearInterval(timer);
+            if (lineTimer)
+                clearInterval(lineTimer);
+            if (interactive)
+                process.stderr.write("\r\x1b[2K");
+        },
+    };
+}

package/dist/ui/theme.d.ts

@@ -0,0 +1,6 @@
+export declare function brand(): string;
+export declare function accent(text: string): string;
+export declare function ok(text: string): string;
+export declare function fail(text: string): string;
+export declare function muted(text: string): string;
+export declare function isInteractive(): boolean;

package/dist/ui/theme.js

@@ -0,0 +1,19 @@
+import pc from "picocolors";
+export function brand() {
+    return pc.dim("farq");
+}
+export function accent(text) {
+    return pc.cyan(text);
+}
+export function ok(text) {
+    return `${pc.cyan("✓")} ${pc.dim(text)}`;
+}
+export function fail(text) {
+    return `${pc.red("✗")} ${text}`;
+}
+export function muted(text) {
+    return pc.dim(text);
+}
+export function isInteractive() {
+    return Boolean(process.stderr.isTTY) && process.env.CI !== "true";
+}

package/dist/visual/chrome.js

@@ -1,6 +1,8 @@
-import { existsSync } from "node:fs";
 import { execa } from "execa";
 import { platform } from "node:os";
+import { join } from "node:path";
+import { resolveExecutable, ToolNotFoundError, } from "../tools.js";
+import { clampViewport } from "./viewport.js";
 const TIMEOUT_MS = 30_000;
 export class ChromeError extends Error {
     constructor(message) {
@@ -9,17 +11,15 @@ export class ChromeError extends Error {
     }
 }
 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"
+    const local = env.LOCALAPPDATA ?? "";
+    const pf = env.ProgramFiles ?? "C:\\Program Files";
+    const pf86 = env["ProgramFiles(x86)"] ?? "C:\\Program Files (x86)";
+    const extraPaths = 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",
+            join(pf, "Google", "Chrome", "Application", "chrome.exe"),
+            join(pf86, "Google", "Chrome", "Application", "chrome.exe"),
+            join(local, "Google", "Chrome", "Application", "chrome.exe"),
+            join(pf, "Chromium", "Application", "chrome.exe"),
         ]
         : platform() === "darwin"
             ? [
@@ -32,16 +32,34 @@ export function resolveChrome(env = process.env) {
                 "/usr/bin/chromium",
                 "/usr/bin/chromium-browser",
             ];
-    for (const c of candidates) {
-        if (c && existsSync(c))
-            return c;
+    try {
+        return resolveExecutable([
+            "google-chrome",
+            "google-chrome-stable",
+            "chromium",
+            "chromium-browser",
+            "chrome",
+            "chrome.exe",
+        ], {
+            env,
+            envKey: "CHROME_PATH",
+            extraPaths,
+            notFoundMessage: "Chrome/Chromium not found — install Google Chrome or set CHROME_PATH",
+        });
+    }
+    catch (err) {
+        if (err instanceof ToolNotFoundError) {
+            throw new ChromeError(err.message);
+        }
+        throw err;
     }
-    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;
+    const { width, height } = clampViewport({
+        width: options.width,
+        height: options.height,
+    });
     try {
         await execa(chrome, [
             "--headless=new",

package/dist/visual/cluster.d.ts

@@ -0,0 +1,23 @@
+import type { ChangeItem, ChangeSummary } from "../schema.js";
+import type { Provider } from "../providers/index.js";
+export declare const MAX_VISUAL_TOPICS = 5;
+export type VisualTopic = {
+    id: number;
+    title: string;
+    items: ChangeItem[];
+    files: string[];
+};
+/**
+ * Prefer intent clustering via the cheap model; fall back to file-overlap.
+ * Same-theme items (one feature across many files) → one topic.
+ * Truly unrelated domains → separate topics (cap 5).
+ */
+export declare function clusterVisualTopics(summary: ChangeSummary, options?: {
+    provider?: Provider;
+    model?: string;
+    log?: (msg: string) => void;
+}): Promise<VisualTopic[]>;
+/** File-overlap union-find (fallback). Exported for tests. */
+export declare function clusterByFileOverlap(summary: ChangeSummary): VisualTopic[];
+/** Build topics from model JSON; null if invalid. Exported for tests. */
+export declare function topicsFromIntentJson(summary: ChangeSummary, raw: unknown): VisualTopic[] | null;