@ahmedalbarghouti/farq 0.0.1 → 0.0.2

package/README.md

@@ -5,13 +5,13 @@
 One command. No servers. No API keys. Auth stays with your local `claude` or `opencode` CLI.
 
 ```bash
-npx @ahmedalbarghouti/farq@0.0.1 pr           # title + markdown body (+ image when feasible)
+npx @ahmedalbarghouti/farq@0.0.2 pr           # title + markdown body (+ image when feasible)
 npx farq slack              # Slack mrkdwn daily update
 npx farq json               # structured JSON
 npx farq pr --open          # fill PR template + create with gh
 ```
 
-> **0.0.1** — first public release. Expect rough edges; the CLI surface (`pr` / `slack` / `json`) is the stable bit.
+> **0.0.2** — PATH/`gh`/Chrome resolution, hosted-image PR body cleanup, orphaned asset prune. CLI surface (`pr` / `slack` / `json`) is the stable bit.
 
 ## Install
 
@@ -23,10 +23,10 @@ farq --help
 Or run without installing:
 
 ```bash
-npx @ahmedalbarghouti/farq@0.0.1 --help
+npx @ahmedalbarghouti/farq@0.0.2 --help
 ```
 
-Add `.farq/` to your repo ignore file (generated HTML/PNG land there).
+Generated images land in a **user cache directory outside the repo** by default (no `.gitignore` change needed). Use `--out .farq` if you want them in-tree.
 
 ## Requirements
 
@@ -95,7 +95,7 @@ Validated change summary plus an `images` array of produced file paths.
 - Generated compositions include a small **generated preview** badge.
 - Diagrams stay conceptual — no code dumps.
 - Missing Chrome / visual failure **soft-degrades** to text-only with a stderr warning (exit 0), unless you passed `--before`/`--after` (then hard-fail).
-- A local `.farq/before-after.png` path will not render on GitHub until the file is attached or uploaded. `--open` tries a best-effort upload.
+- A local image path will not render on GitHub until the file is attached or uploaded. `--open` tries a best-effort upload (and rewrites stdout to the hosted URL).
 
 ## Config
 
@@ -126,7 +126,7 @@ If both `claude` and `opencode` are installed and nothing is configured, farq us
 | `-t, --tone` | `technical` \| `client` |
 | `--before` / `--after` | manual screenshots (skips generation) |
 | `--no-images` | skip visuals |
-| `-o, --out` | image output dir (default `.farq/`) |
+| `-o, --out` | image output dir (default: OS user cache, outside the repo) |
 | `--model-cheap` | cheap model id for visuals |
 | `-v, --verbose` | verbose logs (incl. `feasible: false` reasons) |
 | `--open` | (`pr` only) create PR with `gh` |
@@ -146,17 +146,18 @@ Progress → **stderr**. Artifact → **stdout**.
 Tag-triggered publish via GitHub Actions (npm provenance):
 
 ```bash
-git tag v0.0.1
-git push origin v0.0.1
+git tag v0.0.2
+git push origin v0.0.2
 ```
 
-Requires repo secret `NPM_TOKEN`. Package name: `farq`.
+Requires repo secret `NPM_TOKEN`. Package name: `@ahmedalbarghouti/farq`.
 
 ## Repository ops
 
 - **CI** runs on every PR and on pushes to `main` (test + build + `--help` smoke).
 - **`main` is protected** — changes go through PRs; the `CI / test` check must pass.
-- **Releases** are tag-triggered: create `v0.0.1` (or later) after merge; the publish workflow needs a repo secret named `NPM_TOKEN` (npm automation/granular token with publish rights).
+- **Releases** are tag-triggered: create `v0.0.2` (or later) after merge; the publish workflow needs a repo secret named `NPM_TOKEN` (npm automation/granular token with publish rights).
+- **`--open` image assets:** uploaded as `farq-assets-<branch>` prereleases; farq deletes orphaned tags whose branch no longer has an open PR.
 
 ## Roadmap
 

package/dist/index.js

@@ -1,10 +1,9 @@
 #!/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 { loadConfig, mergeConfig, } from "./config.js";
+import { gatherDiff } from "./git.js";
 import { resolveProvider } from "./providers/index.js";
-import { summarize, SummarizeError } from "./summarize.js";
+import { summarize } from "./summarize.js";
 import { inferTitleConvention } from "./title.js";
 import { fetchRecentPrTitles, openPullRequest } from "./open-pr.js";
 import { runVisualPipeline } from "./visual/pipeline.js";
@@ -12,8 +11,11 @@ import { ChromeError } from "./visual/chrome.js";
 import { renderPr } from "./render/pr.js";
 import { renderSlack } from "./render/slack.js";
 import { renderJson } from "./render/json.js";
+import { createUi } from "./ui/index.js";
+import { defaultOutDir, displayImageRef } from "./paths.js";
 async function run(type, opts) {
     const cwd = process.cwd();
+    const ui = createUi();
     const fileConfig = loadConfig({ cwd });
     const flagConfig = {
         provider: opts.provider,
@@ -26,34 +28,30 @@ async function run(type, opts) {
             : undefined,
     };
     const config = mergeConfig(fileConfig, flagConfig);
-    const log = (msg) => {
-        console.error(msg);
-    };
     let provider;
     try {
         provider = await resolveProvider({
             flag: config.provider,
             config,
-            log,
+            log: (msg) => ui.note(msg),
         });
     }
     catch (err) {
-        log(err instanceof Error ? err.message : String(err));
+        ui.error(err instanceof Error ? err.message : String(err));
         return 1;
     }
     const tone = config.tone ?? "technical";
-    const imagesEnabled = type === "pr" ? !opts.noImages : false;
+    const noImages = opts.noImages === true || opts.images === false;
+    const imagesEnabled = type === "pr" ? !noImages : false;
     let diff;
+    const diffSpin = ui.stage("diff");
     try {
-        log("farq: gathering diff…");
         diff = await gatherDiff({ cwd, range: opts.range });
+        diffSpin.succeed("diff ready");
     }
     catch (err) {
-        if (err instanceof NoChangesError || err instanceof GitError) {
-            log(err.message);
-            return 1;
-        }
-        log(err instanceof Error ? err.message : String(err));
+        const msg = err instanceof Error ? err.message : String(err);
+        diffSpin.fail(msg);
         return 1;
     }
     let titleBlurb = "";
@@ -66,8 +64,8 @@ async function run(type, opts) {
             // optional
         }
     }
-    log(`farq: summarizing with ${provider.name}…`);
     let summary;
+    const sumSpin = ui.stage("summarize", provider.name);
     try {
         summary = await summarize({
             provider,
@@ -75,13 +73,11 @@ async function run(type, opts) {
             tone,
             titleConventionBlurb: titleBlurb || undefined,
         });
+        sumSpin.succeed(`summarized with ${provider.name}`);
     }
     catch (err) {
-        if (err instanceof SummarizeError) {
-            log(err.message);
-            return 2;
-        }
-        log(err instanceof Error ? err.message : String(err));
+        const msg = err instanceof Error ? err.message : String(err);
+        sumSpin.fail(msg);
         return 2;
     }
     const cheapModel = provider.name === "claude"
@@ -92,35 +88,45 @@ async function run(type, opts) {
     let imagePath = null;
     let images = [];
     if (imagesEnabled || (opts.before && opts.after)) {
-        log("farq: visual pipeline…");
+        const visSpin = ui.stage("visual", provider.name);
         try {
             const visual = await runVisualPipeline({
                 cwd,
-                outDir: opts.out ?? ".farq",
+                outDir: opts.out ?? defaultOutDir(cwd),
                 summary,
                 diff,
                 provider,
                 modelCheap: cheapModel,
-                noImages: opts.noImages && !(opts.before && opts.after),
+                noImages: noImages && !(opts.before && opts.after),
                 before: opts.before,
                 after: opts.after,
                 verbose: opts.verbose,
-                log: opts.verbose ? log : () => undefined,
+                log: opts.verbose ? (msg) => ui.note(msg) : () => undefined,
             });
             imagePath = visual.imagePath;
             images = visual.images;
-            if (visual.warning)
-                log(`farq: ${visual.warning}`);
+            if (visual.warning) {
+                visSpin.succeed("visuals skipped");
+                ui.note(visual.warning);
+            }
+            else if (imagePath) {
+                visSpin.succeed("visuals ready");
+            }
+            else {
+                visSpin.succeed("no visual (ok)");
+            }
         }
         catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
             if (err instanceof ChromeError && opts.before && opts.after) {
-                log(err.message);
+                visSpin.fail(msg);
                 return 1;
             }
-            log(`farq: ${err instanceof Error ? err.message : String(err)} (continuing without image)`);
+            visSpin.succeed("visuals skipped");
+            ui.note(`${msg} (continuing without image)`);
         }
     }
-    const relImage = imagePath != null ? relative(cwd, resolve(imagePath)).replaceAll("\\", "/") : null;
+    const relImage = imagePath != null ? displayImageRef(cwd, imagePath) : null;
     let artifact = "";
     if (type === "pr") {
         artifact = renderPr({ summary, imagePath: relImage });
@@ -129,10 +135,10 @@ async function run(type, opts) {
         artifact = renderSlack(summary);
     }
     else {
-        artifact = renderJson(summary, images.map((p) => relative(cwd, p).replaceAll("\\", "/")));
+        artifact = renderJson(summary, images.map((p) => displayImageRef(cwd, p)));
     }
     if (type === "pr" && opts.open) {
-        log("farq: opening PR…");
+        const openSpin = ui.stage("open");
         try {
             const result = await openPullRequest({
                 cwd,
@@ -143,16 +149,20 @@ async function run(type, opts) {
                 imagePath,
             });
             if (result.skipped) {
-                log(`farq: ${result.reason}`);
+                openSpin.succeed(result.reason);
             }
             else {
-                log(`farq: PR ${result.action}${result.url ? ` — ${result.url}` : ""}`);
+                openSpin.succeed(`PR ${result.action}${result.url ? ` — ${result.url}` : ""}`);
                 if (result.warning)
-                    log(`farq: ${result.warning}`);
+                    ui.note(result.warning);
+                // Match GitHub body (hosted image URL, no local-path note).
+                artifact = `${result.title}\n\n${result.body}`.replace(/\n{3,}/g, "\n\n");
+                if (!artifact.endsWith("\n"))
+                    artifact += "\n";
             }
         }
         catch (err) {
-            log(err instanceof Error ? err.message : String(err));
+            openSpin.fail(err instanceof Error ? err.message : String(err));
             return 1;
         }
     }
@@ -167,7 +177,7 @@ function addShared(cmd) {
         .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("-o, --out <dir>", "output dir for images (default: user cache, outside the repo)")
         .option("--model-cheap <id>", "model for visual generation")
         .option("-v, --verbose", "verbose logging", false);
 }
@@ -176,11 +186,11 @@ async function main() {
     program
         .name("farq")
         .description("Turn git branch changes into paste-ready PR/Slack updates with optional before/after visuals")
-        .version("0.0.1");
+        .version("0.0.2");
     addShared(program
         .command("pr", { isDefault: true })
         .description("PR title + body markdown")
-        .option("--open", "create a GitHub PR with gh (template-aware)", false)
+        .option("--open", "create or update a GitHub PR with gh (template-aware)", false)
         .action(async (opts) => {
         process.exitCode = await run("pr", opts);
     }));
@@ -199,6 +209,7 @@ async function main() {
     await program.parseAsync(process.argv);
 }
 main().catch((err) => {
-    console.error(err instanceof Error ? err.message : String(err));
+    const ui = createUi();
+    ui.error(err instanceof Error ? err.message : String(err));
     process.exitCode = 1;
 });

package/dist/open-pr.d.ts

@@ -7,7 +7,12 @@ export type OpenPrResult = {
     action: "created" | "updated";
     url?: string;
     warning?: string;
+    title: string;
+    body: string;
+    imageUrl?: string | null;
 };
+/** Prerelease tag used to host a branch's composed PNG. */
+export declare function assetTagForBranch(branch: string): 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[]>;
@@ -22,5 +27,10 @@ export declare function openPullRequest(options: {
     bodyMarkdown: string;
     imagePath?: string | null;
 }): Promise<OpenPrResult>;
+/**
+ * Delete `farq-assets-*` prereleases whose branch no longer has an open PR.
+ * Always keeps `keepTag` (the just-uploaded asset).
+ */
+export declare function pruneOrphanedFarqAssets(cwd: string, keepTag: string): Promise<string[]>;
 /** 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

@@ -3,17 +3,29 @@ import { join } from "node:path";
 import { tmpdir } from "node:os";
 import { execa } from "execa";
 import { fillPrTemplate, findPrTemplate } from "./template.js";
+import { resolveGh } from "./tools.js";
 const GH_TIMEOUT = 60_000;
+/** Prerelease tag used to host a branch's composed PNG. */
+export function assetTagForBranch(branch) {
+    return `farq-assets-${branch.replace(/[^a-zA-Z0-9._-]/g, "-").slice(0, 40)}`;
+}
+async function gh(cwd, args, options = {}) {
+    return execa(resolveGh(), args, {
+        cwd,
+        timeout: GH_TIMEOUT,
+        reject: options.reject ?? true,
+    });
+}
 export async function resolveDefaultBranch(cwd) {
     try {
-        const { stdout } = await execa("gh", [
+        const { stdout } = await gh(cwd, [
             "repo",
             "view",
             "--json",
             "defaultBranchRef",
             "--jq",
             ".defaultBranchRef.name",
-        ], { cwd, timeout: GH_TIMEOUT, reject: true });
+        ]);
         if (stdout.trim())
             return stdout.trim();
     }
@@ -45,7 +57,7 @@ export async function currentBranch(cwd) {
 }
 export async function fetchRecentPrTitles(cwd, limit = 20) {
     try {
-        const { stdout } = await execa("gh", [
+        const { stdout } = await gh(cwd, [
             "pr",
             "list",
             "--state",
@@ -56,7 +68,7 @@ export async function fetchRecentPrTitles(cwd, limit = 20) {
             "title",
             "--jq",
             ".[].title",
-        ], { cwd, timeout: GH_TIMEOUT, reject: true });
+        ]);
         return stdout
             .split("\n")
             .map((s) => s.trim())
@@ -69,7 +81,7 @@ export async function fetchRecentPrTitles(cwd, limit = 20) {
 /** 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 });
+        const { stdout, exitCode } = await gh(cwd, ["pr", "view", "--json", "number,url"], { reject: false });
         if (exitCode !== 0 || !stdout.trim())
             return null;
         const parsed = JSON.parse(stdout);
@@ -115,7 +127,7 @@ export async function openPullRequest(options) {
     try {
         const existing = await findExistingPr(cwd);
         if (existing) {
-            await execa("gh", [
+            await gh(cwd, [
                 "pr",
                 "edit",
                 String(existing.number),
@@ -123,13 +135,9 @@ export async function openPullRequest(options) {
                 title,
                 "--body-file",
                 bodyFile,
-            ], { cwd, timeout: GH_TIMEOUT, reject: true });
+            ]);
             try {
-                await execa("gh", ["pr", "view", "--web"], {
-                    cwd,
-                    timeout: GH_TIMEOUT,
-                    reject: false,
-                });
+                await gh(cwd, ["pr", "view", "--web"], { reject: false });
             }
             catch {
                 // non-fatal
@@ -139,15 +147,21 @@ export async function openPullRequest(options) {
                 action: "updated",
                 url: existing.url,
                 warning,
+                title,
+                body,
+                imageUrl,
             };
         }
-        const created = await execa("gh", ["pr", "create", "--title", title, "--body-file", bodyFile], { cwd, timeout: GH_TIMEOUT, reject: true });
+        const created = await gh(cwd, [
+            "pr",
+            "create",
+            "--title",
+            title,
+            "--body-file",
+            bodyFile,
+        ]);
         try {
-            await execa("gh", ["pr", "view", "--web"], {
-                cwd,
-                timeout: GH_TIMEOUT,
-                reject: false,
-            });
+            await gh(cwd, ["pr", "view", "--web"], { reject: false });
         }
         catch {
             // non-fatal
@@ -157,6 +171,9 @@ export async function openPullRequest(options) {
             action: "created",
             url: created.stdout?.trim() || undefined,
             warning,
+            title,
+            body,
+            imageUrl,
         };
     }
     catch (err) {
@@ -167,20 +184,59 @@ export async function openPullRequest(options) {
         rmSync(dir, { recursive: true, force: true });
     }
 }
+/**
+ * Delete `farq-assets-*` prereleases whose branch no longer has an open PR.
+ * Always keeps `keepTag` (the just-uploaded asset).
+ */
+export async function pruneOrphanedFarqAssets(cwd, keepTag) {
+    const deleted = [];
+    try {
+        const { stdout: releasesOut, exitCode: relCode } = await gh(cwd, ["release", "list", "--limit", "100", "--json", "tagName,isPrerelease"], { reject: false });
+        if (relCode !== 0 || !releasesOut.trim())
+            return deleted;
+        const releases = JSON.parse(releasesOut);
+        const candidates = releases.filter((r) => r.isPrerelease &&
+            r.tagName.startsWith("farq-assets-") &&
+            r.tagName !== keepTag);
+        if (candidates.length === 0)
+            return deleted;
+        const { stdout: prsOut, exitCode: prCode } = await gh(cwd, ["pr", "list", "--state", "open", "--limit", "100", "--json", "headRefName"], { reject: false });
+        const openTags = new Set();
+        if (prCode === 0 && prsOut.trim()) {
+            const prs = JSON.parse(prsOut);
+            for (const pr of prs) {
+                openTags.add(assetTagForBranch(pr.headRefName));
+            }
+        }
+        for (const rel of candidates) {
+            if (openTags.has(rel.tagName))
+                continue;
+            try {
+                await gh(cwd, ["release", "delete", rel.tagName, "--yes", "--cleanup-tag"], { reject: false });
+                deleted.push(rel.tagName);
+            }
+            catch {
+                // best-effort
+            }
+        }
+    }
+    catch {
+        // best-effort — never fail --open for prune
+    }
+    return deleted;
+}
 /** 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)}`;
+    const tag = assetTagForBranch(branch);
     try {
-        await execa("gh", ["release", "delete", tag, "--yes", "--cleanup-tag"], {
-            cwd,
-            timeout: GH_TIMEOUT,
+        await gh(cwd, ["release", "delete", tag, "--yes", "--cleanup-tag"], {
             reject: false,
         });
     }
     catch {
         // ok if missing
     }
-    await execa("gh", [
+    await gh(cwd, [
         "release",
         "create",
         tag,
@@ -190,10 +246,19 @@ export async function uploadPrImage(cwd, imagePath, 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 { stdout } = await gh(cwd, [
+        "release",
+        "view",
+        tag,
+        "--json",
+        "assets",
+        "--jq",
+        ".assets[0].url",
+    ]);
     const url = stdout.trim();
     if (!url)
         throw new Error("no asset URL returned");
+    await pruneOrphanedFarqAssets(cwd, tag);
     return url;
 }

package/dist/paths.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Default image output dir — outside the repo so generated files
+ * never require a `.gitignore` entry.
+ *
+ * Override with `FARQ_CACHE_DIR` (root) or `--out <dir>`.
+ */
+export declare function defaultOutDir(cwd: string, env?: NodeJS.ProcessEnv): string;
+export declare function cacheRoot(env?: NodeJS.ProcessEnv): string;
+/**
+ * Path shown in markdown: repo-relative when inside cwd, else absolute.
+ */
+export declare function displayImageRef(cwd: string, imagePath: string): string;

package/dist/paths.js

@@ -0,0 +1,38 @@
+import { createHash } from "node:crypto";
+import { homedir } from "node:os";
+import { isAbsolute, join, relative, resolve } from "node:path";
+/**
+ * Default image output dir — outside the repo so generated files
+ * never require a `.gitignore` entry.
+ *
+ * Override with `FARQ_CACHE_DIR` (root) or `--out <dir>`.
+ */
+export function defaultOutDir(cwd, env = process.env) {
+    const abs = resolve(cwd);
+    const hash = createHash("sha256").update(abs).digest("hex").slice(0, 16);
+    return join(cacheRoot(env), hash);
+}
+export function cacheRoot(env = process.env) {
+    if (env.FARQ_CACHE_DIR)
+        return resolve(env.FARQ_CACHE_DIR);
+    if (process.platform === "win32") {
+        const local = env.LOCALAPPDATA ?? join(homedir(), "AppData", "Local");
+        return join(local, "farq", "cache");
+    }
+    if (process.platform === "darwin") {
+        return join(homedir(), "Library", "Caches", "farq");
+    }
+    const xdg = env.XDG_CACHE_HOME ?? join(homedir(), ".cache");
+    return join(xdg, "farq");
+}
+/**
+ * Path shown in markdown: repo-relative when inside cwd, else absolute.
+ */
+export function displayImageRef(cwd, imagePath) {
+    const abs = resolve(imagePath);
+    const rel = relative(resolve(cwd), abs);
+    if (rel && !rel.startsWith("..") && !isAbsolute(rel)) {
+        return rel.replaceAll("\\", "/");
+    }
+    return abs;
+}

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",
@@ -23,8 +24,10 @@ export function renderPr(options) {
         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._");
+        if (!isHostedImageUrl(options.imagePath)) {
+            out.push("");
+            out.push(LOCAL_IMAGE_NOTE);
+        }
     }
     out.push("");
     out.push("### Changes");

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))
@@ -24,9 +25,10 @@ export function fillPrTemplate(options) {
         if (overflow)
             body = overflow + "\n\n" + body;
         if (options.imageUrl) {
-            const re = /\]\((?:\.\/)?\.farq\/[^)]+\)/;
+            // Swap any non-http(s) image target (cache path, .farq/, etc.).
+            const re = /!\[([^\]]*)\]\((?!https?:\/\/)[^)]+\)/;
             if (re.test(body)) {
-                body = body.replace(re, "](" + options.imageUrl + ")");
+                body = body.replace(re, "![$1](" + options.imageUrl + ")");
             }
             else {
                 body =
@@ -35,6 +37,7 @@ export function fillPrTemplate(options) {
                         ")\n\n" +
                         body;
             }
+            body = stripLocalImageNote(body);
         }
         return { title, body };
     }
@@ -58,6 +61,7 @@ export function fillPrTemplate(options) {
                     options.imageUrl +
                     ")\n";
         }
+        body = stripLocalImageNote(body);
     }
     return { title, body };
 }

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,7 @@
-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";
 const TIMEOUT_MS = 30_000;
 export class ChromeError extends Error {
     constructor(message) {
@@ -9,17 +10,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,11 +31,27 @@ 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();

package/dist/visual/compose.js

@@ -1,6 +1,7 @@
 import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { join, resolve } from "node:path";
 import { pathToFileURL } from "node:url";
+import { defaultOutDir } from "../paths.js";
 import { resolveChrome, screenshotHtml, ChromeError } from "./chrome.js";
 export function buildComposeHtml(options) {
     const { beforeBase64, afterBase64, badge } = options;
@@ -32,7 +33,7 @@ function escapeHtml(s) {
 }
 export async function composeBeforeAfter(options) {
     const cwd = options.cwd ?? process.cwd();
-    const outDir = resolve(cwd, options.outDir ?? ".farq");
+    const outDir = resolve(cwd, options.outDir ?? defaultOutDir(cwd));
     mkdirSync(outDir, { recursive: true });
     const before = readFileSync(options.beforePath);
     const after = readFileSync(options.afterPath);

package/dist/visual/pipeline.js

@@ -5,11 +5,12 @@ import { gatherVisualFileContents } from "../git.js";
 import { decideGate } from "./gate.js";
 import { generateMockup } from "./mockup.js";
 import { generateDiagram } from "./diagram.js";
+import { defaultOutDir } from "../paths.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 outDir = resolve(cwd, options.outDir ?? defaultOutDir(cwd));
     const log = options.log ?? (() => undefined);
     const vlog = (msg) => {
         if (options.verbose)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ahmedalbarghouti/farq",
-  "version": "0.0.1",
+  "version": "0.0.2",
   "description": "Turn git branch changes into paste-ready PR/Slack updates with optional before/after visuals",
   "type": "module",
   "engines": {
@@ -36,6 +36,7 @@
   "dependencies": {
     "commander": "^13.0.0",
     "execa": "^9.0.0",
+    "picocolors": "^1.1.1",
     "zod": "^3.24.0"
   },
   "devDependencies": {