@ahmedalbarghouti/farq 0.0.1

package/dist/visual/gate.js

@@ -0,0 +1,28 @@
+const UI_EXT = /\.(tsx|jsx|vue|svelte|html|htm|css|scss|sass|less|css\.ts|module\.css)$/i;
+const UI_HUNK = /[+-].*(class(Name)?=|style=|styled\.|createGlobalStyle|<([A-Z][A-Za-z0-9]*|[a-z]+)|@media|--[a-z-]+\s*:)/;
+/**
+ * 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 function decideGate(files) {
+    if (files.length === 0)
+        return "none";
+    let uiHits = 0;
+    for (const file of files) {
+        const uiFile = UI_EXT.test(file.path);
+        const patch = file.patch || "";
+        if (uiFile && patch.length > 0) {
+            if (UI_HUNK.test(patch) ||
+                /\.(tsx|jsx|vue|svelte|html)$/i.test(file.path)) {
+                uiHits++;
+            }
+        }
+    }
+    if (uiHits > 0)
+        return "mockup";
+    return "diagram";
+}

package/dist/visual/mockup.d.ts

@@ -0,0 +1,26 @@
+import type { ChangeSummary } from "../schema.js";
+import type { Provider } from "../providers/index.js";
+export type MockupResult = {
+    feasible: true;
+    beforePath: string;
+    afterPath: string;
+    viewport?: {
+        width: number;
+        height: number;
+    };
+} | {
+    feasible: false;
+    reason: string;
+};
+export declare function generateMockup(options: {
+    provider: Provider;
+    summary: ChangeSummary;
+    files: Array<{
+        path: string;
+        before: string;
+        after: string;
+    }>;
+    outDir: string;
+    model?: string;
+    log?: (msg: string) => void;
+}): Promise<MockupResult>;

package/dist/visual/mockup.js

@@ -0,0 +1,46 @@
+import { mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { extractJson } from "../extract-json.js";
+export async function generateMockup(options) {
+    const prompt = `You create faithful before/after HTML mockups from a git diff.
+
+Rules:
+- The diff contains exact before/after markup/styles. Emit two fully self-contained HTML documents (inline CSS, no external requests, system fonts) that render this exact markup with these exact styles.
+- Stub only the minimum: container width, placeholder text where dynamic props appear (realistic neutral placeholders).
+- Do not invent UI that is not present in the code.
+- Never show raw code listings.
+- If you cannot render faithfully, return {"feasible": false, "reason": "..."}.
+
+Return JSON only:
+{"feasible": true, "before_html": "...", "after_html": "...", "viewport": {"width":1280,"height":900}}
+or {"feasible": false, "reason": "..."}
+
+Change summary context:
+${JSON.stringify(options.summary, null, 2)}
+
+File contents:
+${options.files
+        .map((f) => `### ${f.path}\n--- BEFORE ---\n${f.before}\n--- AFTER ---\n${f.after}`)
+        .join("\n\n")}
+`;
+    const raw = await options.provider.complete(prompt, { model: options.model });
+    const json = extractJson(raw);
+    if (!json.feasible) {
+        options.log?.(json.reason ?? "mockup not feasible");
+        return { feasible: false, reason: json.reason ?? "not feasible" };
+    }
+    if (!json.before_html || !json.after_html) {
+        return { feasible: false, reason: "missing before_html/after_html" };
+    }
+    mkdirSync(options.outDir, { recursive: true });
+    const beforePath = join(options.outDir, "before.html");
+    const afterPath = join(options.outDir, "after.html");
+    writeFileSync(beforePath, json.before_html, "utf8");
+    writeFileSync(afterPath, json.after_html, "utf8");
+    return {
+        feasible: true,
+        beforePath,
+        afterPath,
+        viewport: json.viewport,
+    };
+}

package/dist/visual/pipeline.d.ts

@@ -0,0 +1,23 @@
+import type { ChangeSummary } from "../schema.js";
+import type { Provider } from "../providers/index.js";
+import type { GatherDiffResult } from "../git.js";
+export type VisualPipelineResult = {
+    imagePath: string | null;
+    images: string[];
+    softDegraded: boolean;
+    warning?: string;
+};
+export type VisualPipelineOptions = {
+    cwd?: string;
+    outDir?: string;
+    summary: ChangeSummary;
+    diff: GatherDiffResult;
+    provider: Provider;
+    modelCheap?: string;
+    noImages?: boolean;
+    before?: string;
+    after?: string;
+    verbose?: boolean;
+    log?: (msg: string) => void;
+};
+export declare function runVisualPipeline(options: VisualPipelineOptions): Promise<VisualPipelineResult>;

package/dist/visual/pipeline.js

@@ -0,0 +1,126 @@
+import { copyFileSync, mkdirSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import { gatherVisualFileContents } from "../git.js";
+import { decideGate } from "./gate.js";
+import { generateMockup } from "./mockup.js";
+import { generateDiagram } from "./diagram.js";
+import { composeBeforeAfter, ChromeError } from "./compose.js";
+import { screenshotHtml, resolveChrome } from "./chrome.js";
+export async function runVisualPipeline(options) {
+    const cwd = options.cwd ?? process.cwd();
+    const outDir = resolve(cwd, options.outDir ?? ".farq");
+    const log = options.log ?? (() => undefined);
+    const vlog = (msg) => {
+        if (options.verbose)
+            log(msg);
+    };
+    if (options.noImages) {
+        return { imagePath: null, images: [], softDegraded: false };
+    }
+    // Manual screenshots skip generation
+    if (options.before && options.after) {
+        try {
+            mkdirSync(outDir, { recursive: true });
+            const beforeCopy = join(outDir, "before.png");
+            const afterCopy = join(outDir, "after.png");
+            copyFileSync(options.before, beforeCopy);
+            copyFileSync(options.after, afterCopy);
+            const composed = await composeBeforeAfter({
+                cwd,
+                outDir,
+                beforePath: beforeCopy,
+                afterPath: afterCopy,
+                badge: "before / after",
+            });
+            return { imagePath: composed, images: [composed], softDegraded: false };
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            throw new ChromeError(msg);
+        }
+    }
+    const gate = decideGate(options.diff.files);
+    vlog(`visual gate: ${gate}`);
+    if (gate === "none") {
+        return { imagePath: null, images: [], softDegraded: false };
+    }
+    try {
+        resolveChrome();
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return {
+            imagePath: null,
+            images: [],
+            softDegraded: true,
+            warning: msg,
+        };
+    }
+    try {
+        if (gate === "mockup") {
+            const files = await gatherVisualFileContents(cwd, options.diff.files, options.diff.baseRef);
+            const mockup = await generateMockup({
+                provider: options.provider,
+                summary: options.summary,
+                files,
+                outDir,
+                model: options.modelCheap,
+                log: vlog,
+            });
+            if (mockup.feasible) {
+                const beforePng = join(outDir, "before.png");
+                const afterPng = join(outDir, "after.png");
+                await screenshotHtml({
+                    url: pathToFileURL(mockup.beforePath).href,
+                    outPath: beforePng,
+                    width: mockup.viewport?.width,
+                    height: mockup.viewport?.height,
+                });
+                await screenshotHtml({
+                    url: pathToFileURL(mockup.afterPath).href,
+                    outPath: afterPng,
+                    width: mockup.viewport?.width,
+                    height: mockup.viewport?.height,
+                });
+                const composed = await composeBeforeAfter({
+                    cwd,
+                    outDir,
+                    beforePath: beforePng,
+                    afterPath: afterPng,
+                    badge: "generated preview",
+                });
+                return { imagePath: composed, images: [composed], softDegraded: false };
+            }
+            vlog(`mockup infeasible: ${mockup.reason}; trying diagram`);
+        }
+        // diagram path (gate=diagram or mockup downgrade)
+        const diagram = await generateDiagram({
+            provider: options.provider,
+            summary: options.summary,
+            diffText: options.diff.diffText,
+            outDir,
+            model: options.modelCheap,
+            log: vlog,
+        });
+        if (!diagram.feasible) {
+            vlog(`diagram infeasible: ${diagram.reason}`);
+            return { imagePath: null, images: [], softDegraded: false };
+        }
+        const outPng = join(outDir, "before-after.png");
+        await screenshotHtml({
+            url: pathToFileURL(diagram.htmlPath).href,
+            outPath: outPng,
+        });
+        return { imagePath: outPng, images: [outPng], softDegraded: false };
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return {
+            imagePath: null,
+            images: [],
+            softDegraded: true,
+            warning: msg,
+        };
+    }
+}

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@ahmedalbarghouti/farq",
+  "version": "0.0.1",
+  "description": "Turn git branch changes into paste-ready PR/Slack updates with optional before/after visuals",
+  "type": "module",
+  "engines": {
+    "node": ">=20"
+  },
+  "bin": {
+    "farq": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "prepublishOnly": "npm run build",
+    "pretest": "npm run build"
+  },
+  "keywords": [
+    "git",
+    "pr",
+    "cli",
+    "diff",
+    "changelog"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/AhmedAlbarghouti/farq.git"
+  },
+  "dependencies": {
+    "commander": "^13.0.0",
+    "execa": "^9.0.0",
+    "zod": "^3.24.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.7.0",
+    "vitest": "^3.0.0"
+  },
+  "bugs": {
+    "url": "https://github.com/AhmedAlbarghouti/farq/issues"
+  },
+  "homepage": "https://github.com/AhmedAlbarghouti/farq#readme",
+  "publishConfig": {
+    "access": "public"
+  }
+}