{"kind":"Skill","metadata":{"namespace":"community","name":"eyeball","version":"0.1.0"},"spec":{"description":"Document analysis with inline source screenshots. When you ask Copilot to analyze a document, Eyeball generates a Word doc where every factual claim includes a highlighted screenshot from the source material so you can verify it with your own eyes.","files":{"SKILL.md":"---\nname: eyeball\ndescription: 'Document analysis with inline source screenshots. When you ask Copilot to analyze a document, Eyeball generates a Word doc where every factual claim includes a highlighted screenshot from the source material so you can verify it with your own eyes.'\n---\n\n# Eyeball\n\nAnalyze documents with visual proof. When activated, Eyeball produces a Word document on the user's Desktop where every factual assertion includes an inline screenshot from the source material with the cited text highlighted in yellow.\n\n## Activation\n\nWhen the user invokes this skill (e.g., \"use eyeball\", \"run eyeball on this\", \"eyeball this document\"), respond with:\n\n\u003e **Eyeball is active.** I'll analyze the document and produce a Word doc with inline source screenshots so you can verify every claim with your own eyes.\n\nThen follow the workflow below.\n\n## Supported Sources\n\n- **Local files:** Word documents (.docx, .doc), PDFs (.pdf), RTF files\n- **Web URLs:** Any publicly accessible web page\n\n## Tool Location\n\nThe Eyeball Python utility is located at:\n```\n\u003cplugin_dir\u003e/skills/eyeball/tools/eyeball.py\n```\n\nTo find the actual path, run:\n```bash\nfind ~/.copilot/installed-plugins -name \"eyeball.py\" -path \"*/eyeball/*\" 2\u003e/dev/null\n```\n\nIf not found there, check the project directory or the user's home directory for the eyeball repo.\n\n## First-Run Setup\n\nBefore first use, check that dependencies are installed:\n\n```bash\npython3 \u003cpath-to\u003e/eyeball.py setup-check\n```\n\nIf anything is missing, install the required dependencies:\n```bash\npip3 install pymupdf pillow python-docx playwright\npython3 -m playwright install chromium\n```\n\nOn Windows, also install pywin32 for Word automation:\n```bash\npip install pywin32\n```\n\n## Workflow\n\nFollow these steps exactly. The order matters.\n\n### Step 1: Read the source text\n\nBefore writing any analysis, extract and read the full text of the source document:\n\n```bash\npython3 \u003cpath-to\u003e/eyeball.py extract-text --source \"\u003cpath-or-url\u003e\"\n```\n\nRead the output carefully. Identify actual section numbers, headings, page numbers, and key language.\n\n**CRITICAL:** Do not skip this step. Do not write analysis based on assumptions about how the document is structured. Read the actual text.\n\n### Step 2: Write analysis with exact citations\n\nFor each point in your analysis, you must:\n\n1. **Reference the correct section number as it appears in the document** (e.g., \"Section 9\" not \"Section 8\" because you assumed the numbering).\n2. **Reference the correct page number** where the section appears in the extracted text.\n3. **Select anchors that are verbatim phrases from the source** that directly support your claim.\n\n### Step 3: Select anchors correctly\n\nThis is the most important step. Anchors determine what gets highlighted in the screenshots.\n\n**DO:**\n- Use verbatim phrases from the source text that directly support your assertion\n- Use multiple anchors to span the full range of text the reader should see\n- Use specific, uncommon phrases that appear only where you intend\n\n**DO NOT:**\n- Use generic topic labels (e.g., \"Confidentiality\") that appear throughout the document\n- Use section titles alone when they appear as cross-references elsewhere\n- Use single common words that match in many places\n\n**Examples:**\n\nWRONG -- uses a generic topic label that matches everywhere:\n```json\n{\"anchors\": [\"User-Generated Content\"], \"target_page\": 8}\n```\n\nRIGHT -- uses the specific language that supports the claim:\n```json\n{\"anchors\": [\"retain ownership\", \"Ownership of Content, Right to Post\"], \"target_page\": 8}\n```\n\nWRONG -- section title appears as a cross-reference on earlier pages:\n```json\n{\"anchors\": [\"LIMITATION OF LIABILITY\"]}\n```\n\nRIGHT -- includes the section number for precision, targets the correct page:\n```json\n{\"anchors\": [\"12. LIMITATION OF LIABILITY\", \"INDIRECT\", \"CONSEQUENTIAL\"], \"target_page\": 13}\n```\n\n### Step 4: Build the analysis document\n\nConstruct a JSON array of sections and call the build command:\n\n```bash\npython3 \u003cpath-to\u003e/eyeball.py build \\\n  --source \"\u003cpath-or-url\u003e\" \\\n  --output ~/Desktop/\u003ctitle\u003e.docx \\\n  --title \"Analysis Title\" \\\n  --subtitle \"Source description\" \\\n  --sections '[\n    {\n      \"heading\": \"1. Section Title\",\n      \"analysis\": \"Your analysis text here. Reference Section X on page Y...\",\n      \"anchors\": [\"verbatim phrase 1\", \"verbatim phrase 2\"],\n      \"target_page\": 5,\n      \"context_padding\": 40\n    },\n    {\n      \"heading\": \"2. Another Section\",\n      \"analysis\": \"More analysis...\",\n      \"anchors\": [\"exact quote from source\"],\n      \"target_pages\": [10, 11],\n      \"context_padding\": 50\n    }\n  ]'\n```\n\nSection object fields:\n- `heading` (required): Section heading in the output document\n- `analysis` (required): Your analysis text\n- `anchors` (required): List of verbatim phrases from the source to search for and highlight\n- `target_page` (optional): Single page number (1-indexed) to search on\n- `target_pages` (optional): List of page numbers to search across (screenshots stitched vertically)\n- `context_padding` (optional): Padding in PDF points above/below the anchor region (default: 40). Increase for more context.\n\n### Step 5: Deliver the output\n\nSave the output to the user's Desktop. Tell the user the filename and that they can open it to verify each claim against the highlighted source screenshots.\n\n## Self-Check Before Delivery\n\nBefore saving the final document, mentally verify:\n\n1. Does each section's analysis text reference the correct section number from the source?\n2. Are the anchors verbatim phrases that appear on the target page?\n3. Does each anchor directly support the claim in the analysis, not just relate to the same topic?\n4. If the screenshot doesn't match the analysis, is the analysis wrong or is the anchor wrong? Fix whichever is incorrect.\n\n## Notes\n\n- The output document includes highlighted screenshots that are dynamically sized. If you provide multiple anchors, the screenshot expands to cover all of them.\n- When a search term is not found, the output document will note this. If this happens, the anchor was likely not verbatim enough. Adjust and rebuild.\n- For web pages, Playwright renders the page to PDF first. The resulting page numbers may differ from what you see in a browser. Use the extracted text output (step 1) to determine correct page numbers.\n- If the user has already provided the source text or you have already read it in the current conversation, you can skip step 1. But always verify section numbers and page references against the actual text before writing analysis.\n","tools/eyeball.py":"#!/usr/bin/env python3\n\"\"\"\nEyeball - Document analysis with inline source screenshots.\n\nConverts source documents (Word, PDF, web URL) to PDF, renders pages as images,\nsearches for cited text, highlights matching regions, and assembles an output\nWord document with analysis text interleaved with source screenshots.\n\nUsage (called by the Copilot CLI skill, not typically invoked directly):\n\n    python3 eyeball.py build \\\n        --source \u003cpath-or-url\u003e \\\n        --output \u003coutput.docx\u003e \\\n        --sections '[{\"heading\": \"Section 1\", \"analysis\": \"Example analysis text\"}]'\n\n    python3 eyeball.py setup-check\n\n    python3 eyeball.py convert --source \u003cfile.docx\u003e --output \u003cfile.pdf\u003e\n\n    python3 eyeball.py screenshot \\\n        --source \u003cfile.pdf\u003e \\\n        --anchors '[\"term1\", \"term2\"]' \\\n        --page 5 \\\n        --output screenshot.png\n\"\"\"\n\nimport argparse\nimport io\nimport json\nimport os\nimport platform\nimport shutil\nimport subprocess\nimport sys\nimport tempfile\n\ntry:\n    import fitz  # PyMuPDF\nexcept ImportError:\n    fitz = None\n\ntry:\n    from PIL import Image, ImageDraw\nexcept ImportError:\n    Image = None\n    ImageDraw = None\n\ntry:\n    from docx import Document\n    from docx.shared import Inches, Pt, RGBColor\nexcept ImportError:\n    Document = None\n    Inches = None\n    Pt = None\n    RGBColor = None\n\n\ndef _resolve_path(path_str):\n    \"\"\"Expand ~ and environment variables in a user-provided path.\"\"\"\n    return os.path.expandvars(os.path.expanduser(path_str))\n\n\ndef _check_core_deps():\n    \"\"\"Raise if core dependencies are missing.\"\"\"\n    missing = []\n    if fitz is None:\n        missing.append(\"pymupdf\")\n    if Image is None:\n        missing.append(\"pillow\")\n    if Document is None:\n        missing.append(\"python-docx\")\n    if missing:\n        print(f\"Missing dependencies: {', '.join(missing)}\", file=sys.stderr)\n        print(f\"Run setup.sh or: {sys.executable} -m pip install pymupdf pillow python-docx playwright\", file=sys.stderr)\n        sys.exit(1)\n\n\n# ---------------------------------------------------------------------------\n# Document conversion: source -\u003e PDF\n# ---------------------------------------------------------------------------\n\ndef convert_to_pdf(source_path, output_pdf_path):\n    \"\"\"Convert a document to PDF. Supports .docx, .doc, .rtf, .html, .htm.\"\"\"\n    if not os.path.isfile(source_path):\n        raise FileNotFoundError(f\"Source file not found: {source_path}\")\n\n    ext = os.path.splitext(source_path)[1].lower()\n\n    if ext == \".pdf\":\n        if os.path.abspath(source_path) != os.path.abspath(output_pdf_path):\n            shutil.copy2(source_path, output_pdf_path)\n        return True\n\n    system = platform.system()\n\n    # Try Microsoft Word first on the current platform\n    if system == \"Darwin\" and ext in (\".docx\", \".doc\", \".rtf\"):\n        if os.path.exists(\"/Applications/Microsoft Word.app\"):\n            if _convert_with_word_mac(source_path, output_pdf_path):\n                return True\n\n    if system == \"Windows\" and ext in (\".docx\", \".doc\", \".rtf\"):\n        if _convert_with_word_windows(source_path, output_pdf_path):\n            return True\n\n    # Fall back to LibreOffice on any platform\n    soffice = shutil.which(\"libreoffice\") or shutil.which(\"soffice\")\n    if not soffice and system == \"Windows\":\n        soffice = _find_libreoffice_windows()\n    if soffice and ext in (\".docx\", \".doc\", \".rtf\", \".odt\", \".html\", \".htm\"):\n        if _convert_with_libreoffice(soffice, source_path, output_pdf_path):\n            return True\n\n    raise RuntimeError(\n        f\"Cannot convert {ext} to PDF. Install Microsoft Word (macOS/Windows) \"\n        f\"or LibreOffice (any platform).\"\n    )\n\n\ndef _convert_with_word_mac(source_path, output_pdf_path):\n    \"\"\"Convert using Microsoft Word on macOS via AppleScript.\"\"\"\n    source_abs = os.path.abspath(source_path)\n    output_abs = os.path.abspath(output_pdf_path)\n    # Escape characters that break AppleScript string interpolation\n    source_safe = source_abs.replace('\\\\', '\\\\\\\\').replace('\"', '\\\\\"')\n    output_safe = output_abs.replace('\\\\', '\\\\\\\\').replace('\"', '\\\\\"')\n    script = f'''\n    tell application \"Microsoft Word\"\n        open POSIX file \"{source_safe}\"\n        delay 5\n        set theDoc to active document\n        save as theDoc file name POSIX file \"{output_safe}\" file format format PDF\n        close theDoc saving no\n    end tell\n    '''\n    try:\n        result = subprocess.run(\n            [\"osascript\", \"-e\", script],\n            capture_output=True, text=True, timeout=120\n        )\n        return result.returncode == 0 and os.path.exists(output_pdf_path)\n    except (subprocess.TimeoutExpired, FileNotFoundError):\n        return False\n\n\ndef _convert_with_libreoffice(soffice_path, source_path, output_pdf_path):\n    \"\"\"Convert using LibreOffice headless mode.\"\"\"\n    with tempfile.TemporaryDirectory() as tmpdir:\n        try:\n            result = subprocess.run(\n                [soffice_path, \"--headless\", \"--convert-to\", \"pdf\",\n                 \"--outdir\", tmpdir, source_path],\n                capture_output=True, text=True, timeout=120\n            )\n            if result.returncode != 0:\n                return False\n            basename = os.path.splitext(os.path.basename(source_path))[0] + \".pdf\"\n            tmp_pdf = os.path.join(tmpdir, basename)\n            if os.path.exists(tmp_pdf):\n                shutil.move(tmp_pdf, output_pdf_path)\n                return True\n        except (subprocess.TimeoutExpired, FileNotFoundError):\n            pass\n    return False\n\n\ndef _find_libreoffice_windows():\n    \"\"\"Find LibreOffice in common Windows install locations.\"\"\"\n    candidates = []\n    for env_var in (\"ProgramFiles\", \"ProgramFiles(x86)\"):\n        base = os.environ.get(env_var)\n        if base:\n            candidates.append(os.path.join(base, \"LibreOffice\", \"program\", \"soffice.exe\"))\n    for path in candidates:\n        if os.path.isfile(path):\n            return path\n    return None\n\n\ndef _convert_with_word_windows(source_path, output_pdf_path):\n    \"\"\"Convert using Microsoft Word on Windows via win32com.\"\"\"\n    word = None\n    doc = None\n    try:\n        import win32com.client\n        source_abs = os.path.abspath(source_path)\n        output_abs = os.path.abspath(output_pdf_path)\n        os.makedirs(os.path.dirname(output_abs), exist_ok=True)\n\n        # DispatchEx creates an isolated Word process; fall back to Dispatch\n        # if the DCOM class isn't registered\n        try:\n            word = win32com.client.DispatchEx(\"Word.Application\")\n        except Exception:\n            word = win32com.client.Dispatch(\"Word.Application\")\n\n        word.Visible = False\n        word.DisplayAlerts = 0\n        try:\n            word.AutomationSecurity = 3  # msoAutomationSecurityForceDisable\n        except Exception:\n            pass\n\n        doc = word.Documents.Open(\n            FileName=source_abs,\n            ConfirmConversions=False,\n            ReadOnly=True,\n            AddToRecentFiles=False,\n            NoEncodingDialog=True,\n        )\n        doc.ExportAsFixedFormat(\n            OutputFileName=output_abs,\n            ExportFormat=17,  # wdExportFormatPDF\n            OpenAfterExport=False,\n        )\n        return os.path.isfile(output_abs)\n    except Exception:\n        return False\n    finally:\n        if doc is not None:\n            try:\n                doc.Close(False)\n            except Exception:\n                pass\n        if word is not None:\n            try:\n                word.Quit()\n            except Exception:\n                pass\n\n\ndef render_url_to_pdf(url, output_pdf_path):\n    \"\"\"Render a web page to PDF using Playwright.\"\"\"\n    try:\n        from playwright.sync_api import sync_playwright\n    except ImportError:\n        raise RuntimeError(\n            \"Playwright is required for web URL support. \"\n            f\"Run: {sys.executable} -m pip install playwright \u0026\u0026 \"\n            f\"{sys.executable} -m playwright install chromium\"\n        )\n\n    with sync_playwright() as p:\n        browser = None\n        try:\n            browser = p.chromium.launch(headless=True)\n            page = browser.new_page()\n            page.goto(url, wait_until=\"networkidle\", timeout=30000)\n\n            # Clean up navigation/footer elements for cleaner output\n            page.evaluate(\"\"\"\n                document.querySelectorAll(\n                    'header, footer, nav, [data-testid=\"header\"], [data-testid=\"footer\"], '\n                    + '.site-header, .site-footer, #cookie-banner, .cookie-consent'\n                ).forEach(el =\u003e el.remove());\n            \"\"\")\n\n            page.pdf(\n                path=output_pdf_path,\n                format=\"Letter\",\n                print_background=True,\n                margin={\"top\": \"0.5in\", \"bottom\": \"0.5in\",\n                        \"left\": \"0.75in\", \"right\": \"0.75in\"}\n            )\n        finally:\n            if browser is not None:\n                browser.close()\n\n\n# ---------------------------------------------------------------------------\n# Screenshot generation\n# ---------------------------------------------------------------------------\n\ndef screenshot_region(pdf_doc, anchors, target_page=None, target_pages=None,\n                      context_padding=40, dpi=200):\n    \"\"\"\n    Find anchor text in a PDF and capture the surrounding region as a highlighted image.\n\n    Args:\n        pdf_doc: An open fitz.Document.\n        anchors: List of search strings. The crop region expands to cover all of them.\n        target_page: Single 1-indexed page to search on.\n        target_pages: List of 1-indexed pages to search across (results stitched vertically).\n        context_padding: Extra padding in PDF points above/below the anchor region.\n        dpi: Render resolution.\n\n    Returns:\n        (image_bytes, page_label, (width, height)) or (None, None, None).\n    \"\"\"\n    if isinstance(anchors, str):\n        anchors = [anchors]\n\n    # Determine pages to search\n    if target_pages:\n        pages = [p - 1 for p in target_pages]\n    elif target_page is not None:\n        pages = [target_page - 1]\n    else:\n        pages = list(range(pdf_doc.page_count))\n\n    # Collect hits across pages\n    page_hits = {}\n    for pg_idx in pages:\n        if pg_idx \u003c 0 or pg_idx \u003e= pdf_doc.page_count:\n            continue\n        page = pdf_doc[pg_idx]\n        hits_on_page = []\n        for anchor in anchors:\n            found = page.search_for(anchor)\n            if found:\n                hits_on_page.extend([(anchor, h) for h in found])\n        if hits_on_page:\n            page_hits[pg_idx] = hits_on_page\n\n    if not page_hits:\n        return None, None, None\n\n    zoom = dpi / 72\n\n    # If single page, render one region\n    if len(page_hits) == 1:\n        pg_idx = list(page_hits.keys())[0]\n        img = _render_page_region(pdf_doc, pg_idx, page_hits[pg_idx],\n                                   context_padding, zoom)\n        img_bytes = _img_to_bytes(img)\n        return img_bytes, f\"page {pg_idx + 1}\", img.size\n\n    # Multi-page: stitch vertically\n    images = []\n    pages_used = sorted(page_hits.keys())\n    for pg_idx in pages_used:\n        img = _render_page_region(pdf_doc, pg_idx, page_hits[pg_idx],\n                                   context_padding, zoom)\n        images.append(img)\n\n    stitched = _stitch_vertical(images)\n    img_bytes = _img_to_bytes(stitched)\n\n    if len(pages_used) \u003e 1:\n        page_nums = \", \".join(str(p + 1) for p in pages_used)\n        page_label = f\"pages {page_nums}\"\n    else:\n        page_label = f\"page {pages_used[0]+1}\"\n\n    return img_bytes, page_label, stitched.size\n\n\ndef _render_page_region(pdf_doc, pg_idx, hits_with_anchors, context_padding, zoom):\n    \"\"\"Render a cropped region of a PDF page with highlighted anchor text.\"\"\"\n    page = pdf_doc[pg_idx]\n    page_rect = page.rect\n\n    all_rects = [h for _, h in hits_with_anchors]\n    min_y = min(r.y0 for r in all_rects)\n    max_y = max(r.y1 for r in all_rects)\n\n    crop_rect = fitz.Rect(\n        page_rect.x0 + 20,\n        max(page_rect.y0, min_y - context_padding),\n        page_rect.x1 - 20,\n        min(page_rect.y1, max_y + context_padding)\n    )\n\n    mat = fitz.Matrix(zoom, zoom)\n    pix = page.get_pixmap(matrix=mat, clip=crop_rect)\n    img = Image.frombytes(\"RGB\", [pix.width, pix.height], pix.samples)\n\n    # Highlight each anchor hit\n    draw = ImageDraw.Draw(img, \"RGBA\")\n    pad = max(2, round(2 * zoom))\n    for anchor, rect in hits_with_anchors:\n        if rect.y0 \u003e= crop_rect.y0 - 5 and rect.y1 \u003c= crop_rect.y1 + 5:\n            x0 = (rect.x0 - crop_rect.x0) * zoom\n            y0 = (rect.y0 - crop_rect.y0) * zoom\n            x1 = (rect.x1 - crop_rect.x0) * zoom\n            y1 = (rect.y1 - crop_rect.y0) * zoom\n            draw.rectangle([x0-pad, y0-pad, x1+pad, y1+pad], fill=(255, 255, 0, 100))\n\n    # Border\n    ImageDraw.Draw(img).rectangle(\n        [0, 0, img.width - 1, img.height - 1],\n        outline=(160, 160, 160), width=2\n    )\n\n    return img\n\n\ndef _stitch_vertical(images, gap=4):\n    \"\"\"Stitch multiple images vertically with a small gap between them.\"\"\"\n    total_height = sum(img.height for img in images) + gap * (len(images) - 1)\n    max_width = max(img.width for img in images)\n    stitched = Image.new(\"RGB\", (max_width, total_height), (255, 255, 255))\n    y = 0\n    for img in images:\n        stitched.paste(img, (0, y))\n        y += img.height + gap\n    ImageDraw.Draw(stitched).rectangle(\n        [0, 0, stitched.width - 1, stitched.height - 1],\n        outline=(160, 160, 160), width=2\n    )\n    return stitched\n\n\ndef _img_to_bytes(img):\n    \"\"\"Convert PIL Image to a PNG BytesIO buffer (file-like object).\"\"\"\n    buf = io.BytesIO()\n    img.save(buf, format=\"PNG\")\n    buf.seek(0)\n    return buf\n\n\n# ---------------------------------------------------------------------------\n# Output document assembly\n# ---------------------------------------------------------------------------\n\ndef build_analysis_doc(pdf_doc, sections, output_path, title=None, subtitle=None,\n                       source_label=None, dpi=200):\n    \"\"\"\n    Build a Word document with analysis sections and inline source screenshots.\n\n    Args:\n        pdf_doc: An open fitz.Document (the source, already converted to PDF).\n        sections: List of dicts, each with:\n            - heading (str): Section heading\n            - analysis (str): Analysis text\n            - anchors (list[str]): Verbatim phrases from source to search and highlight\n            - target_page (int, optional): 1-indexed page to search on\n            - target_pages (list[int], optional): Multiple pages to search across\n            - context_padding (int, optional): Extra padding in PDF points (default 40)\n        output_path: Where to save the output .docx file.\n        title: Document title.\n        subtitle: Document subtitle.\n        source_label: Label for the source (e.g., filename or URL).\n        dpi: Screenshot resolution.\n    \"\"\"\n    doc = Document()\n\n    # Style\n    style = doc.styles[\"Normal\"]\n    style.font.name = \"Calibri\"\n    style.font.size = Pt(11)\n\n    # Title\n    if title:\n        doc.add_heading(title, level=1)\n    if subtitle:\n        p = doc.add_paragraph()\n        run = p.add_run(subtitle)\n        run.font.size = Pt(11)\n        run.font.color.rgb = RGBColor(100, 100, 100)\n        doc.add_paragraph(\"\")\n\n    # Sections\n    for i, section in enumerate(sections):\n        heading = section.get(\"heading\", f\"Section {i+1}\")\n        analysis = section.get(\"analysis\", \"\")\n        anchors = section.get(\"anchors\", [])\n        target_page = section.get(\"target_page\")\n        target_pages = section.get(\"target_pages\")\n        padding = section.get(\"context_padding\", 40)\n\n        doc.add_heading(heading, level=2)\n        doc.add_paragraph(analysis)\n\n        if anchors:\n            img_bytes, page_label, size = screenshot_region(\n                pdf_doc, anchors,\n                target_page=target_page,\n                target_pages=target_pages,\n                context_padding=padding,\n                dpi=dpi\n            )\n\n            if img_bytes:\n                # Source label\n                p = doc.add_paragraph()\n                anchor_text = \", \".join(f'\"{a}\"' for a in anchors[:3])\n                if len(anchors) \u003e 3:\n                    anchor_text += f\" (+{len(anchors)-3} more)\"\n                label = f\"[Source: {source_label or 'document'}, {page_label}\"\n                label += f\" -- highlighted: {anchor_text}]\"\n                run = p.add_run(label)\n                run.font.size = Pt(8)\n                run.font.color.rgb = RGBColor(120, 120, 120)\n                run.font.italic = True\n                p.paragraph_format.space_before = Pt(6)\n                p.paragraph_format.space_after = Pt(2)\n\n                # Screenshot\n                doc.add_picture(img_bytes, width=Inches(5.8))\n                doc.paragraphs[-1].paragraph_format.space_after = Pt(12)\n            else:\n                # Anchors not found\n                p = doc.add_paragraph()\n                run = p.add_run(\n                    f\"[Screenshot not available: could not find \"\n                    f\"{', '.join(repr(a) for a in anchors)} in the source document]\"\n                )\n                run.font.size = Pt(9)\n                run.font.italic = True\n                run.font.color.rgb = RGBColor(180, 50, 50)\n\n    # Footer note\n    doc.add_paragraph(\"\")\n    note = doc.add_paragraph()\n    run = note.add_run(\n        \"Generated by Eyeball. Each screenshot is captured from the source document \"\n        \"with cited text highlighted in yellow. Screenshots are dynamically sized to \"\n        \"cover the full range of text referenced in the analysis. Review the highlighted \"\n        \"source material to verify each assertion.\"\n    )\n    run.font.size = Pt(9)\n    run.font.italic = True\n    run.font.color.rgb = RGBColor(130, 130, 130)\n\n    doc.save(output_path)\n    return output_path\n\n\n# ---------------------------------------------------------------------------\n# CLI commands\n# ---------------------------------------------------------------------------\n\ndef cmd_setup_check():\n    \"\"\"Check if all dependencies are available.\"\"\"\n    checks = {\n        \"PyMuPDF\": False,\n        \"Pillow\": False,\n        \"python-docx\": False,\n        \"Playwright\": False,\n        \"Chromium browser\": False,\n        \"Word (macOS)\": False,\n        \"Word (Windows)\": False,\n        \"LibreOffice\": False,\n    }\n\n    try:\n        import fitz\n        checks[\"PyMuPDF\"] = True\n    except ImportError:\n        pass\n\n    try:\n        from PIL import Image\n        checks[\"Pillow\"] = True\n    except ImportError:\n        pass\n\n    try:\n        from docx import Document\n        checks[\"python-docx\"] = True\n    except ImportError:\n        pass\n\n    try:\n        from playwright.sync_api import sync_playwright\n        checks[\"Playwright\"] = True\n    except ImportError:\n        pass\n\n    # Check Chromium across all platforms\n    pw_cache_candidates = []\n    system = platform.system()\n    if system == \"Darwin\":\n        pw_cache_candidates.append(os.path.expanduser(\"~/Library/Caches/ms-playwright\"))\n    if system == \"Windows\":\n        local_app_data = os.environ.get(\"LOCALAPPDATA\", \"\")\n        if local_app_data:\n            pw_cache_candidates.append(os.path.join(local_app_data, \"ms-playwright\"))\n    pw_cache_candidates.append(os.path.expanduser(\"~/.cache/ms-playwright\"))\n    # Respect PLAYWRIGHT_BROWSERS_PATH\n    custom_pw = os.environ.get(\"PLAYWRIGHT_BROWSERS_PATH\")\n    if custom_pw and custom_pw != \"0\":\n        pw_cache_candidates.insert(0, custom_pw)\n    for pw_cache in pw_cache_candidates:\n        if os.path.isdir(pw_cache) and any(\n            d.startswith(\"chromium\") for d in os.listdir(pw_cache)\n        ):\n            checks[\"Chromium browser\"] = True\n            break\n\n    # Check converters -- registry/filesystem only, never launch Word\n    if system == \"Darwin\" and os.path.exists(\"/Applications/Microsoft Word.app\"):\n        checks[\"Word (macOS)\"] = True\n\n    if system == \"Windows\":\n        try:\n            import winreg\n            word_reg_paths = [\n                (winreg.HKEY_LOCAL_MACHINE, r\"SOFTWARE\\Microsoft\\Windows\\CurrentVersion\\App Paths\\WINWORD.EXE\"),\n                (winreg.HKEY_CURRENT_USER, r\"SOFTWARE\\Microsoft\\Windows\\CurrentVersion\\App Paths\\WINWORD.EXE\"),\n                (winreg.HKEY_CLASSES_ROOT, r\"Word.Application\"),\n            ]\n            for hive, subkey in word_reg_paths:\n                try:\n                    winreg.OpenKey(hive, subkey)\n                    checks[\"Word (Windows)\"] = True\n                    break\n                except OSError:\n                    pass\n        except ImportError:\n            pass\n        # Check if pywin32 is available for Word automation\n        if checks[\"Word (Windows)\"]:\n            try:\n                import win32com.client  # noqa: F401\n            except ImportError:\n                checks[\"Word (Windows)\"] = False\n                print(\"  Note: Microsoft Word found but pywin32 is not installed.\")\n                print(f\"  Run: {sys.executable} -m pip install pywin32\")\n\n    if shutil.which(\"libreoffice\") or shutil.which(\"soffice\"):\n        checks[\"LibreOffice\"] = True\n    elif system == \"Windows\":\n        if _find_libreoffice_windows():\n            checks[\"LibreOffice\"] = True\n\n    print(\"Eyeball dependency check:\")\n    all_core = True\n    for name, ok in checks.items():\n        status = \"OK\" if ok else \"MISSING\"\n        marker = \"+\" if ok else \"-\"\n        print(f\"  [{marker}] {name}: {status}\")\n        if name in (\"PyMuPDF\", \"Pillow\", \"python-docx\") and not ok:\n            all_core = False\n\n    has_converter = checks[\"Word (macOS)\"] or checks[\"Word (Windows)\"] or checks[\"LibreOffice\"]\n    has_web = checks[\"Playwright\"] and checks[\"Chromium browser\"]\n\n    print(\"\")\n    print(\"Source support:\")\n    print(f\"  PDF files:   {'Ready' if all_core else 'Needs: pip3 install pymupdf pillow python-docx'}\")\n    print(f\"  Word docs:   {'Ready' if has_converter else 'Needs: Microsoft Word or LibreOffice'}\")\n    print(f\"  Web URLs:    {'Ready' if has_web else 'Needs: pip3 install playwright \u0026\u0026 python3 -m playwright install chromium'}\")\n\n    return 0 if all_core else 1\n\n\ndef cmd_convert(args):\n    \"\"\"Convert a document to PDF.\"\"\"\n    source = _resolve_path(args.source)\n    output = _resolve_path(args.output)\n\n    if source.startswith((\"http://\", \"https://\")):\n        render_url_to_pdf(source, output)\n    else:\n        convert_to_pdf(source, output)\n\n    print(f\"Converted: {output} ({os.path.getsize(output)} bytes)\")\n\n\ndef cmd_screenshot(args):\n    \"\"\"Generate a single screenshot from a PDF.\"\"\"\n    _check_core_deps()\n    source = _resolve_path(args.source)\n\n    if not os.path.isfile(source):\n        print(f\"Source file not found: {source}\", file=sys.stderr)\n        sys.exit(1)\n\n    ext = os.path.splitext(source)[1].lower()\n    if ext != \".pdf\":\n        print(f\"Source must be a PDF file (got {ext}). \"\n              f\"Use 'convert' to convert other formats first.\", file=sys.stderr)\n        sys.exit(1)\n\n    anchors = json.loads(args.anchors)\n    target_page = args.page\n    padding = args.padding\n    dpi = args.dpi\n\n    pdf_doc = fitz.open(source)\n    try:\n        img_bytes, page_label, size = screenshot_region(\n            pdf_doc, anchors,\n            target_page=target_page,\n            context_padding=padding,\n            dpi=dpi\n        )\n    finally:\n        pdf_doc.close()\n\n    if img_bytes:\n        output = _resolve_path(args.output)\n        with open(output, \"wb\") as f:\n            f.write(img_bytes.getvalue())\n        print(f\"Screenshot saved: {output} ({size[0]}x{size[1]}px, {page_label})\")\n    else:\n        print(f\"No matches found for: {anchors}\", file=sys.stderr)\n        sys.exit(1)\n\n\ndef cmd_build(args):\n    \"\"\"Build a complete analysis document.\"\"\"\n    _check_core_deps()\n    source = _resolve_path(args.source)\n    output = _resolve_path(args.output)\n    sections = json.loads(args.sections)\n    title = args.title\n    subtitle = args.subtitle\n    dpi = args.dpi\n\n    if not source.startswith((\"http://\", \"https://\")) and not os.path.isfile(source):\n        print(f\"Source file not found: {source}\", file=sys.stderr)\n        sys.exit(1)\n\n    # Determine source type and convert to PDF\n    with tempfile.NamedTemporaryFile(suffix=\".pdf\", delete=False) as tmp:\n        tmp_pdf = tmp.name\n\n    pdf_doc = None\n    try:\n        if source.startswith((\"http://\", \"https://\")):\n            render_url_to_pdf(source, tmp_pdf)\n            source_label = source\n        elif source.lower().endswith(\".pdf\"):\n            shutil.copy2(source, tmp_pdf)\n            source_label = os.path.basename(source)\n        else:\n            convert_to_pdf(source, tmp_pdf)\n            source_label = os.path.basename(source)\n\n        pdf_doc = fitz.open(tmp_pdf)\n        build_analysis_doc(\n            pdf_doc, sections, output,\n            title=title, subtitle=subtitle,\n            source_label=source_label,\n            dpi=dpi\n        )\n\n        size_kb = os.path.getsize(output) / 1024\n        print(f\"Analysis saved: {output} ({size_kb:.0f} KB)\")\n\n    finally:\n        if pdf_doc is not None:\n            pdf_doc.close()\n        if os.path.exists(tmp_pdf):\n            os.unlink(tmp_pdf)\n\n\ndef cmd_extract_text(args):\n    \"\"\"Extract text from a source document (for the AI to read before writing analysis).\"\"\"\n    _check_core_deps()\n    source = _resolve_path(args.source)\n\n    if not source.startswith((\"http://\", \"https://\")) and not os.path.isfile(source):\n        print(f\"Source file not found: {source}\", file=sys.stderr)\n        sys.exit(1)\n\n    with tempfile.NamedTemporaryFile(suffix=\".pdf\", delete=False) as tmp:\n        tmp_pdf = tmp.name\n\n    pdf_doc = None\n    try:\n        if source.startswith((\"http://\", \"https://\")):\n            render_url_to_pdf(source, tmp_pdf)\n        elif source.lower().endswith(\".pdf\"):\n            shutil.copy2(source, tmp_pdf)\n        else:\n            convert_to_pdf(source, tmp_pdf)\n\n        pdf_doc = fitz.open(tmp_pdf)\n        for i in range(pdf_doc.page_count):\n            text = pdf_doc[i].get_text()\n            print(f\"\\n[PAGE {i+1}]\")\n            print(text)\n\n    finally:\n        if pdf_doc is not None:\n            pdf_doc.close()\n        if os.path.exists(tmp_pdf):\n            os.unlink(tmp_pdf)\n\n\ndef main():\n    parser = argparse.ArgumentParser(\n        description=\"Eyeball: Document analysis with inline source screenshots\"\n    )\n    sub = parser.add_subparsers(dest=\"command\")\n\n    # setup-check\n    sub.add_parser(\"setup-check\", help=\"Check dependencies\")\n\n    # convert\n    p_conv = sub.add_parser(\"convert\", help=\"Convert a document to PDF\")\n    p_conv.add_argument(\"--source\", required=True)\n    p_conv.add_argument(\"--output\", required=True)\n\n    # screenshot\n    p_ss = sub.add_parser(\"screenshot\", help=\"Generate a screenshot from a PDF\")\n    p_ss.add_argument(\"--source\", required=True, help=\"PDF file path\")\n    p_ss.add_argument(\"--anchors\", required=True, help=\"JSON array of search terms\")\n    p_ss.add_argument(\"--page\", type=int, help=\"Target page (1-indexed)\")\n    p_ss.add_argument(\"--padding\", type=int, default=40)\n    p_ss.add_argument(\"--dpi\", type=int, default=200)\n    p_ss.add_argument(\"--output\", required=True, help=\"Output PNG path\")\n\n    # build\n    p_build = sub.add_parser(\"build\", help=\"Build analysis document\")\n    p_build.add_argument(\"--source\", required=True,\n                         help=\"Source document path or URL\")\n    p_build.add_argument(\"--output\", required=True,\n                         help=\"Output .docx path\")\n    p_build.add_argument(\"--sections\", required=True,\n                         help=\"JSON array of section objects\")\n    p_build.add_argument(\"--title\", help=\"Document title\")\n    p_build.add_argument(\"--subtitle\", help=\"Document subtitle\")\n    p_build.add_argument(\"--dpi\", type=int, default=200)\n\n    # extract-text\n    p_text = sub.add_parser(\"extract-text\",\n                            help=\"Extract text from a document (for AI analysis)\")\n    p_text.add_argument(\"--source\", required=True)\n\n    args = parser.parse_args()\n\n    if args.command == \"setup-check\":\n        sys.exit(cmd_setup_check())\n    elif args.command == \"convert\":\n        cmd_convert(args)\n    elif args.command == \"screenshot\":\n        cmd_screenshot(args)\n    elif args.command == \"build\":\n        cmd_build(args)\n    elif args.command == \"extract-text\":\n        cmd_extract_text(args)\n    else:\n        parser.print_help()\n        sys.exit(1)\n\n\nif __name__ == \"__main__\":\n    main()\n"},"import":{"commit_sha":"541b7819d8c3545c6df122491af4fa1eae415779","imported_at":"2026-05-18T20:05:35Z","license_text":"MIT License\n\nCopyright GitHub, Inc.\n\nPermission is hereby granted, free of charge, to any person obtaining a copy\nof this software and associated documentation files (the \"Software\"), to deal\nin the Software without restriction, including without limitation the rights\nto use, copy, modify, merge, publish, distribute, sublicense, and/or sell\ncopies of the Software, and to permit persons to whom the Software is\nfurnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all\ncopies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\nSOFTWARE.","owner":"github","repo":"github/awesome-copilot","source_url":"https://github.com/github/awesome-copilot/tree/541b7819d8c3545c6df122491af4fa1eae415779/plugins/eyeball/skills/eyeball"}},"content_hash":[114,76,3,19,169,190,62,152,246,222,84,106,171,115,113,57,52,245,190,204,215,246,229,21,22,224,50,13,190,138,76,6],"trust_level":"unsigned","yanked":false}