@ahmedalbarghouti/farq 0.0.1 → 0.0.3

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.3 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.3** — 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.3 --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
 
@@ -76,7 +76,7 @@ farq pr --open
 
 1. Reads `.github` PR template if present and fills known sections  
 2. Infers title style from recent merged PR titles when `gh` works  
-3. Best-effort uploads the composed image as a prerelease asset and embeds the URL  
+3. Best-effort uploads composed image(s) as prerelease assets and embeds the URL(s)  
 4. Creates the PR with `gh pr create`, or **updates** title/body with `gh pr edit` if one already exists for the branch, then opens it in the browser  
 
 On the default branch (`main` / `master` / repo default), `--open` skips create and still prints the artifact. Titles are capped at GitHub's **256** character limit (overflow goes into the body).
@@ -91,11 +91,11 @@ Validated change summary plus an `images` array of produced file paths.
 
 ## Images (honesty policy)
 
-- Visuals come from the diff only. UI markup gets a mockup attempt; everything else gets a small concept flowchart/diagram. If the model cannot produce a faithful preview, **no image** is produced (still exit 0).
+- Visuals come from the diff only. A cheap model groups summary items into **up to 5** visual topics by intent (same feature → one image; truly unrelated domains → separate). File-overlap is the fallback if that grouping fails. UI markup gets a mockup attempt; everything else gets a small concept flowchart/diagram. Screenshots are capped at **1280×720** so content must fit the frame (no tall cut-off pages). If a topic is infeasible, it is skipped (still exit 0).
 - 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` |
@@ -141,22 +141,12 @@ If both `claude` and `opencode` are installed and nothing is configured, farq us
 
 Progress → **stderr**. Artifact → **stdout**.
 
-## Publishing notes (maintainers)
-
-Tag-triggered publish via GitHub Actions (npm provenance):
-
-```bash
-git tag v0.0.1
-git push origin v0.0.1
-```
-
-Requires repo secret `NPM_TOKEN`. Package name: `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.3` (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"
@@ -91,48 +87,60 @@ async function run(type, opts) {
             : undefined;
     let imagePath = null;
     let images = [];
+    let imageMeta = [];
     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}`);
+            imageMeta = visual.imageMeta;
+            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 prImages = (imageMeta.length > 0 ? imageMeta : images.map((p) => ({ path: p, title: "before / after" }))).map((img) => ({ path: displayImageRef(cwd, img.path), title: img.title }));
     let artifact = "";
     if (type === "pr") {
-        artifact = renderPr({ summary, imagePath: relImage });
+        artifact = renderPr({ summary, images: prImages });
     }
     else if (type === "slack") {
         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,
@@ -141,18 +149,24 @@ async function run(type, opts) {
                     ? artifact.split("\n\n").slice(1).join("\n\n")
                     : artifact,
                 imagePath,
+                imagePaths: images,
+                imageTitles: imageMeta.map((m) => m.title),
             });
             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 +181,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 +190,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.3");
     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 +213,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,13 @@ export type OpenPrResult = {
     action: "created" | "updated";
     url?: string;
     warning?: string;
+    title: string;
+    body: string;
+    imageUrl?: string | null;
+    imageUrls?: string[];
 };
+/** 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[]>;
@@ -21,6 +27,15 @@ export declare function openPullRequest(options: {
     summary: ChangeSummary;
     bodyMarkdown: string;
     imagePath?: string | null;
+    imagePaths?: string[];
+    imageTitles?: string[];
 }): Promise<OpenPrResult>;
-/** Best-effort: prerelease asset URL for the PNG. */
+/**
+ * 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 one PNG. */
 export declare function uploadPrImage(cwd: string, imagePath: string, branch: string): Promise<string>;
+/** Best-effort: upload many PNGs to one prerelease; URLs in input order. */
+export declare function uploadPrImages(cwd: string, imagePaths: string[], branch: string): Promise<string[]>;

package/dist/open-pr.js

@@ -1,19 +1,31 @@
 import { mkdtempSync, writeFileSync, rmSync } from "node:fs";
-import { join } from "node:path";
+import { basename, 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);
@@ -92,14 +104,19 @@ export async function openPullRequest(options) {
             reason: `Already on ${defaultBranch} — skipping PR create`,
         };
     }
-    let imageUrl = null;
+    const paths = options.imagePaths && options.imagePaths.length > 0
+        ? options.imagePaths
+        : options.imagePath
+            ? [options.imagePath]
+            : [];
+    let imageUrls = [];
     let warning;
-    if (options.imagePath) {
+    if (paths.length > 0) {
         try {
-            imageUrl = await uploadPrImage(cwd, options.imagePath, branch);
+            imageUrls = await uploadPrImages(cwd, paths, branch);
         }
         catch (err) {
-            warning = `Image upload failed — attach manually: ${options.imagePath} (${err instanceof Error ? err.message : String(err)})`;
+            warning = `Image upload failed — attach manually: ${paths.join(", ")} (${err instanceof Error ? err.message : String(err)})`;
         }
     }
     const template = findPrTemplate(cwd);
@@ -107,7 +124,11 @@ export async function openPullRequest(options) {
         template,
         summary: options.summary,
         bodyMarkdown: options.bodyMarkdown,
-        imageUrl,
+        imageUrl: imageUrls[0] ?? null,
+        images: imageUrls.map((url, i) => ({
+            url,
+            title: options.imageTitles?.[i],
+        })),
     });
     const dir = mkdtempSync(join(tmpdir(), "farq-pr-"));
     const bodyFile = join(dir, "body.md");
@@ -115,7 +136,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 +144,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 +156,22 @@ export async function openPullRequest(options) {
                 action: "updated",
                 url: existing.url,
                 warning,
+                title,
+                body,
+                imageUrl: imageUrls[0] ?? null,
+                imageUrls,
             };
         }
-        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 +181,10 @@ export async function openPullRequest(options) {
             action: "created",
             url: created.stdout?.trim() || undefined,
             warning,
+            title,
+            body,
+            imageUrl: imageUrls[0] ?? null,
+            imageUrls,
         };
     }
     catch (err) {
@@ -167,33 +195,96 @@ export async function openPullRequest(options) {
         rmSync(dir, { recursive: true, force: true });
     }
 }
-/** Best-effort: prerelease asset URL for the PNG. */
+/**
+ * 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 one PNG. */
 export async function uploadPrImage(cwd, imagePath, branch) {
-    const tag = `farq-assets-${branch.replace(/[^a-zA-Z0-9._-]/g, "-").slice(0, 40)}`;
+    const urls = await uploadPrImages(cwd, [imagePath], branch);
+    const url = urls[0];
+    if (!url)
+        throw new Error("no asset URL returned");
+    return url;
+}
+/** Best-effort: upload many PNGs to one prerelease; URLs in input order. */
+export async function uploadPrImages(cwd, imagePaths, branch) {
+    if (imagePaths.length === 0)
+        return [];
+    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,
-        imagePath,
+        ...imagePaths,
         "--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;
+    ]);
+    const { stdout } = await gh(cwd, [
+        "release",
+        "view",
+        tag,
+        "--json",
+        "assets",
+    ]);
+    const parsed = JSON.parse(stdout);
+    const assets = parsed.assets ?? [];
+    const urls = imagePaths.map((p) => {
+        const name = basename(p);
+        const hit = assets.find((a) => a.name === name);
+        if (!hit?.url) {
+            throw new Error(`no asset URL for ${name}`);
+        }
+        return hit.url;
+    });
+    await pruneOrphanedFarqAssets(cwd, tag);
+    return urls;
 }

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;
+}