harnery 0.0.1 → 0.2.0

package/dist/lib/browser/visibility.js

@@ -0,0 +1,333 @@
+// Visibility / occlusion check primitive for `harn browse --check-visible`.
+//
+// The bug this exists to catch: a sticky-bottom composer strip painting over
+// a `position: absolute; bottom: 208px` scroll-to-bottom pill, where every
+// other check (element exists, has dimensions, is "in viewport") passes
+// because the pill's bounding rect IS technically inside the visible area;
+// it's just rendered behind another element.
+//
+// Mechanism: get the target's getBoundingClientRect, sample a grid of points
+// inside it, call document.elementFromPoint(x, y) per sample, and count
+// samples where the returned element is the target (or one of its
+// descendants). visibleRatio = visibleSamples / validSamples. Report the
+// dominant occluder for diagnostics.
+/**
+ * Build the JS function passed to Playwright's `page.evaluate`. Returns
+ * a function reference (not a string) so Playwright serializes args
+ * properly. Caller invokes via `page.evaluate(fn, { selectors, sampleGrid })`.
+ */
+export function buildVisibilityCheck() {
+    return ({ selectors, sampleGrid }) => {
+        function findHiddenAncestor(start) {
+            let cur = start;
+            while (cur) {
+                const cs = window.getComputedStyle(cur);
+                const tag = cur.tagName.toLowerCase();
+                const cls = typeof cur.className === "string" ? cur.className : (cur.getAttribute("class") ?? "");
+                const id = cur.id ?? "";
+                if (cs.display === "none") {
+                    return {
+                        reason: "display-none",
+                        ancestorTag: tag,
+                        ancestorClass: cls,
+                        ancestorId: id,
+                        propertyValue: "display: none",
+                    };
+                }
+                if (cs.visibility === "hidden" || cs.visibility === "collapse") {
+                    return {
+                        reason: "visibility-hidden",
+                        ancestorTag: tag,
+                        ancestorClass: cls,
+                        ancestorId: id,
+                        propertyValue: `visibility: ${cs.visibility}`,
+                    };
+                }
+                const op = Number.parseFloat(cs.opacity || "1");
+                if (op === 0) {
+                    // Distinguish opacity:0 alone from opacity:0 + pointer-events:none.
+                    // The latter is the "hidden-but-keeps-layout" pattern that
+                    // also makes elementFromPoint skip the element and surface the
+                    // wrong "occluded" answer.
+                    const pe = cs.pointerEvents;
+                    return {
+                        reason: pe === "none" ? "pointer-events-none-with-opacity-zero" : "opacity-zero",
+                        ancestorTag: tag,
+                        ancestorClass: cls,
+                        ancestorId: id,
+                        propertyValue: `opacity: 0${pe === "none" ? "; pointer-events: none" : ""}`,
+                    };
+                }
+                // contentVisibility is read via the style declaration since it's
+                // a property name with hyphens in the standard property list.
+                const cv = cs.contentVisibility;
+                if (cv === "hidden") {
+                    return {
+                        reason: "content-visibility-hidden",
+                        ancestorTag: tag,
+                        ancestorClass: cls,
+                        ancestorId: id,
+                        propertyValue: "content-visibility: hidden",
+                    };
+                }
+                cur = cur.parentElement;
+            }
+            return null;
+        }
+        function checkOne(selector) {
+            const empty = {
+                selector,
+                found: false,
+                inViewport: false,
+                partiallyInViewport: false,
+                rect: { x: 0, y: 0, width: 0, height: 0 },
+                cssVisible: false,
+                hiddenBy: null,
+                visibleRatio: 0,
+                samples: [],
+                occludedBy: null,
+                elementOuterHTML: "",
+            };
+            const el = document.querySelector(selector);
+            if (!(el instanceof Element))
+                return empty;
+            const rect = el.getBoundingClientRect();
+            const vw = window.innerWidth;
+            const vh = window.innerHeight;
+            const inViewport = rect.top >= 0 && rect.bottom <= vh && rect.left >= 0 && rect.right <= vw;
+            const partiallyInViewport = !(rect.bottom <= 0 ||
+                rect.top >= vh ||
+                rect.right <= 0 ||
+                rect.left >= vw);
+            // CSS-level visibility check FIRST. Element.checkVisibility() is the
+            // standard primitive (Chromium 105+, Safari 17.4+, Firefox 125+); we
+            // also walk the ancestor chain to identify which property is hiding
+            // it. If the element is CSS-hidden, occlusion sampling is irrelevant,
+            // so short-circuit with visibleRatio=0 and skip the elementFromPoint
+            // calls (which would otherwise surface misleading "occluded by ..."
+            // answers when pointer-events:none is in play).
+            const checkVis = el
+                .checkVisibility;
+            const cssVisible = typeof checkVis === "function"
+                ? checkVis.call(el, {
+                    contentVisibilityAuto: true,
+                    opacityProperty: true,
+                    visibilityProperty: true,
+                })
+                : (() => {
+                    // Fallback for browsers without Element.checkVisibility:
+                    // detect via the same ancestor walk we use to identify
+                    // hiddenBy. cssVisible = (no ancestor in the chain hides it).
+                    return findHiddenAncestor(el) === null;
+                })();
+            const hiddenBy = cssVisible ? null : findHiddenAncestor(el);
+            if (!cssVisible) {
+                return {
+                    selector,
+                    found: true,
+                    inViewport,
+                    partiallyInViewport,
+                    rect: {
+                        x: Math.round(rect.x),
+                        y: Math.round(rect.y),
+                        width: Math.round(rect.width),
+                        height: Math.round(rect.height),
+                    },
+                    cssVisible: false,
+                    hiddenBy,
+                    visibleRatio: 0,
+                    samples: [],
+                    occludedBy: null,
+                    elementOuterHTML: el.outerHTML.slice(0, 500),
+                };
+            }
+            const samples = [];
+            let visibleCount = 0;
+            let validCount = 0;
+            const occluderCounts = {};
+            for (let i = 1; i <= sampleGrid; i++) {
+                for (let j = 1; j <= sampleGrid; j++) {
+                    const x = rect.left + (rect.width * i) / (sampleGrid + 1);
+                    const y = rect.top + (rect.height * j) / (sampleGrid + 1);
+                    if (x < 0 || x >= vw || y < 0 || y >= vh) {
+                        samples.push({ x: Math.round(x), y: Math.round(y), status: "outside-viewport" });
+                        continue;
+                    }
+                    validCount++;
+                    const topEl = document.elementFromPoint(x, y);
+                    if (!topEl) {
+                        samples.push({ x: Math.round(x), y: Math.round(y), status: "no-element" });
+                        continue;
+                    }
+                    // Visible if topmost element is the target itself OR one of its
+                    // descendants (e.g. the pill button contains an SVG icon, so sampling
+                    // the icon area still counts as the pill being visible).
+                    const visible = topEl === el || el.contains(topEl);
+                    if (visible) {
+                        samples.push({ x: Math.round(x), y: Math.round(y), status: "visible" });
+                        visibleCount++;
+                    }
+                    else {
+                        const tag = topEl.tagName.toLowerCase();
+                        const cls = typeof topEl.className === "string"
+                            ? topEl.className
+                            : (topEl.getAttribute("class") ?? "");
+                        const key = `${tag}|${cls}`;
+                        const existing = occluderCounts[key];
+                        if (existing) {
+                            existing.count++;
+                        }
+                        else {
+                            occluderCounts[key] = {
+                                count: 1,
+                                firstX: x,
+                                firstY: y,
+                            };
+                        }
+                        samples.push({
+                            x: Math.round(x),
+                            y: Math.round(y),
+                            status: "occluded",
+                            occluderTag: tag,
+                            occluderClass: cls,
+                        });
+                    }
+                }
+            }
+            let occludedBy = null;
+            const ranked = Object.entries(occluderCounts).sort((a, b) => b[1].count - a[1].count);
+            if (ranked.length > 0) {
+                const top = ranked[0];
+                const [, info] = top;
+                const occluderEl = document.elementFromPoint(info.firstX, info.firstY);
+                if (occluderEl instanceof Element) {
+                    const cs = window.getComputedStyle(occluderEl);
+                    const orect = occluderEl.getBoundingClientRect();
+                    occludedBy = {
+                        tagName: occluderEl.tagName.toLowerCase(),
+                        className: typeof occluderEl.className === "string"
+                            ? occluderEl.className
+                            : (occluderEl.getAttribute("class") ?? ""),
+                        id: occluderEl.id ?? "",
+                        outerHTML: occluderEl.outerHTML.slice(0, 500),
+                        computedStyles: {
+                            position: cs.position,
+                            zIndex: cs.zIndex,
+                            backgroundColor: cs.backgroundColor,
+                        },
+                        rect: {
+                            x: Math.round(orect.x),
+                            y: Math.round(orect.y),
+                            width: Math.round(orect.width),
+                            height: Math.round(orect.height),
+                        },
+                    };
+                }
+            }
+            return {
+                selector,
+                found: true,
+                inViewport,
+                partiallyInViewport,
+                rect: {
+                    x: Math.round(rect.x),
+                    y: Math.round(rect.y),
+                    width: Math.round(rect.width),
+                    height: Math.round(rect.height),
+                },
+                cssVisible: true,
+                hiddenBy: null,
+                visibleRatio: validCount > 0 ? visibleCount / validCount : 0,
+                samples,
+                occludedBy,
+                elementOuterHTML: el.outerHTML.slice(0, 500),
+            };
+        }
+        return selectors.map(checkOne);
+    };
+}
+/**
+ * Build a script that injects overlay rectangles for each visibility result.
+ * Green border = target, red border = dominant occluder. Caller injects via
+ * `page.evaluate`, takes the screenshot, then clears via
+ * `buildClearAnnotationsScript`. Boxes are absolutely positioned at the
+ * target/occluder's `getBoundingClientRect()` location, so they survive
+ * scroll changes between sample-time and screenshot-time only if nothing
+ * has scrolled. The recommended flow is sample → annotate → screenshot →
+ * clear without intervening scrolls.
+ */
+export function buildAnnotateScript() {
+    return ({ results }) => {
+        const ROOT_ID = "__bp-check-visible-annotations__";
+        document.getElementById(ROOT_ID)?.remove();
+        const root = document.createElement("div");
+        root.id = ROOT_ID;
+        root.style.cssText = "position: fixed; inset: 0; pointer-events: none; z-index: 2147483647;";
+        document.body.appendChild(root);
+        const drawBox = (rect, color, label) => {
+            const box = document.createElement("div");
+            box.style.cssText = `
+        position: absolute;
+        left: ${rect.x}px;
+        top: ${rect.y}px;
+        width: ${rect.width}px;
+        height: ${rect.height}px;
+        border: 2px solid ${color};
+        box-sizing: border-box;
+        background: ${color}1a;
+        pointer-events: none;
+      `;
+            const tag = document.createElement("div");
+            tag.textContent = label;
+            tag.style.cssText = `
+        position: absolute;
+        left: 0;
+        top: -18px;
+        background: ${color};
+        color: #fff;
+        font: 12px/1.4 -apple-system, system-ui, sans-serif;
+        padding: 1px 6px;
+        border-radius: 3px 3px 3px 0;
+        white-space: nowrap;
+        pointer-events: none;
+      `;
+            box.appendChild(tag);
+            root.appendChild(box);
+        };
+        for (const r of results) {
+            if (!r.found)
+                continue;
+            // Color the target by failure mode:
+            //   green:   cssVisible + visibleRatio>=0.9 (actually visible)
+            //   red:     cssVisible + visibleRatio<0.9 (occluded by sibling)
+            //   magenta: !cssVisible (CSS-hidden via opacity/display/visibility/...)
+            let color;
+            let label;
+            if (!r.cssVisible) {
+                color = "#a855f7"; // tailwind purple-500
+                const hb = r.hiddenBy;
+                label = hb
+                    ? `${r.selector}  HIDDEN [${hb.reason}] via ${hb.ancestorTag}${hb.ancestorId ? `#${hb.ancestorId}` : ""}`
+                    : `${r.selector}  HIDDEN`;
+            }
+            else if (r.visibleRatio >= 0.9) {
+                color = "#10b981"; // tailwind emerald-500
+                label = `${r.selector}  ratio=${(r.visibleRatio * 100).toFixed(0)}%`;
+            }
+            else {
+                color = "#ef4444"; // tailwind red-500
+                label = `${r.selector}  ratio=${(r.visibleRatio * 100).toFixed(0)}%`;
+            }
+            drawBox(r.rect, color, label);
+            if (r.cssVisible && r.occludedBy && r.visibleRatio < 0.9) {
+                drawBox(r.occludedBy.rect, "#f59e0b", // amber-500
+                `occluder: ${r.occludedBy.tagName}${r.occludedBy.id ? `#${r.occludedBy.id}` : ""}`);
+            }
+        }
+    };
+}
+export function buildClearAnnotationsScript() {
+    return () => {
+        document.getElementById("__bp-check-visible-annotations__")?.remove();
+    };
+}

package/dist/lib/browser/visual-diff.d.ts

@@ -0,0 +1,38 @@
+declare const BASELINE_DIR: string;
+export interface SaveBaselineResult {
+    name: string;
+    path: string;
+    bytes: number;
+}
+export interface DiffResult {
+    name: string;
+    baselinePath: string;
+    currentPath: string;
+    diffPath: string;
+    matched: boolean;
+    /** Pixels that differ between baseline and current beyond the threshold. */
+    mismatchedPixels: number;
+    totalPixels: number;
+    /** mismatchedPixels / totalPixels. Lower = more similar. 0 = identical. */
+    mismatchRatio: number;
+    similarity: number;
+    baselineDims: {
+        width: number;
+        height: number;
+    };
+    currentDims: {
+        width: number;
+        height: number;
+    };
+    /** True when baseline + current have different dimensions (auto-fail). */
+    sizeMismatch: boolean;
+}
+export declare function saveBaseline(currentPngPath: string, name: string): SaveBaselineResult;
+export declare function diffAgainstBaseline(currentPngPath: string, name: string, opts?: {
+    threshold?: number;
+    diffOutputPath?: string;
+}): DiffResult;
+export declare function baselineExists(name: string): boolean;
+export declare function listBaselines(): string[];
+export { BASELINE_DIR };
+//# sourceMappingURL=visual-diff.d.ts.map

package/dist/lib/browser/visual-diff.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"visual-diff.d.ts","sourceRoot":"","sources":["../../../src/lib/browser/visual-diff.ts"],"names":[],"mappings":"AAiBA,QAAA,MAAM,YAAY,QAA8D,CAAC;AAEjF,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,OAAO,CAAC;IACjB,4EAA4E;IAC5E,gBAAgB,EAAE,MAAM,CAAC;IACzB,WAAW,EAAE,MAAM,CAAC;IACpB,2EAA2E;IAC3E,aAAa,EAAE,MAAM,CAAC;IACtB,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IAChD,WAAW,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IAC/C,0EAA0E;IAC1E,YAAY,EAAE,OAAO,CAAC;CACvB;AAWD,wBAAgB,YAAY,CAAC,cAAc,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,kBAAkB,CAMrF;AAED,wBAAgB,mBAAmB,CACjC,cAAc,EAAE,MAAM,EACtB,IAAI,EAAE,MAAM,EACZ,IAAI,GAAE;IAAE,SAAS,CAAC,EAAE,MAAM,CAAC;IAAC,cAAc,CAAC,EAAE,MAAM,CAAA;CAAO,GACzD,UAAU,CA+DZ;AAED,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAMpD;AAED,wBAAgB,aAAa,IAAI,MAAM,EAAE,CAUxC;AAED,OAAO,EAAE,YAAY,EAAE,CAAC"}

package/dist/lib/browser/visual-diff.js

@@ -0,0 +1,107 @@
+// Visual-regression primitive for `harn browse --baseline / --diff`. Captures
+// the screenshot under a name + later pixel-diffs against it. Catches the
+// class of regressions where every per-element check (visibility, console
+// errors, network) passes but the rendered UI shifted/lost styling/regressed
+// a hover state: the kind of thing a single human screenshot would have
+// flagged immediately.
+//
+// pixelmatch (with pngjs decoding) is the pixel-diff workhorse: small, no
+// native deps, ships an alpha-blended diff PNG and a mismatched-pixel count
+// in one pass.
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, resolve } from "node:path";
+import pixelmatch from "pixelmatch";
+import { PNG } from "pngjs";
+const BASELINE_DIR = resolve(homedir(), ".cache", "harnery", "visual-baselines");
+function baselinePath(name) {
+    if (!/^[a-zA-Z0-9_.-]+$/.test(name)) {
+        throw new Error(`Invalid baseline name '${name}'. Use alphanumeric + _ . - only (file-system-safe).`);
+    }
+    return resolve(BASELINE_DIR, `${name}.png`);
+}
+export function saveBaseline(currentPngPath, name) {
+    const dest = baselinePath(name);
+    mkdirSync(dirname(dest), { recursive: true });
+    const bytes = readFileSync(currentPngPath);
+    writeFileSync(dest, bytes);
+    return { name, path: dest, bytes: bytes.length };
+}
+export function diffAgainstBaseline(currentPngPath, name, opts = {}) {
+    const basePath = baselinePath(name);
+    if (!existsSync(basePath)) {
+        throw new Error(`No baseline named '${name}' at ${basePath}. Save one first with --baseline ${name}.`);
+    }
+    const baselineBuf = readFileSync(basePath);
+    const currentBuf = readFileSync(currentPngPath);
+    const baseline = PNG.sync.read(baselineBuf);
+    const current = PNG.sync.read(currentBuf);
+    const sizeMismatch = baseline.width !== current.width || baseline.height !== current.height;
+    const diffPath = opts.diffOutputPath ?? `${currentPngPath.replace(/\.png$/i, "")}-diff.png`;
+    mkdirSync(dirname(diffPath), { recursive: true });
+    if (sizeMismatch) {
+        // Different dimensions: pixelmatch can't compare directly. Write a
+        // placeholder diff that's just the current image with a banner; report
+        // the size delta in the result so the caller knows what's up.
+        writeFileSync(diffPath, currentBuf);
+        return {
+            name,
+            baselinePath: basePath,
+            currentPath: currentPngPath,
+            diffPath,
+            matched: false,
+            mismatchedPixels: current.width * current.height,
+            totalPixels: current.width * current.height,
+            mismatchRatio: 1,
+            similarity: 0,
+            baselineDims: { width: baseline.width, height: baseline.height },
+            currentDims: { width: current.width, height: current.height },
+            sizeMismatch: true,
+        };
+    }
+    const { width, height } = baseline;
+    const diff = new PNG({ width, height });
+    const mismatchedPixels = pixelmatch(baseline.data, current.data, diff.data, width, height, {
+        threshold: opts.threshold ?? 0.1, // pixelmatch's per-pixel tolerance (YIQ color delta)
+        includeAA: false,
+    });
+    writeFileSync(diffPath, PNG.sync.write(diff));
+    const totalPixels = width * height;
+    const mismatchRatio = mismatchedPixels / totalPixels;
+    return {
+        name,
+        baselinePath: basePath,
+        currentPath: currentPngPath,
+        diffPath,
+        matched: mismatchedPixels === 0,
+        mismatchedPixels,
+        totalPixels,
+        mismatchRatio,
+        similarity: 1 - mismatchRatio,
+        baselineDims: { width, height },
+        currentDims: { width: current.width, height: current.height },
+        sizeMismatch: false,
+    };
+}
+export function baselineExists(name) {
+    try {
+        return existsSync(baselinePath(name));
+    }
+    catch {
+        return false;
+    }
+}
+export function listBaselines() {
+    if (!existsSync(BASELINE_DIR))
+        return [];
+    try {
+        return readdirSync(BASELINE_DIR)
+            .filter((f) => f.endsWith(".png"))
+            .map((f) => f.replace(/\.png$/, ""))
+            .sort();
+    }
+    catch {
+        return [];
+    }
+}
+export { BASELINE_DIR };

package/dist/lib/completion/bash.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Bash completion generator. Walks a CommandSpec tree and emits a single
+ * self-contained bash function `_<bin>` plus the `complete -F _<bin> <bin>`
+ * directive that registers it. The bin name is injected by the caller so the
+ * same generator serves any host CLI.
+ *
+ * Generated script architecture:
+ *   1. `_<bin>_path()`: walks COMP_WORDS forward, skipping options and option
+ *      values, returns the current command-path string (e.g., "anthropic cost").
+ *   2. `_<bin>_options()` / `_<bin>_subcommands()` / `_<bin>_option_takes_value()` /
+ *      `_<bin>_option_choices()`: table-lookup functions, generated as big
+ *      case statements from the spec tree.
+ *   3. `_<bin>()`: main entry. Sets COMPREPLY based on whether the cursor is
+ *      on a subcommand name, option name (--<TAB>), or value.
+ *   4. Dynamic value paths shell out to `<bin> __complete <provider> -- "$cur"`.
+ *
+ * Important escaping rules:
+ *   - Single-quoted strings in bash don't honor escapes. We replace `'` in
+ *     descriptions/choices with `'\''` (the standard bash single-quote escape).
+ *   - We avoid descriptions in bash output because bash COMPREPLY can't render
+ *     them; descriptions are a zsh/fish feature.
+ */
+import type { CommandSpec } from "./walk.js";
+export declare function generateBash(root: CommandSpec, binName: string): string;
+//# sourceMappingURL=bash.d.ts.map

package/dist/lib/completion/bash.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bash.d.ts","sourceRoot":"","sources":["../../../src/lib/completion/bash.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,KAAK,EAAE,WAAW,EAA8B,MAAM,WAAW,CAAC;AAuBzE,wBAAgB,YAAY,CAAC,IAAI,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CA2FvE"}