@ahmedalbarghouti/farq 0.0.1

package/dist/index.js

@@ -0,0 +1,204 @@
+#!/usr/bin/env node
+import { Command } from "commander";
+import { relative, resolve } from "node:path";
+import { loadConfig, mergeConfig } from "./config.js";
+import { gatherDiff, NoChangesError, GitError } from "./git.js";
+import { resolveProvider } from "./providers/index.js";
+import { summarize, SummarizeError } from "./summarize.js";
+import { inferTitleConvention } from "./title.js";
+import { fetchRecentPrTitles, openPullRequest } from "./open-pr.js";
+import { runVisualPipeline } from "./visual/pipeline.js";
+import { ChromeError } from "./visual/chrome.js";
+import { renderPr } from "./render/pr.js";
+import { renderSlack } from "./render/slack.js";
+import { renderJson } from "./render/json.js";
+async function run(type, opts) {
+    const cwd = process.cwd();
+    const fileConfig = loadConfig({ cwd });
+    const flagConfig = {
+        provider: opts.provider,
+        tone: opts.tone,
+        models: opts.modelCheap
+            ? {
+                claudeCheap: opts.modelCheap,
+                opencodeCheap: opts.modelCheap,
+            }
+            : undefined,
+    };
+    const config = mergeConfig(fileConfig, flagConfig);
+    const log = (msg) => {
+        console.error(msg);
+    };
+    let provider;
+    try {
+        provider = await resolveProvider({
+            flag: config.provider,
+            config,
+            log,
+        });
+    }
+    catch (err) {
+        log(err instanceof Error ? err.message : String(err));
+        return 1;
+    }
+    const tone = config.tone ?? "technical";
+    const imagesEnabled = type === "pr" ? !opts.noImages : false;
+    let diff;
+    try {
+        log("farq: gathering diff…");
+        diff = await gatherDiff({ cwd, range: opts.range });
+    }
+    catch (err) {
+        if (err instanceof NoChangesError || err instanceof GitError) {
+            log(err.message);
+            return 1;
+        }
+        log(err instanceof Error ? err.message : String(err));
+        return 1;
+    }
+    let titleBlurb = "";
+    if (type === "pr") {
+        try {
+            const titles = await fetchRecentPrTitles(cwd);
+            titleBlurb = inferTitleConvention(titles).blurb;
+        }
+        catch {
+            // optional
+        }
+    }
+    log(`farq: summarizing with ${provider.name}…`);
+    let summary;
+    try {
+        summary = await summarize({
+            provider,
+            diff,
+            tone,
+            titleConventionBlurb: titleBlurb || undefined,
+        });
+    }
+    catch (err) {
+        if (err instanceof SummarizeError) {
+            log(err.message);
+            return 2;
+        }
+        log(err instanceof Error ? err.message : String(err));
+        return 2;
+    }
+    const cheapModel = provider.name === "claude"
+        ? config.models?.claudeCheap
+        : provider.name === "opencode"
+            ? config.models?.opencodeCheap ?? process.env.FARQ_OPENCODE_MODEL
+            : undefined;
+    let imagePath = null;
+    let images = [];
+    if (imagesEnabled || (opts.before && opts.after)) {
+        log("farq: visual pipeline…");
+        try {
+            const visual = await runVisualPipeline({
+                cwd,
+                outDir: opts.out ?? ".farq",
+                summary,
+                diff,
+                provider,
+                modelCheap: cheapModel,
+                noImages: opts.noImages && !(opts.before && opts.after),
+                before: opts.before,
+                after: opts.after,
+                verbose: opts.verbose,
+                log: opts.verbose ? log : () => undefined,
+            });
+            imagePath = visual.imagePath;
+            images = visual.images;
+            if (visual.warning)
+                log(`farq: ${visual.warning}`);
+        }
+        catch (err) {
+            if (err instanceof ChromeError && opts.before && opts.after) {
+                log(err.message);
+                return 1;
+            }
+            log(`farq: ${err instanceof Error ? err.message : String(err)} (continuing without image)`);
+        }
+    }
+    const relImage = imagePath != null ? relative(cwd, resolve(imagePath)).replaceAll("\\", "/") : null;
+    let artifact = "";
+    if (type === "pr") {
+        artifact = renderPr({ summary, imagePath: relImage });
+    }
+    else if (type === "slack") {
+        artifact = renderSlack(summary);
+    }
+    else {
+        artifact = renderJson(summary, images.map((p) => relative(cwd, p).replaceAll("\\", "/")));
+    }
+    if (type === "pr" && opts.open) {
+        log("farq: opening PR…");
+        try {
+            const result = await openPullRequest({
+                cwd,
+                summary,
+                bodyMarkdown: artifact.includes("\n\n")
+                    ? artifact.split("\n\n").slice(1).join("\n\n")
+                    : artifact,
+                imagePath,
+            });
+            if (result.skipped) {
+                log(`farq: ${result.reason}`);
+            }
+            else {
+                log(`farq: PR ${result.action}${result.url ? ` — ${result.url}` : ""}`);
+                if (result.warning)
+                    log(`farq: ${result.warning}`);
+            }
+        }
+        catch (err) {
+            log(err instanceof Error ? err.message : String(err));
+            return 1;
+        }
+    }
+    process.stdout.write(artifact);
+    return 0;
+}
+function addShared(cmd) {
+    return cmd
+        .option("-r, --range <range>", "git range, e.g. main..feature")
+        .option("-p, --provider <name>", "claude | opencode | fake")
+        .option("-t, --tone <tone>", "technical | client", "technical")
+        .option("--before <path>", "manual before screenshot")
+        .option("--after <path>", "manual after screenshot")
+        .option("--no-images", "skip image generation/composition")
+        .option("-o, --out <dir>", "output dir for images", ".farq")
+        .option("--model-cheap <id>", "model for visual generation")
+        .option("-v, --verbose", "verbose logging", false);
+}
+async function main() {
+    const program = new Command();
+    program
+        .name("farq")
+        .description("Turn git branch changes into paste-ready PR/Slack updates with optional before/after visuals")
+        .version("0.0.1");
+    addShared(program
+        .command("pr", { isDefault: true })
+        .description("PR title + body markdown")
+        .option("--open", "create a GitHub PR with gh (template-aware)", false)
+        .action(async (opts) => {
+        process.exitCode = await run("pr", opts);
+    }));
+    addShared(program
+        .command("slack")
+        .description("Slack mrkdwn daily update")
+        .action(async (opts) => {
+        process.exitCode = await run("slack", { ...opts, noImages: true });
+    }));
+    addShared(program
+        .command("json")
+        .description("Structured ChangeSummary JSON")
+        .action(async (opts) => {
+        process.exitCode = await run("json", { ...opts, noImages: true });
+    }));
+    await program.parseAsync(process.argv);
+}
+main().catch((err) => {
+    console.error(err instanceof Error ? err.message : String(err));
+    process.exitCode = 1;
+});

package/dist/open-pr.d.ts

@@ -0,0 +1,26 @@
+import type { ChangeSummary } from "./schema.js";
+export type OpenPrResult = {
+    skipped: true;
+    reason: string;
+} | {
+    skipped: false;
+    action: "created" | "updated";
+    url?: string;
+    warning?: string;
+};
+export declare function resolveDefaultBranch(cwd: string): Promise<string>;
+export declare function currentBranch(cwd: string): Promise<string>;
+export declare function fetchRecentPrTitles(cwd: string, limit?: number): Promise<string[]>;
+/** Existing open PR for the current branch, if any. */
+export declare function findExistingPr(cwd: string): Promise<{
+    number: number;
+    url: string;
+} | null>;
+export declare function openPullRequest(options: {
+    cwd: string;
+    summary: ChangeSummary;
+    bodyMarkdown: string;
+    imagePath?: string | null;
+}): Promise<OpenPrResult>;
+/** Best-effort: prerelease asset URL for the PNG. */
+export declare function uploadPrImage(cwd: string, imagePath: string, branch: string): Promise<string>;

package/dist/open-pr.js

@@ -0,0 +1,199 @@
+import { mkdtempSync, writeFileSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { execa } from "execa";
+import { fillPrTemplate, findPrTemplate } from "./template.js";
+const GH_TIMEOUT = 60_000;
+export async function resolveDefaultBranch(cwd) {
+    try {
+        const { stdout } = await execa("gh", [
+            "repo",
+            "view",
+            "--json",
+            "defaultBranchRef",
+            "--jq",
+            ".defaultBranchRef.name",
+        ], { cwd, timeout: GH_TIMEOUT, reject: true });
+        if (stdout.trim())
+            return stdout.trim();
+    }
+    catch {
+        // fall through
+    }
+    for (const name of ["main", "master"]) {
+        try {
+            await execa("git", ["rev-parse", "--verify", name], {
+                cwd,
+                timeout: 10_000,
+                reject: true,
+            });
+            return name;
+        }
+        catch {
+            // try next
+        }
+    }
+    return "main";
+}
+export async function currentBranch(cwd) {
+    const { stdout } = await execa("git", ["rev-parse", "--abbrev-ref", "HEAD"], {
+        cwd,
+        timeout: 10_000,
+        reject: true,
+    });
+    return stdout.trim();
+}
+export async function fetchRecentPrTitles(cwd, limit = 20) {
+    try {
+        const { stdout } = await execa("gh", [
+            "pr",
+            "list",
+            "--state",
+            "merged",
+            "--limit",
+            String(limit),
+            "--json",
+            "title",
+            "--jq",
+            ".[].title",
+        ], { cwd, timeout: GH_TIMEOUT, reject: true });
+        return stdout
+            .split("\n")
+            .map((s) => s.trim())
+            .filter(Boolean);
+    }
+    catch {
+        return [];
+    }
+}
+/** Existing open PR for the current branch, if any. */
+export async function findExistingPr(cwd) {
+    try {
+        const { stdout, exitCode } = await execa("gh", ["pr", "view", "--json", "number,url"], { cwd, timeout: GH_TIMEOUT, reject: false });
+        if (exitCode !== 0 || !stdout.trim())
+            return null;
+        const parsed = JSON.parse(stdout);
+        if (typeof parsed.number === "number" && typeof parsed.url === "string") {
+            return { number: parsed.number, url: parsed.url };
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+export async function openPullRequest(options) {
+    const cwd = options.cwd;
+    const branch = await currentBranch(cwd);
+    const defaultBranch = await resolveDefaultBranch(cwd);
+    if (branch === defaultBranch) {
+        return {
+            skipped: true,
+            reason: `Already on ${defaultBranch} — skipping PR create`,
+        };
+    }
+    let imageUrl = null;
+    let warning;
+    if (options.imagePath) {
+        try {
+            imageUrl = await uploadPrImage(cwd, options.imagePath, branch);
+        }
+        catch (err) {
+            warning = `Image upload failed — attach manually: ${options.imagePath} (${err instanceof Error ? err.message : String(err)})`;
+        }
+    }
+    const template = findPrTemplate(cwd);
+    const { title, body } = fillPrTemplate({
+        template,
+        summary: options.summary,
+        bodyMarkdown: options.bodyMarkdown,
+        imageUrl,
+    });
+    const dir = mkdtempSync(join(tmpdir(), "farq-pr-"));
+    const bodyFile = join(dir, "body.md");
+    writeFileSync(bodyFile, body, "utf8");
+    try {
+        const existing = await findExistingPr(cwd);
+        if (existing) {
+            await execa("gh", [
+                "pr",
+                "edit",
+                String(existing.number),
+                "--title",
+                title,
+                "--body-file",
+                bodyFile,
+            ], { cwd, timeout: GH_TIMEOUT, reject: true });
+            try {
+                await execa("gh", ["pr", "view", "--web"], {
+                    cwd,
+                    timeout: GH_TIMEOUT,
+                    reject: false,
+                });
+            }
+            catch {
+                // non-fatal
+            }
+            return {
+                skipped: false,
+                action: "updated",
+                url: existing.url,
+                warning,
+            };
+        }
+        const created = await execa("gh", ["pr", "create", "--title", title, "--body-file", bodyFile], { cwd, timeout: GH_TIMEOUT, reject: true });
+        try {
+            await execa("gh", ["pr", "view", "--web"], {
+                cwd,
+                timeout: GH_TIMEOUT,
+                reject: false,
+            });
+        }
+        catch {
+            // non-fatal
+        }
+        return {
+            skipped: false,
+            action: "created",
+            url: created.stdout?.trim() || undefined,
+            warning,
+        };
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        throw new Error(`gh pr create/edit failed: ${msg}`);
+    }
+    finally {
+        rmSync(dir, { recursive: true, force: true });
+    }
+}
+/** Best-effort: prerelease asset URL for the PNG. */
+export async function uploadPrImage(cwd, imagePath, branch) {
+    const tag = `farq-assets-${branch.replace(/[^a-zA-Z0-9._-]/g, "-").slice(0, 40)}`;
+    try {
+        await execa("gh", ["release", "delete", tag, "--yes", "--cleanup-tag"], {
+            cwd,
+            timeout: GH_TIMEOUT,
+            reject: false,
+        });
+    }
+    catch {
+        // ok if missing
+    }
+    await execa("gh", [
+        "release",
+        "create",
+        tag,
+        imagePath,
+        "--title",
+        `farq assets (${branch})`,
+        "--notes",
+        "Auto-uploaded by farq for PR description embedding.",
+        "--prerelease",
+    ], { cwd, timeout: GH_TIMEOUT, reject: true });
+    const { stdout } = await execa("gh", ["release", "view", tag, "--json", "assets", "--jq", ".assets[0].url"], { cwd, timeout: GH_TIMEOUT, reject: true });
+    const url = stdout.trim();
+    if (!url)
+        throw new Error("no asset URL returned");
+    return url;
+}

package/dist/providers/claude.d.ts

@@ -0,0 +1,3 @@
+import type { CompleteOptions } from "./fake.js";
+export declare function complete(prompt: string, options?: CompleteOptions): Promise<string>;
+export declare function isInstalled(): Promise<boolean>;

package/dist/providers/claude.js

@@ -0,0 +1,88 @@
+import { execa } from "execa";
+const TIMEOUT_MS = 120_000;
+export async function complete(prompt, options = {}) {
+    const baseArgs = ["-p", "--output-format", "json", "--max-turns", "1"];
+    if (options.model)
+        baseArgs.push("--model", options.model);
+    // Prefer without allowedTools first — empty allowedTools hangs/fails on some versions.
+    const attempts = [[...baseArgs], [...baseArgs, "--allowedTools", ""]];
+    let lastErr;
+    for (const args of attempts) {
+        try {
+            const result = await execa("claude", args, {
+                input: prompt,
+                timeout: TIMEOUT_MS,
+                reject: false,
+                stdout: "pipe",
+                stderr: "pipe",
+            });
+            if (result.timedOut) {
+                throw new Error("claude did not respond — check that it's authenticated (`claude` login)");
+            }
+            const text = (result.stdout || result.stderr || "").trim();
+            if (!text && result.exitCode !== 0) {
+                throw new Error(`claude failed (exit ${result.exitCode}): ${(result.stderr || "no output").trim()}`);
+            }
+            try {
+                return parseClaudeOutput(text);
+            }
+            catch (parseErr) {
+                // Retry next arg set only when allowedTools looks unsupported
+                if (args.includes("--allowedTools") &&
+                    /allowedTools|unknown option|unexpected/i.test(`${result.stderr ?? ""} ${text}`)) {
+                    lastErr = parseErr;
+                    continue;
+                }
+                throw parseErr;
+            }
+        }
+        catch (err) {
+            const e = err;
+            if (e.timedOut || /did not respond/i.test(e.message ?? "")) {
+                throw new Error("claude did not respond — check that it's authenticated (`claude` login)");
+            }
+            lastErr = err;
+            if (!args.includes("--allowedTools")) {
+                // try with allowedTools only if first attempt was a flag-related failure
+                const msg = e.message ?? "";
+                if (/unknown option|allowedTools/i.test(msg))
+                    continue;
+                throw err instanceof Error ? err : new Error(String(err));
+            }
+        }
+    }
+    throw lastErr instanceof Error ? lastErr : new Error("claude failed");
+}
+function parseClaudeOutput(stdout) {
+    try {
+        const envelope = JSON.parse(stdout);
+        if (envelope.is_error) {
+            const detail = envelope.result || envelope.error || "claude returned is_error: true";
+            if (/authenticat|401|OAuth/i.test(detail)) {
+                throw new Error(`claude authentication failed — run \`claude\` and sign in again. (${detail})`);
+            }
+            throw new Error(detail);
+        }
+        if (typeof envelope.result === "string")
+            return envelope.result;
+    }
+    catch (err) {
+        if (err instanceof Error && /claude |authenticat|is_error/i.test(err.message)) {
+            throw err;
+        }
+        // fall through — maybe raw text / not JSON
+    }
+    if (!stdout.trim()) {
+        throw new Error("claude returned empty output");
+    }
+    return stdout;
+}
+export async function isInstalled() {
+    try {
+        await execa("claude", ["--version"], { timeout: 10_000, reject: true });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/providers/fake.d.ts

@@ -0,0 +1,8 @@
+import type { ChangeSummary } from "../schema.js";
+export declare const FAKE_SUMMARY: ChangeSummary;
+export declare const FAKE_BEFORE_HTML = "<!doctype html><html><body style=\"font-family:system-ui;padding:24px;background:#f6f6f6\">\n<main style=\"max-width:420px;margin:auto;background:#fff;padding:16px;border:1px solid #ddd\">\n  <h1 style=\"font-size:18px;margin:0 0 8px\">Order #1042</h1>\n  <p style=\"margin:0;color:#444\">Total: $48.00</p>\n</main></body></html>";
+export declare const FAKE_AFTER_HTML = "<!doctype html><html><body style=\"font-family:system-ui;padding:24px;background:#f6f6f6\">\n<main style=\"max-width:420px;margin:auto;background:#fff;padding:16px;border:1px solid #ddd\">\n  <h1 style=\"font-size:18px;margin:0 0 8px\">Order #1042</h1>\n  <p style=\"margin:0 0 8px;color:#444\">Total: $48.00</p>\n  <p style=\"margin:0;color:#0a7\">Refund status: pending</p>\n</main></body></html>";
+export type CompleteOptions = {
+    model?: string;
+};
+export declare function complete(prompt: string, _options?: CompleteOptions): Promise<string>;

package/dist/providers/fake.js

@@ -0,0 +1,43 @@
+export const FAKE_SUMMARY = {
+    headline: "Add refund status to order responses",
+    overview: "Orders now include a refund_status field so clients can track refund progress without extra lookups.",
+    items: [
+        {
+            category: "feature",
+            title: "Refund status on orders",
+            description: "Adds refund_status to the order API response shape.",
+            why_it_matters: "Support and customers can see whether a refund is pending or complete.",
+            files: ["src/orders/serializer.ts", "src/orders/types.ts"],
+        },
+        {
+            category: "docs",
+            title: "Document refund_status",
+            description: "Updates OpenAPI notes for the new field.",
+            files: ["docs/api.md"],
+        },
+    ],
+    breaking_changes: [],
+    visual_notes: "Show a simple status badge on the order card.",
+};
+export const FAKE_BEFORE_HTML = `<!doctype html><html><body style="font-family:system-ui;padding:24px;background:#f6f6f6">
+<main style="max-width:420px;margin:auto;background:#fff;padding:16px;border:1px solid #ddd">
+  <h1 style="font-size:18px;margin:0 0 8px">Order #1042</h1>
+  <p style="margin:0;color:#444">Total: $48.00</p>
+</main></body></html>`;
+export const FAKE_AFTER_HTML = `<!doctype html><html><body style="font-family:system-ui;padding:24px;background:#f6f6f6">
+<main style="max-width:420px;margin:auto;background:#fff;padding:16px;border:1px solid #ddd">
+  <h1 style="font-size:18px;margin:0 0 8px">Order #1042</h1>
+  <p style="margin:0 0 8px;color:#444">Total: $48.00</p>
+  <p style="margin:0;color:#0a7">Refund status: pending</p>
+</main></body></html>`;
+export async function complete(prompt, _options = {}) {
+    if (prompt.includes("before_html") || prompt.includes("feasible")) {
+        return JSON.stringify({
+            feasible: true,
+            before_html: FAKE_BEFORE_HTML,
+            after_html: FAKE_AFTER_HTML,
+            viewport: { width: 900, height: 700 },
+        });
+    }
+    return JSON.stringify(FAKE_SUMMARY);
+}

package/dist/providers/index.d.ts

@@ -0,0 +1,22 @@
+import type { FarqConfig, ProviderName } from "../config.js";
+import type { CompleteOptions } from "./fake.js";
+export type Provider = {
+    name: ProviderName;
+    complete: (prompt: string, options?: CompleteOptions) => Promise<string>;
+};
+export type ResolveProviderOptions = {
+    flag?: ProviderName;
+    config?: FarqConfig;
+    detect?: () => Promise<{
+        claude: boolean;
+        opencode: boolean;
+    }>;
+    log?: (msg: string) => void;
+};
+export declare function detectProviders(): Promise<{
+    claude: boolean;
+    opencode: boolean;
+}>;
+export declare function resolveProvider(options?: ResolveProviderOptions): Promise<Provider>;
+export declare function getProvider(name: ProviderName): Provider;
+export { FAKE_SUMMARY, FAKE_BEFORE_HTML, FAKE_AFTER_HTML } from "./fake.js";

package/dist/providers/index.js

@@ -0,0 +1,40 @@
+import * as claude from "./claude.js";
+import * as opencode from "./opencode.js";
+import * as fake from "./fake.js";
+export async function detectProviders() {
+    const [c, o] = await Promise.all([
+        claude.isInstalled(),
+        opencode.isInstalled(),
+    ]);
+    return { claude: c, opencode: o };
+}
+export async function resolveProvider(options = {}) {
+    const flag = options.flag;
+    if (flag)
+        return getProvider(flag);
+    if (options.config?.provider)
+        return getProvider(options.config.provider);
+    const detected = options.detect
+        ? await options.detect()
+        : await detectProviders();
+    if (detected.claude && detected.opencode) {
+        options.log?.("Both claude and opencode found — using claude. Set provider in ~/.config/farq/config.json or pass --provider to override.");
+        return getProvider("claude");
+    }
+    if (detected.claude)
+        return getProvider("claude");
+    if (detected.opencode)
+        return getProvider("opencode");
+    throw new Error("No AI provider found. Install Claude Code (https://claude.ai/code) or OpenCode, or pass --provider fake for testing.");
+}
+export function getProvider(name) {
+    switch (name) {
+        case "claude":
+            return { name, complete: claude.complete };
+        case "opencode":
+            return { name, complete: opencode.complete };
+        case "fake":
+            return { name, complete: fake.complete };
+    }
+}
+export { FAKE_SUMMARY, FAKE_BEFORE_HTML, FAKE_AFTER_HTML } from "./fake.js";

package/dist/providers/opencode.d.ts

@@ -0,0 +1,3 @@
+import type { CompleteOptions } from "./fake.js";
+export declare function complete(prompt: string, options?: CompleteOptions): Promise<string>;
+export declare function isInstalled(): Promise<boolean>;

package/dist/providers/opencode.js

@@ -0,0 +1,33 @@
+import { execa } from "execa";
+const TIMEOUT_MS = 120_000;
+export async function complete(prompt, options = {}) {
+    const args = ["run"];
+    if (options.model)
+        args.push("--model", options.model);
+    args.push(prompt);
+    try {
+        const result = await execa("opencode", args, {
+            timeout: TIMEOUT_MS,
+            reject: true,
+            stdout: "pipe",
+            stderr: "pipe",
+        });
+        return result.stdout;
+    }
+    catch (err) {
+        const e = err;
+        if (e.timedOut) {
+            throw new Error("opencode did not respond — check that it's authenticated");
+        }
+        throw new Error(`opencode failed: ${(e.stderr || e.message || "unknown error").trim()}`);
+    }
+}
+export async function isInstalled() {
+    try {
+        await execa("opencode", ["--version"], { timeout: 10_000, reject: true });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/render/json.d.ts

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