appsnap 0.2.0__tar.gz

appsnap-0.2.0/.github/workflows/publish.yml

@@ -0,0 +1,59 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*" # Trigger on version tags like v0.2.0, v1.0.0, etc.
+  release:
+    types: [published] # Also trigger on GitHub releases
+  workflow_dispatch: # Allow manual trigger from Actions tab
+
+jobs:
+  build-and-publish:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+
+      - name: Install build dependencies
+        run: |
+          uv pip install --system build twine
+
+      - name: Build package
+        run: |
+          python -m build
+
+      - name: Check package
+        run: |
+          twine check dist/*
+
+      - name: Publish to PyPI
+        env:
+          TWINE_USERNAME: __token__
+          TWINE_PASSWORD: ${{ secrets.PYPI_API_TOKEN }}
+        run: |
+          twine upload dist/*
+
+      - name: Upload build artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Create GitHub Release (if tag push)
+        if: startsWith(github.ref, 'refs/tags/')
+        uses: softprops/action-gh-release@v1
+        with:
+          files: dist/*
+          generate_release_notes: true
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

appsnap-0.2.0/.github/workflows/test.yml

@@ -0,0 +1,48 @@
+name: Tests
+
+on:
+  push:
+    branches: [main, master]
+  pull_request:
+    branches: [main, master]
+  workflow_dispatch:
+
+jobs:
+  test:
+    runs-on: windows-latest
+
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+
+      - name: Install dependencies
+        run: |
+          uv pip install --system -e .
+
+      - name: Test CLI
+        run: |
+          appsnap --version
+          appsnap --help
+          appsnap --list
+
+      - name: Build package
+        run: |
+          uv pip install --system build
+          python -m build
+
+      - name: Check distribution
+        run: |
+          uv pip install --system twine
+          twine check dist/*

appsnap-0.2.0/.gitignore

@@ -0,0 +1,154 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+.python-version
+
+# pipenv
+Pipfile.lock
+
+# poetry
+poetry.lock
+
+# pdm
+.pdm.toml
+
+# PEP 582
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# IDEs
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Project specific
+*.png
+*.jpg
+*.jpeg
+*.bmp
+screenshots/

appsnap-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 appsnap contributors
+
+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.

appsnap-0.2.0/MANIFEST.in

@@ -0,0 +1,5 @@
+include README.md
+include LICENSE
+include PUBLISHING.md
+include pyproject.toml
+recursive-include src *.py

appsnap-0.2.0/PKG-INFO

@@ -0,0 +1,281 @@
+Metadata-Version: 2.4
+Name: appsnap
+Version: 0.2.0
+Summary: Fast Windows screenshot tool for AI coding agents
+Project-URL: Homepage, https://github.com/detroittommy879/appsnap
+Project-URL: Repository, https://github.com/detroittommy879/appsnap
+Project-URL: Issues, https://github.com/detroittommy879/appsnap/issues
+Project-URL: Documentation, https://github.com/detroittommy879/appsnap#readme
+Project-URL: Changelog, https://github.com/detroittommy879/appsnap/releases
+Author: appsnap contributors
+License: MIT
+License-File: LICENSE
+Keywords: ai-agent,automation,cli,desktop,screenshot,windows
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Testing
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Requires-Dist: fuzzywuzzy>=0.18.0
+Requires-Dist: pillow>=11.0.0
+Requires-Dist: python-levenshtein>=0.25.0
+Requires-Dist: pywin32>=306
+Provides-Extra: dev
+Requires-Dist: black>=24.0.0; extra == 'dev'
+Requires-Dist: pytest-cov>=4.1.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.3.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# 📸 appsnap
+
+**Fast Windows screenshot tool for AI coding agents**
+
+`appsnap` is a simple, fast CLI tool for capturing screenshots of Windows application windows. Perfect for AI agents that need to verify UI changes during development iterations.
+
+## ✨ Features
+
+- 🎯 **Window-specific capture** - Target apps by name with fuzzy matching
+- � **Bulk capture** - Screenshot all windows at once for testing
+- 🚀 **Fast** - Screenshots in ~0.1-0.3 seconds
+- 🤖 **Agent-friendly** - JSON output and stdout paths for easy parsing
+- 📁 **Smart defaults** - Temp directory with auto-cleanup
+- 🔍 **List windows** - See all capturable windows
+- 🎨 **DPI-aware** - Handles high-DPI displays correctly
+- 🔢 **Duplicate handling** - Auto-numbers windows with identical titles
+
+## 🚀 Quick Start
+
+### Installation
+
+```bash
+# Install from PyPI with uvx (recommended)
+uvx appsnap
+
+# Or install as a tool with uv
+uv tool install appsnap
+
+# Or with pipx
+pipx install appsnap
+
+# Install from GitHub (development version)
+uv tool install git+https://github.com/detroittommy879/appsnap.git
+
+# Development mode (local testing)
+git clone https://github.com/detroittommy879/appsnap.git
+cd appsnap
+uv venv
+uv pip install -e .
+```
+
+### Usage
+
+**Option 1: After activating venv**
+
+```bash
+# Activate the virtual environment first
+.venv\Scripts\activate  # Windows
+# source .venv/bin/activate  # Linux/Mac
+
+# Then use appsnap directly
+appsnap --list
+appsnap "Visual Studio Code"
+```
+
+**Option 2: Using uv run (no activation needed)**
+
+```bash
+# Run from within the appsnap directory
+cd appsnap
+uv run appsnap --list
+uv run appsnap "Chrome" --output screenshot.png
+```
+
+**Common Commands:**
+
+```bash
+# List all capturable windows
+appsnap --list
+
+# Capture a window (saves to temp directory)
+appsnap "Visual Studio Code"
+
+# Capture with custom output path
+appsnap "Chrome" --output screenshot.png
+
+# JSON output for agents
+appsnap "Notepad" --json
+# {"path": "C:\\Temp\\appsnap\\appsnap_20260202_153045.png", "window": "Notepad", "bbox": [100, 200, 800, 600]}
+
+# Adjust fuzzy matching threshold (0-100, default 70)
+appsnap "VS" --threshold 60
+
+# Capture ALL windows to a folder (great for testing!)
+appsnap --all ./screenshots
+
+# Capture all with JSON summary
+appsnap --all ./test-screens --json
+```
+
+## 🤖 AI Agent Integration
+
+### Claude Desktop Skill
+
+Add to your agent prompt or skill:
+
+```
+When you need to verify UI changes, use: appsnap "App Name" --json
+Parse the JSON output to get the screenshot path and window metadata.
+```
+
+### Python Integration
+
+```python
+import subprocess
+import json
+
+result = subprocess.run(
+    ["appsnap", "Chrome", "--json"],
+    capture_output=True,
+    text=True
+)
+data = json.loads(result.stdout)
+screenshot_path = data["path"]
+```
+
+### PowerShell Integration
+
+```powershell
+$result = appsnap "VSCode" --json | ConvertFrom-Json
+Write-Host "Screenshot: $($result.path)"
+```
+
+## 📖 CLI Options
+
+```
+positional arguments:
+  window_name           Window title to search for (fuzzy matching)
+
+options:
+  -h, --help            Show this help message and exit
+  -l, --list            List all capturable windows
+  -a DIR, --all DIR     Capture all windows to specified directory
+  -o PATH, --output PATH
+                        Output file path (default: temp directory)
+  -t N, --threshold N   Fuzzy match threshold 0-100 (default: 70)
+  -j, --json            Output JSON with path and metadata
+```
+
+### Bulk Capture Example
+
+The `--all` flag is perfect for quickly testing that all windows capture correctly:
+
+```bash
+# Capture all windows to a test folder
+uv run appsnap --all ./test-captures
+
+# Output:
+# Capturing 42 window(s) to C:\path\to\test-captures...
+#
+# [OK] Visual Studio Code
+# [OK] Chrome - Google Search
+# [OK] Task Manager
+# [OK] Settings
+# [OK] PowerShell_1  # Auto-numbered duplicate
+# [OK] PowerShell_2  # Auto-numbered duplicate
+# ...
+#
+# Complete: 40 successful, 2 failed
+# Screenshots saved to: C:\path\to\test-captures
+```
+
+Windows with the same title automatically get numbered (e.g., `PowerShell_1.png`, `PowerShell_2.png`).
+
+## 🛠️ How It Works
+
+1. **DPI Awareness** - Sets process DPI awareness for correct scaling on high-DPI displays
+2. **Window Enumeration** - Uses Win32 API to enumerate all visible, non-minimized windows
+3. **Fuzzy Matching** - Finds windows using `fuzzywuzzy` for flexible name matching
+4. **Direct Window Capture** - Uses Win32 `PrintWindow` API to capture window content directly (works even when partially occluded)
+5. **Output** - Saves to temp or custom location, prints path to stdout for easy agent parsing
+
+## 🔧 Development
+
+```bash
+# Clone and install dev dependencies
+git clone <repo>
+cd appsnap
+uv pip install -e ".[dev]"
+
+# Run tests
+uv run pytest
+
+# Run with local changes
+uv run appsnap --list
+```
+
+## 🐛 Troubleshooting
+
+### "No window found matching..."
+
+- Use `appsnap --list` to see exact window titles
+- Try lowering the threshold: `--threshold 60`
+- Make sure the window is visible (not minimized)
+
+### Screenshots are blank, wrong window, or multiple windows
+
+**v0.1.1 Fix:** Switched to Win32 PrintWindow API for direct window content capture.
+
+This method captures the actual window content, not screen regions, so it:
+
+- Works correctly on multi-monitor setups
+- Captures partially occluded windows
+- Handles DPI scaling properly
+
+If you still have issues:
+
+- Ensure the window is not minimized (minimized windows cannot be captured)
+- Some apps (especially GPU-accelerated ones) may not respond to PrintWindow correctly
+- Try bringing the window to foreground if capture fails
+
+### DPI/Scaling issues
+
+The tool automatically handles DPI awareness. If you see incorrect sizing:
+
+- Ensure Windows display scaling is consistent
+- Check that the app respects DPI settings
+
+## 📝 License
+
+MIT License - see [LICENSE](LICENSE) for details
+
+## 🙏 Acknowledgments
+
+Built on the excellent Windows-MCP project patterns and libraries:
+
+- [Pillow](https://github.com/python-pillow/Pillow) - Screenshot capture and image processing
+- [fuzzywuzzy](https://github.com/seatgeek/fuzzywuzzy) - Fuzzy string matching
+- [pywin32](https://github.com/mhammond/pywin32) - Windows API access
+
+## 🤝 Contributing
+
+Contributions welcome! Please feel free to submit issues or pull requests.
+
+For maintainers publishing to PyPI, see [PUBLISHING.md](PUBLISHING.md) for detailed instructions on:
+
+- Setting up GitHub Actions for automated PyPI releases
+- Manual publishing workflow
+- AI agent skill integration
+- Troubleshooting
+
+---
+
+Made for AI agents, by developers 🤖❤️