@ahmedalbarghouti/farq 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ahmed Albarghouti
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,169 @@
+# farq
+
+**farq** (فرق, "difference") turns a git branch's changes into a paste-ready update: an AI-written summary plus an optional before/after visual.
+
+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 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.
+
+## Install
+
+```bash
+npm i -g @ahmedalbarghouti/farq
+farq --help
+```
+
+Or run without installing:
+
+```bash
+npx @ahmedalbarghouti/farq@0.0.1 --help
+```
+
+Add `.farq/` to your repo ignore file (generated HTML/PNG land there).
+
+## Requirements
+
+Checked at runtime when needed — nothing native is bundled.
+
+| Tool | When needed |
+|------|-------------|
+| **Node ≥ 20** | always |
+| **git** | always |
+| **`claude` or `opencode`** | summarizing / generating visuals (`--provider fake` for dry runs) |
+| **Google Chrome / Chromium** | image generation or `--before`/`--after` compose (`CHROME_PATH` override OK) |
+| **`gh`** | only for `farq pr --open` |
+
+Missing a required tool → one-line fix hint + non-zero exit. Optional visuals soft-degrade (see below).
+
+## Quick start
+
+```bash
+# On a feature branch with commits (or dirty worktree):
+farq pr --no-images          # text only
+farq pr                      # text + visual attempt
+farq slack                   # paste into Slack
+farq pr --open               # create the GitHub PR
+```
+
+Stdout is the artifact only (pipe-friendly):
+
+```bash
+farq pr --no-images | pbcopy          # macOS
+farq pr --no-images | clip            # Windows
+```
+
+## Commands
+
+### `farq pr` (default)
+
+Line 1 = title. Blank line. Then markdown body (overview, optional before/after, changes, breaking).
+
+```bash
+farq pr
+farq pr --provider fake --no-images
+farq pr --before shot-a.png --after shot-b.png
+farq pr --open
+```
+
+**`--open`** (feature branches only):
+
+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  
+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).
+
+### `farq slack`
+
+Slack mrkdwn with category emoji. Images off by default.
+
+### `farq json`
+
+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).
+- 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.
+
+## Config
+
+Precedence: **flags → project → global**.
+
+- Project: `.farqrc` or `.farqrc.json`
+- Global: `~/.config/farq/config.json`
+
+```json
+{
+  "provider": "claude",
+  "tone": "technical",
+  "models": {
+    "claudeCheap": "haiku",
+    "opencodeCheap": "provider/model"
+  }
+}
+```
+
+If both `claude` and `opencode` are installed and nothing is configured, farq uses **claude** and prints how to override (no interactive prompt).
+
+## Flags
+
+| Flag | Meaning |
+|------|---------|
+| `-r, --range` | git range (default: merge-base…HEAD, else worktree) |
+| `-p, --provider` | `claude` \| `opencode` \| `fake` |
+| `-t, --tone` | `technical` \| `client` |
+| `--before` / `--after` | manual screenshots (skips generation) |
+| `--no-images` | skip visuals |
+| `-o, --out` | image output dir (default `.farq/`) |
+| `--model-cheap` | cheap model id for visuals |
+| `-v, --verbose` | verbose logs (incl. `feasible: false` reasons) |
+| `--open` | (`pr` only) create PR with `gh` |
+
+## Exit codes
+
+| Code | Meaning |
+|------|---------|
+| `0` | success (including no feasible image / skipped `--open` on default branch) |
+| `1` | user/environment error |
+| `2` | AI failure after retry / timeout |
+
+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).
+
+## Roadmap
+
+- Harder GitHub image upload (`user-attachments` URLs)
+- Optional CDP snap of an already-running Chrome tab
+- Richer multi-template chooser
+
+## License
+
+MIT © Ahmed Albarghouti

package/dist/config.d.ts

@@ -0,0 +1,18 @@
+export type ProviderName = "claude" | "opencode" | "fake";
+export type ToneName = "technical" | "client";
+export type FarqConfig = {
+    provider?: ProviderName;
+    tone?: ToneName;
+    models?: {
+        claudeCheap?: string;
+        opencodeCheap?: string;
+    };
+};
+export type LoadConfigOptions = {
+    cwd?: string;
+    globalDir?: string;
+};
+export declare function defaultGlobalDir(): string;
+export declare function loadConfig(options?: LoadConfigOptions): FarqConfig;
+/** Merge with later sources winning. Undefined flag fields do not wipe base. */
+export declare function mergeConfig(base: FarqConfig, override: FarqConfig): FarqConfig;

package/dist/config.js

@@ -0,0 +1,74 @@
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+export function defaultGlobalDir() {
+    return join(homedir(), ".config", "farq");
+}
+export function loadConfig(options = {}) {
+    const cwd = options.cwd ?? process.cwd();
+    const globalDir = options.globalDir ?? defaultGlobalDir();
+    const globalCfg = readJsonFile(join(globalDir, "config.json"));
+    const projectCfg = readJsonFile(join(cwd, ".farqrc.json")) ??
+        readJsonFile(join(cwd, ".farqrc"));
+    return mergeConfig(globalCfg ?? {}, projectCfg ?? {});
+}
+/** Merge with later sources winning. Undefined flag fields do not wipe base. */
+export function mergeConfig(base, override) {
+    const out = {};
+    const provider = override.provider ?? base.provider;
+    const tone = override.tone ?? base.tone;
+    const models = {
+        ...base.models,
+        ...stripUndefined(override.models ?? {}),
+    };
+    if (provider !== undefined)
+        out.provider = provider;
+    if (tone !== undefined)
+        out.tone = tone;
+    if (Object.keys(models).length > 0)
+        out.models = models;
+    return out;
+}
+function stripUndefined(obj) {
+    const out = {};
+    for (const [k, v] of Object.entries(obj)) {
+        if (v !== undefined)
+            out[k] = v;
+    }
+    return out;
+}
+function readJsonFile(path) {
+    if (!existsSync(path))
+        return null;
+    try {
+        const raw = readFileSync(path, "utf8");
+        const data = JSON.parse(raw);
+        return sanitize(data);
+    }
+    catch {
+        return null;
+    }
+}
+function sanitize(data) {
+    const out = {};
+    if (data.provider === "claude" ||
+        data.provider === "opencode" ||
+        data.provider === "fake") {
+        out.provider = data.provider;
+    }
+    if (data.tone === "technical" || data.tone === "client") {
+        out.tone = data.tone;
+    }
+    if (data.models && typeof data.models === "object") {
+        const models = {};
+        if (typeof data.models.claudeCheap === "string") {
+            models.claudeCheap = data.models.claudeCheap;
+        }
+        if (typeof data.models.opencodeCheap === "string") {
+            models.opencodeCheap = data.models.opencodeCheap;
+        }
+        if (Object.keys(models).length > 0)
+            out.models = models;
+    }
+    return out;
+}

package/dist/extract-json.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Extract and parse the outermost JSON object from model output.
+ * Strips markdown fences and leading/trailing prose.
+ */
+export declare function extractJson(text: string): unknown;

package/dist/extract-json.js

@@ -0,0 +1,60 @@
+/**
+ * Extract and parse the outermost JSON object from model output.
+ * Strips markdown fences and leading/trailing prose.
+ */
+export function extractJson(text) {
+    const trimmed = text.trim();
+    const unfenced = stripFences(trimmed);
+    const candidate = findOutermostObject(unfenced);
+    if (!candidate) {
+        throw new Error("No JSON object found in model output");
+    }
+    try {
+        return JSON.parse(candidate);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        throw new Error(`Invalid JSON in model output: ${message}`);
+    }
+}
+function stripFences(text) {
+    const fenced = text.match(/```(?:json)?\s*([\s\S]*?)```/i);
+    if (fenced?.[1])
+        return fenced[1].trim();
+    return text;
+}
+function findOutermostObject(text) {
+    const start = text.indexOf("{");
+    if (start === -1)
+        return null;
+    let depth = 0;
+    let inString = false;
+    let escape = false;
+    for (let i = start; i < text.length; i++) {
+        const ch = text[i];
+        if (inString) {
+            if (escape) {
+                escape = false;
+            }
+            else if (ch === "\\") {
+                escape = true;
+            }
+            else if (ch === '"') {
+                inString = false;
+            }
+            continue;
+        }
+        if (ch === '"') {
+            inString = true;
+            continue;
+        }
+        if (ch === "{")
+            depth++;
+        if (ch === "}") {
+            depth--;
+            if (depth === 0)
+                return text.slice(start, i + 1);
+        }
+    }
+    return null;
+}

package/dist/git.d.ts

@@ -0,0 +1,36 @@
+export declare const SUMMARY_DIFF_BUDGET = 150000;
+export declare const VISUAL_DIFF_BUDGET = 60000;
+export declare class NoChangesError extends Error {
+    constructor(message?: string);
+}
+export declare class GitError extends Error {
+    constructor(message: string);
+}
+export type DiffFile = {
+    path: string;
+    status: string;
+    patch: string;
+};
+export type GatherDiffResult = {
+    mode: "range" | "worktree";
+    range: string;
+    baseRef: string | null;
+    headRef: string;
+    files: DiffFile[];
+    diffText: string;
+    truncated: boolean;
+    commits: string[];
+};
+export type GatherDiffOptions = {
+    cwd?: string;
+    range?: string;
+    budget?: number;
+};
+export declare function gatherDiff(options?: GatherDiffOptions): Promise<GatherDiffResult>;
+export declare function getFileAtRef(cwd: string, ref: string, filePath: string): Promise<string | null>;
+/** Size-capped before/after pairs for visual generation. */
+export declare function gatherVisualFileContents(cwd: string, files: DiffFile[], baseRef: string | null, budget?: number): Promise<Array<{
+    path: string;
+    before: string;
+    after: string;
+}>>;

package/dist/git.js

@@ -0,0 +1,277 @@
+import { execa } from "execa";
+export const SUMMARY_DIFF_BUDGET = 150_000;
+export const VISUAL_DIFF_BUDGET = 60_000;
+const GIT_TIMEOUT_MS = 30_000;
+export class NoChangesError extends Error {
+    constructor(message = "No changes found in range — nothing to summarize") {
+        super(message);
+        this.name = "NoChangesError";
+    }
+}
+export class GitError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "GitError";
+    }
+}
+export async function gatherDiff(options = {}) {
+    const cwd = options.cwd ?? process.cwd();
+    const budget = options.budget ?? SUMMARY_DIFF_BUDGET;
+    await assertGitRepo(cwd);
+    if (options.range) {
+        const explicit = await gatherRangeDiff(cwd, options.range, budget);
+        if (explicit.files.length === 0 && !explicit.diffText.trim()) {
+            throw new NoChangesError();
+        }
+        return explicit;
+    }
+    const base = await resolveMergeBase(cwd);
+    const range = `${base}..HEAD`;
+    const committed = await gatherRangeDiff(cwd, range, budget);
+    if (committed.files.length > 0 || committed.diffText.trim()) {
+        return committed;
+    }
+    // merge-base..HEAD empty — fall through to worktree
+    const worktree = await gatherWorktreeDiff(cwd, budget);
+    if (worktree.files.length === 0) {
+        throw new NoChangesError();
+    }
+    return worktree;
+}
+export async function getFileAtRef(cwd, ref, filePath) {
+    try {
+        const { stdout } = await git(cwd, ["show", `${ref}:${filePath}`]);
+        return stdout;
+    }
+    catch {
+        return null;
+    }
+}
+/** Size-capped before/after pairs for visual generation. */
+export async function gatherVisualFileContents(cwd, files, baseRef, budget = VISUAL_DIFF_BUDGET) {
+    const out = [];
+    let used = 0;
+    for (const file of files) {
+        if (used >= budget)
+            break;
+        const before = baseRef
+            ? ((await getFileAtRef(cwd, baseRef, file.path)) ?? "")
+            : "";
+        const after = (await getFileAtRef(cwd, "HEAD", file.path)) ??
+            (await readWorktreeFile(cwd, file.path)) ??
+            "";
+        const chunk = before.length + after.length;
+        if (used + chunk > budget && out.length > 0)
+            break;
+        out.push({
+            path: file.path,
+            before: before.slice(0, budget - used),
+            after: after.slice(0, Math.max(0, budget - used - before.length)),
+        });
+        used += Math.min(chunk, budget - used);
+    }
+    return out;
+}
+async function gatherRangeDiff(cwd, range, budget) {
+    const [baseRef, headRef] = splitRange(range);
+    const nameStatus = await git(cwd, [
+        "diff",
+        "--name-status",
+        "--find-renames",
+        range,
+    ]);
+    const patch = await git(cwd, ["diff", "--find-renames", "--unified=5", range]);
+    const commits = await listCommits(cwd, range);
+    const files = parseNameStatus(nameStatus.stdout, patch.stdout);
+    const { text, truncated } = capText(patch.stdout, budget);
+    return {
+        mode: "range",
+        range,
+        baseRef: baseRef === "HEAD" ? null : baseRef,
+        headRef,
+        files,
+        diffText: text,
+        truncated,
+        commits,
+    };
+}
+async function gatherWorktreeDiff(cwd, budget) {
+    const nameStatus = await git(cwd, [
+        "diff",
+        "HEAD",
+        "--name-status",
+        "--find-renames",
+    ]);
+    const patch = await git(cwd, ["diff", "HEAD", "--find-renames", "--unified=5"]);
+    const untracked = await listUntracked(cwd);
+    const files = parseNameStatus(nameStatus.stdout, patch.stdout);
+    let diffText = patch.stdout;
+    for (const path of untracked) {
+        if (!files.some((f) => f.path === path)) {
+            const content = (await readWorktreeFile(cwd, path)) ?? "";
+            const patchChunk = formatNewFilePatch(path, content);
+            files.push({ path, status: "A", patch: patchChunk });
+            diffText += (diffText.endsWith("\n") || !diffText ? "" : "\n") + patchChunk;
+        }
+    }
+    const capped = capText(diffText, budget);
+    return {
+        mode: "worktree",
+        range: "WORKTREE",
+        baseRef: "HEAD",
+        headRef: "WORKTREE",
+        files,
+        diffText: capped.text,
+        truncated: capped.truncated,
+        commits: [],
+    };
+}
+async function resolveMergeBase(cwd) {
+    const candidates = [
+        "origin/HEAD",
+        "origin/main",
+        "origin/master",
+        "main",
+        "master",
+    ];
+    for (const ref of candidates) {
+        try {
+            const { stdout } = await git(cwd, ["merge-base", "HEAD", ref]);
+            if (stdout.trim())
+                return stdout.trim();
+        }
+        catch {
+            // try next
+        }
+    }
+    // Fallback: first commit / empty tree against parent
+    try {
+        const { stdout } = await git(cwd, ["rev-parse", "HEAD~1"]);
+        return stdout.trim();
+    }
+    catch {
+        throw new NoChangesError("Could not resolve a merge base — provide --range explicitly");
+    }
+}
+async function assertGitRepo(cwd) {
+    try {
+        await git(cwd, ["rev-parse", "--is-inside-work-tree"]);
+    }
+    catch {
+        throw new GitError("Not a git repository — run farq inside a repo (install: https://git-scm.com/)");
+    }
+}
+async function listCommits(cwd, range) {
+    try {
+        const { stdout } = await git(cwd, [
+            "log",
+            "--format=%s",
+            range.includes("..") ? range : `${range}`,
+        ]);
+        return stdout
+            .split("\n")
+            .map((s) => s.trim())
+            .filter(Boolean);
+    }
+    catch {
+        return [];
+    }
+}
+async function listUntracked(cwd) {
+    const { stdout } = await git(cwd, [
+        "ls-files",
+        "--others",
+        "--exclude-standard",
+    ]);
+    return stdout
+        .split("\n")
+        .map((s) => s.trim())
+        .filter(Boolean);
+}
+async function readWorktreeFile(cwd, filePath) {
+    try {
+        const { readFileSync } = await import("node:fs");
+        const { join } = await import("node:path");
+        return readFileSync(join(cwd, filePath), "utf8");
+    }
+    catch {
+        return null;
+    }
+}
+function formatNewFilePatch(path, content) {
+    const lines = content.split("\n");
+    const body = lines.map((l) => `+${l}`).join("\n");
+    return `diff --git a/${path} b/${path}\nnew file mode 100644\n--- /dev/null\n+++ b/${path}\n@@ -0,0 +1,${lines.length} @@\n${body}\n`;
+}
+function parseNameStatus(nameStatus, patch) {
+    const files = [];
+    for (const line of nameStatus.split("\n")) {
+        if (!line.trim())
+            continue;
+        const parts = line.split("\t");
+        const status = parts[0] ?? "M";
+        const path = parts[parts.length - 1] ?? "";
+        if (!path)
+            continue;
+        files.push({
+            path,
+            status: status[0] ?? "M",
+            patch: extractFilePatch(patch, path),
+        });
+    }
+    return files;
+}
+function extractFilePatch(patch, path) {
+    const marker = `diff --git a/${path} b/${path}`;
+    const start = patch.indexOf(marker);
+    if (start === -1) {
+        // renamed or quoted paths — soft fallback
+        const idx = patch.indexOf(path);
+        if (idx === -1)
+            return "";
+    }
+    const from = start === -1 ? 0 : start;
+    const rest = patch.slice(from + (start === -1 ? 0 : marker.length));
+    const next = rest.indexOf("\ndiff --git ");
+    if (start === -1)
+        return "";
+    return patch.slice(start, next === -1 ? undefined : start + marker.length + next);
+}
+function splitRange(range) {
+    if (range.includes("...")) {
+        const [a, b] = range.split("...");
+        return [a || "HEAD", b || "HEAD"];
+    }
+    if (range.includes("..")) {
+        const [a, b] = range.split("..");
+        return [a || "HEAD", b || "HEAD"];
+    }
+    return [range, "HEAD"];
+}
+function capText(text, budget) {
+    if (text.length <= budget)
+        return { text, truncated: false };
+    return {
+        text: text.slice(0, budget) +
+            `\n\n… [farq truncated diff at ${budget} bytes]\n`,
+        truncated: true,
+    };
+}
+async function git(cwd, args) {
+    try {
+        return await execa("git", args, {
+            cwd,
+            timeout: GIT_TIMEOUT_MS,
+            reject: true,
+            stdout: "pipe",
+            stderr: "pipe",
+        });
+    }
+    catch (err) {
+        const e = err;
+        if (e.timedOut) {
+            throw new GitError("git did not respond — check that the repository is healthy");
+        }
+        throw err;
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};