@ahmedalbarghouti/farq 0.0.2 → 0.1.0

package/dist/ui/lines.d.ts

@@ -1,3 +1,21 @@
 import type { ProviderName } from "../config.js";
-export type LineBank = "summarize" | "visual" | "open" | "diff";
+/**
+ * Rotating status lines. `{p}` is replaced with the provider name so a line
+ * always says who is doing the work. Keep templates <= 37 chars so the longest
+ * provider name still fits the one-line spinner.
+ */
+declare const BANKS: {
+    diff: string[];
+    summarize: string[];
+    topics: string[];
+    mockup: string[];
+    diagram: string[];
+    shoot: string[];
+    visual: string[];
+    open: string[];
+};
+export type LineBank = keyof typeof BANKS;
 export declare function linesFor(bank: LineBank, provider?: ProviderName): string[];
+/** Short, honest name for the stage — the witty line sits next to it. */
+export declare function labelFor(bank: LineBank): string;
+export {};

package/dist/ui/lines.js

@@ -1,48 +1,90 @@
-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…",
+/**
+ * Rotating status lines. `{p}` is replaced with the provider name so a line
+ * always says who is doing the work. Keep templates <= 37 chars so the longest
+ * provider name still fits the one-line spinner.
+ */
+const BANKS = {
+    diff: [
+        "gathering the diff…",
+        "asking git politely…",
+        "reading what you actually did…",
+        "diffing against the merge base…",
+        "counting the damage…",
     ],
-};
-const VISUAL = {
-    claude: [
-        "claude is sketching a mockup…",
-        "claude is boxing a flowchart…",
-        "chrome is taking the shot…",
+    summarize: [
+        "{p} is reading the diff…",
+        "{p} is grouping the mess…",
+        "{p} is finding the story…",
+        "{p} is naming things (hard part)…",
+        "{p} is deciding what matters…",
+        "{p} is skipping the boring parts…",
+        "{p} is drafting your PR title…",
+        "{p} is writing the blurb…",
     ],
-    opencode: [
-        "opencode is sketching a mockup…",
-        "opencode is boxing a flowchart…",
-        "chrome is taking the shot…",
+    topics: [
+        "planning the visuals…",
+        "splitting the story into scenes…",
+        "deciding how many pictures…",
+        "grouping changes into topics…",
+    ],
+    mockup: [
+        "{p} is sketching the before…",
+        "{p} is sketching the after…",
+        "{p} is laying out the mockup…",
+        "{p} is writing placeholder copy…",
+        "{p} is obeying the design tokens…",
+        "{p} is resisting a redesign…",
+        "{p} is measuring the spacing…",
     ],
-    fake: [
-        "fake is drawing boxes…",
-        "fake is pretending to design…",
+    diagram: [
+        "{p} is boxing a flowchart…",
+        "{p} is drawing arrows…",
+        "{p} is explaining it with boxes…",
+        "{p} is keeping it conceptual…",
+        "{p} is deleting a wall of text…",
+    ],
+    shoot: [
         "chrome is taking the shot…",
+        "chrome is scaling it to fit…",
+        "waiting on headless chrome…",
+        "pressing the shutter…",
+    ],
+    visual: [
+        "{p} is drawing the difference…",
+        "{p} is picking a composition…",
+        "chrome is warming up…",
+        "making the change look obvious…",
+    ],
+    open: [
+        "talking to gh…",
+        "filling the PR template…",
+        "uploading the visuals…",
+        "shipping the PR body…",
+        "almost there…",
     ],
 };
-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…"];
+    const name = provider ?? "claude";
+    return BANKS[bank].map((line) => line.replaceAll("{p}", name));
+}
+/** Short, honest name for the stage — the witty line sits next to it. */
+export function labelFor(bank) {
+    switch (bank) {
+        case "diff":
+            return "diff";
+        case "summarize":
+            return "summary";
+        case "topics":
+            return "planning";
+        case "mockup":
+            return "mockup";
+        case "diagram":
+            return "diagram";
+        case "shoot":
+            return "capture";
+        case "visual":
+            return "visuals";
+        case "open":
+            return "pull request";
     }
-    if (bank === "open")
-        return OPEN;
-    const p = provider ?? "claude";
-    return bank === "summarize" ? SUMMARIZE[p] : VISUAL[p];
 }

package/dist/ui/logger.d.ts

@@ -1,11 +1,18 @@
 import type { ProviderName } from "../config.js";
 import { type LineBank } from "./lines.js";
 import { type SpinnerHandle } from "./spinner.js";
+export type StageOptions = {
+    provider?: ProviderName;
+    /** Override the stage label shown before the witty line. */
+    label?: string;
+};
 export type Ui = {
+    /** Declare how many stages this run will have, so steps read as [2/4]. */
+    plan: (totalSteps: number) => void;
     /** Plain note (no spinner). */
     note: (text: string) => void;
-    /** Start a spinning stage with optional rotating witty lines. */
-    stage: (bank: LineBank, provider?: ProviderName) => SpinnerHandle;
+    /** Start a numbered stage with rotating witty lines. */
+    stage: (bank: LineBank, options?: StageOptions | ProviderName) => SpinnerHandle;
     error: (text: string) => void;
     success: (text: string) => void;
 };

package/dist/ui/logger.js

@@ -1,14 +1,25 @@
-import { linesFor } from "./lines.js";
+import { labelFor, linesFor } from "./lines.js";
 import { startSpinner } from "./spinner.js";
 import { brand, fail, muted, ok } from "./theme.js";
 export function createUi() {
+    let total = 0;
+    let step = 0;
     return {
+        plan(totalSteps) {
+            total = Math.max(0, Math.floor(totalSteps));
+            step = 0;
+        },
         note(text) {
             process.stderr.write(`${brand()} ${muted(text)}\n`);
         },
-        stage(bank, provider) {
-            const lines = linesFor(bank, provider);
-            return startSpinner(lines[0] ?? "working…", lines);
+        stage(bank, options) {
+            const opts = typeof options === "string" ? { provider: options } : (options ?? {});
+            step++;
+            return startSpinner({
+                lines: linesFor(bank, opts.provider),
+                label: opts.label ?? labelFor(bank),
+                step: total > 0 ? { index: Math.min(step, total), total } : undefined,
+            });
         },
         error(text) {
             process.stderr.write(`${brand()} ${fail(text)}\n`);

package/dist/ui/spinner.d.ts

@@ -1,7 +1,20 @@
 export type SpinnerHandle = {
-    update: (text: string) => void;
+    /** Replace the stage label (rarely needed). */
+    update: (label: string) => void;
+    /** Swap the rotating witty lines mid-stage, e.g. summarize → mockup. */
+    setLines: (lines: string[]) => void;
+    /** Concrete sub-stage status shown after the witty line. */
+    detail: (text: string | null) => void;
     succeed: (text: string) => void;
     fail: (text: string) => void;
     stop: () => void;
 };
-export declare function startSpinner(initial: string, rotateLines?: string[]): SpinnerHandle;
+export type SpinnerOptions = {
+    lines: string[];
+    label?: string;
+    step?: {
+        index: number;
+        total: number;
+    };
+};
+export declare function startSpinner(options: SpinnerOptions): SpinnerHandle;

package/dist/ui/spinner.js

@@ -1,46 +1,86 @@
-import { brand, accent, isInteractive, muted, ok, fail } from "./theme.js";
+import { accent, brand, dim, fail, isInteractive, muted, ok } from "./theme.js";
 const FRAMES = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
-export function startSpinner(initial, rotateLines) {
+const FRAME_MS = 80;
+const ROTATE_MS = 2600;
+/** Only surface a timer once a stage is slow enough to feel slow. */
+const ELAPSED_AFTER_MS = 3000;
+export function startSpinner(options) {
     const interactive = isInteractive();
-    let text = initial;
-    let i = 0;
+    const started = Date.now();
+    let label = options.label ?? "working";
+    let lines = rotateOrder(options.lines);
     let lineIdx = 0;
+    let detailText = null;
+    let frame = 0;
     let timer = null;
     let lineTimer = null;
     let stopped = false;
+    let lastStatic = "";
+    const stepTag = options.step
+        ? `[${options.step.index}/${options.step.total}] `
+        : "";
+    const elapsedSeconds = () => (Date.now() - started) / 1000;
+    const compose = () => {
+        const parts = [lines[lineIdx] ?? label];
+        if (detailText)
+            parts.push(detailText);
+        const elapsed = Date.now() - started >= ELAPSED_AFTER_MS
+            ? `${Math.round(elapsedSeconds())}s`
+            : "";
+        const body = parts.join(dim(" · "));
+        const tail = elapsed ? `${dim(" · ")}${dim(elapsed)}` : "";
+        return `${accent(stepTag)}${label}${dim(" · ")}${muted(body)}${tail}`;
+    };
     const render = () => {
         if (!interactive || stopped)
             return;
-        const frame = accent(FRAMES[i % FRAMES.length]);
-        process.stderr.write(`\r\x1b[2K${brand()} ${frame} ${text}`);
-        i++;
+        const line = `${brand()} ${accent(FRAMES[frame % FRAMES.length])} ${compose()}`;
+        process.stderr.write(`\r\x1b[2K${truncate(line)}`);
+        frame++;
+    };
+    const printStatic = () => {
+        const next = detailText ? `${label} · ${detailText}` : label;
+        if (next === lastStatic)
+            return;
+        lastStatic = next;
+        process.stderr.write(`${brand()} ${muted(`${stepTag}${next}`)}\n`);
     };
     if (interactive) {
         render();
-        timer = setInterval(render, 80);
-        if (rotateLines && rotateLines.length > 1) {
+        timer = setInterval(render, FRAME_MS);
+        if (lines.length > 1) {
             lineTimer = setInterval(() => {
-                lineIdx = (lineIdx + 1) % rotateLines.length;
-                text = rotateLines[lineIdx];
-            }, 2000);
+                lineIdx = (lineIdx + 1) % lines.length;
+            }, ROTATE_MS);
         }
     }
     else {
-        process.stderr.write(`${brand()} ${muted(text)}\n`);
+        printStatic();
     }
-    return {
+    const handle = {
         update(next) {
-            text = next;
+            label = next;
+            if (!interactive)
+                printStatic();
+        },
+        setLines(next) {
+            if (next.length === 0)
+                return;
+            lines = rotateOrder(next);
+            lineIdx = 0;
+        },
+        detail(text) {
+            detailText = text && text.trim() ? text.trim() : null;
             if (!interactive)
-                process.stderr.write(`${brand()} ${muted(text)}\n`);
+                printStatic();
         },
-        succeed(next) {
-            this.stop();
-            process.stderr.write(`${brand()} ${ok(next)}\n`);
+        succeed(text) {
+            handle.stop();
+            process.stderr.write(`${brand()} ${ok(text)}${dim(` ${formatDuration(elapsedSeconds())}`)}\n`);
         },
-        fail(next) {
-            this.stop();
-            process.stderr.write(`${brand()} ${fail(next)}\n`);
+        fail(text) {
+            handle.stop();
+            process.stderr.write(`${brand()} ${fail(text)}\n`);
         },
         stop() {
             if (stopped)
@@ -54,4 +94,47 @@ export function startSpinner(initial, rotateLines) {
                 process.stderr.write("\r\x1b[2K");
         },
     };
+    return handle;
+}
+function formatDuration(seconds) {
+    if (seconds < 10)
+        return `${seconds.toFixed(1)}s`;
+    if (seconds < 60)
+        return `${Math.round(seconds)}s`;
+    const mins = Math.floor(seconds / 60);
+    return `${mins}m${String(Math.round(seconds % 60)).padStart(2, "0")}s`;
+}
+/** Keep the first line stable, shuffle the rest so reruns feel different. */
+function rotateOrder(lines) {
+    if (lines.length < 3)
+        return [...lines];
+    const [head, ...tail] = lines;
+    for (let i = tail.length - 1; i > 0; i--) {
+        const j = Math.floor(Math.random() * (i + 1));
+        [tail[i], tail[j]] = [tail[j], tail[i]];
+    }
+    return [head, ...tail];
+}
+/** Trim to the terminal width, ignoring ANSI escapes when measuring. */
+function truncate(line) {
+    const columns = process.stderr.columns ?? 0;
+    if (!columns || columns < 20)
+        return line;
+    const max = columns - 1;
+    let visible = 0;
+    let i = 0;
+    while (i < line.length) {
+        if (line[i] === "\x1b") {
+            const end = line.indexOf("m", i);
+            if (end === -1)
+                break;
+            i = end + 1;
+            continue;
+        }
+        if (visible === max)
+            return `${line.slice(0, i)}…\x1b[0m`;
+        visible++;
+        i++;
+    }
+    return line;
 }

package/dist/ui/theme.d.ts

@@ -3,4 +3,5 @@ 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 dim(text: string): string;
 export declare function isInteractive(): boolean;

package/dist/ui/theme.js

@@ -14,6 +14,9 @@ export function fail(text) {
 export function muted(text) {
     return pc.dim(text);
 }
+export function dim(text) {
+    return pc.dim(text);
+}
 export function isInteractive() {
     return Boolean(process.stderr.isTTY) && process.env.CI !== "true";
 }

package/dist/visual/chrome.js

@@ -2,6 +2,7 @@ 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,7 +10,16 @@ export class ChromeError extends Error {
         this.name = "ChromeError";
     }
 }
+let cachedChromePath = null;
 export function resolveChrome(env = process.env) {
+    if (env === process.env && cachedChromePath)
+        return cachedChromePath;
+    const path = lookupChrome(env);
+    if (env === process.env)
+        cachedChromePath = path;
+    return path;
+}
+function lookupChrome(env) {
     const local = env.LOCALAPPDATA ?? "";
     const pf = env.ProgramFiles ?? "C:\\Program Files";
     const pf86 = env["ProgramFiles(x86)"] ?? "C:\\Program Files (x86)";
@@ -55,13 +65,22 @@ export function resolveChrome(env = process.env) {
 }
 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",
             "--disable-gpu",
             "--hide-scrollbars",
+            "--no-first-run",
+            "--no-default-browser-check",
+            "--disable-extensions",
+            "--disable-background-networking",
+            "--disable-sync",
+            "--disable-dev-shm-usage",
+            "--force-color-profile=srgb",
             `--window-size=${width},${height}`,
             `--screenshot=${options.outPath}`,
             options.url,

package/dist/visual/cluster.d.ts

@@ -0,0 +1,29 @@
+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[];
+};
+/**
+ * Topic grouping, cheapest source first:
+ *   1. visual_topics returned by the summarize call (free — no extra request)
+ *   2. a dedicated cheap-model call
+ *   3. file-overlap union-find
+ * Same-theme items (one feature across many files) → one topic.
+ * Truly unrelated domains → separate topics.
+ */
+export declare function clusterVisualTopics(summary: ChangeSummary, options?: {
+    provider?: Provider;
+    model?: string;
+    maxTopics?: number;
+    log?: (msg: string) => void;
+}): Promise<VisualTopic[]>;
+/** File-overlap union-find (fallback). Exported for tests. */
+export declare function clusterByFileOverlap(summary: ChangeSummary): VisualTopic[];
+/** Merge the smallest topics until at most `limit` remain. */
+export declare function capTopics(topics: VisualTopic[], limit?: number): VisualTopic[];
+/** Build topics from model JSON; null if invalid. Exported for tests. */
+export declare function topicsFromIntentJson(summary: ChangeSummary, raw: unknown): VisualTopic[] | null;