diffgrab 0.1.0__tar.gz

diffgrab-0.1.0/.gitignore

@@ -0,0 +1,12 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.venv/
+.pytest_cache/
+.ruff_cache/
+.env
+.env.local
+CLAUDE.md
+PLAN.txt

diffgrab-0.1.0/LICENSE

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

diffgrab-0.1.0/PKG-INFO

@@ -0,0 +1,237 @@
+Metadata-Version: 2.4
+Name: diffgrab
+Version: 0.1.0
+Summary: Web page change tracking with structured diffs — markgrab + snapgrab integration, MCP native.
+Project-URL: Homepage, https://github.com/QuartzUnit/diffgrab
+Project-URL: Repository, https://github.com/QuartzUnit/diffgrab
+Author: QuartzUnit
+License-Expression: MIT
+License-File: LICENSE
+Keywords: change-detection,diff,markgrab,mcp,monitoring,web
+Classifier: Development Status :: 3 - Alpha
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.28
+Requires-Dist: markgrab>=0.1.2
+Provides-Extra: all
+Requires-Dist: click>=8.0; extra == 'all'
+Requires-Dist: fastmcp>=2.0; extra == 'all'
+Requires-Dist: rich>=13.0; extra == 'all'
+Requires-Dist: snapgrab>=0.1.0; extra == 'all'
+Provides-Extra: cli
+Requires-Dist: click>=8.0; extra == 'cli'
+Requires-Dist: rich>=13.0; extra == 'cli'
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.8; extra == 'dev'
+Provides-Extra: mcp
+Requires-Dist: fastmcp>=2.0; extra == 'mcp'
+Provides-Extra: visual
+Requires-Dist: snapgrab>=0.1.0; extra == 'visual'
+Description-Content-Type: text/markdown
+
+# diffgrab
+
+[![PyPI](https://img.shields.io/pypi/v/diffgrab)](https://pypi.org/project/diffgrab/)
+[![Python](https://img.shields.io/pypi/pyversions/diffgrab)](https://pypi.org/project/diffgrab/)
+[![License](https://img.shields.io/github/license/QuartzUnit/diffgrab)](https://github.com/QuartzUnit/diffgrab/blob/main/LICENSE)
+
+> Web page change tracking with structured diffs. markgrab + snapgrab integration, MCP native.
+
+```python
+from diffgrab import DiffTracker
+
+tracker = DiffTracker()
+await tracker.track("https://example.com")
+changes = await tracker.check()
+for c in changes:
+    if c.changed:
+        print(c.summary)     # "3 lines added, 1 lines removed in sections: Introduction."
+        print(c.unified_diff) # Standard unified diff output
+await tracker.close()
+```
+
+## Features
+
+- **Change detection** — track any URL, detect content changes via content hashing
+- **Structured diffs** — unified diff + section-level analysis (which headings changed)
+- **Human-readable summaries** — "5 lines added, 2 removed in sections: Intro, Methods"
+- **Snapshot history** — SQLite storage, browse past versions of any page
+- **markgrab powered** — HTML/YouTube/PDF/DOCX extraction via [markgrab](https://github.com/QuartzUnit/markgrab)
+- **Visual diff** — optional screenshot comparison via [snapgrab](https://github.com/QuartzUnit/snapgrab)
+- **MCP server** — 5 tools for Claude Code / MCP clients
+- **CLI included** — `diffgrab track`, `check`, `diff`, `history`, `untrack`
+
+## Install
+
+```bash
+pip install diffgrab
+```
+
+Optional extras:
+
+```bash
+pip install 'diffgrab[cli]'      # CLI with click + rich
+pip install 'diffgrab[visual]'   # Visual diff with snapgrab
+pip install 'diffgrab[mcp]'      # MCP server with fastmcp
+pip install 'diffgrab[all]'      # Everything
+```
+
+## Usage
+
+### Python API
+
+```python
+import asyncio
+from diffgrab import DiffTracker
+
+async def main():
+    tracker = DiffTracker()
+
+    # Track a URL (takes initial snapshot)
+    await tracker.track("https://example.com", interval_hours=12)
+
+    # Check for changes
+    changes = await tracker.check()
+    for change in changes:
+        if change.changed:
+            print(change.summary)
+            print(change.unified_diff)
+
+    # Get diff between specific snapshots
+    result = await tracker.diff("https://example.com", before_id=1, after_id=2)
+
+    # Browse snapshot history
+    history = await tracker.history("https://example.com", count=20)
+
+    # Stop tracking
+    await tracker.untrack("https://example.com")
+
+    await tracker.close()
+
+asyncio.run(main())
+```
+
+### Convenience Functions
+
+```python
+from diffgrab import track, check, diff, history, untrack
+
+await track("https://example.com")
+changes = await check()
+result = await diff("https://example.com")
+snaps = await history("https://example.com")
+await untrack("https://example.com")
+```
+
+### CLI
+
+```bash
+# Track a URL
+diffgrab track https://example.com --interval 12
+
+# Check all tracked URLs for changes
+diffgrab check
+
+# Check a specific URL
+diffgrab check https://example.com
+
+# Show diff between snapshots
+diffgrab diff https://example.com
+diffgrab diff https://example.com --before 1 --after 3
+
+# View snapshot history
+diffgrab history https://example.com --count 20
+
+# Stop tracking
+diffgrab untrack https://example.com
+```
+
+### MCP Server
+
+Add to your Claude Code MCP config:
+
+```json
+{
+  "mcpServers": {
+    "diffgrab": {
+      "command": "diffgrab-mcp",
+      "args": []
+    }
+  }
+}
+```
+
+Or with uvx:
+
+```json
+{
+  "mcpServers": {
+    "diffgrab": {
+      "command": "uvx",
+      "args": ["--from", "diffgrab[mcp]", "diffgrab-mcp"]
+    }
+  }
+}
+```
+
+**MCP Tools:**
+
+| Tool | Description |
+|------|-------------|
+| `track_url` | Register a URL for change tracking |
+| `check_changes` | Check tracked URLs for changes |
+| `get_diff` | Get structured diff between snapshots |
+| `get_history` | Browse snapshot history |
+| `untrack_url` | Stop tracking a URL |
+
+## DiffResult
+
+Every diff operation returns a `DiffResult`:
+
+```python
+@dataclass
+class DiffResult:
+    url: str                           # The tracked URL
+    changed: bool                      # Whether content changed
+    added_lines: int                   # Lines added
+    removed_lines: int                 # Lines removed
+    changed_sections: list[str]        # Markdown headings with changes
+    unified_diff: str                  # Standard unified diff
+    summary: str                       # Human-readable summary
+    before_snapshot_id: int | None     # DB ID of older snapshot
+    after_snapshot_id: int | None      # DB ID of newer snapshot
+    before_timestamp: str              # When older snapshot was taken
+    after_timestamp: str               # When newer snapshot was taken
+```
+
+## Storage
+
+Snapshots are stored in SQLite at `~/.local/share/diffgrab/diffgrab.db` (auto-created). Custom path:
+
+```python
+tracker = DiffTracker(db_path="/path/to/custom.db")
+```
+
+## QuartzUnit Ecosystem
+
+| Package | Role | PyPI |
+|---------|------|------|
+| [markgrab](https://github.com/QuartzUnit/markgrab) | HTML/YouTube/PDF/DOCX to markdown | `pip install markgrab` |
+| [snapgrab](https://github.com/QuartzUnit/snapgrab) | URL to screenshot + metadata | `pip install snapgrab` |
+| [docpick](https://github.com/QuartzUnit/docpick) | OCR + LLM document extraction | `pip install docpick` |
+| [feedkit](https://github.com/QuartzUnit/feedkit) | RSS feed collection | `pip install feedkit` |
+| **diffgrab** | **Web page change tracking** | `pip install diffgrab` |
+| [browsegrab](https://github.com/QuartzUnit/browsegrab) | Browser agent for LLMs | Coming soon |
+
+## License
+
+[MIT](LICENSE)
+
+<!-- mcp-name: io.github.ArkNill/diffgrab -->

diffgrab-0.1.0/README.md

@@ -0,0 +1,199 @@
+# diffgrab
+
+[![PyPI](https://img.shields.io/pypi/v/diffgrab)](https://pypi.org/project/diffgrab/)
+[![Python](https://img.shields.io/pypi/pyversions/diffgrab)](https://pypi.org/project/diffgrab/)
+[![License](https://img.shields.io/github/license/QuartzUnit/diffgrab)](https://github.com/QuartzUnit/diffgrab/blob/main/LICENSE)
+
+> Web page change tracking with structured diffs. markgrab + snapgrab integration, MCP native.
+
+```python
+from diffgrab import DiffTracker
+
+tracker = DiffTracker()
+await tracker.track("https://example.com")
+changes = await tracker.check()
+for c in changes:
+    if c.changed:
+        print(c.summary)     # "3 lines added, 1 lines removed in sections: Introduction."
+        print(c.unified_diff) # Standard unified diff output
+await tracker.close()
+```
+
+## Features
+
+- **Change detection** — track any URL, detect content changes via content hashing
+- **Structured diffs** — unified diff + section-level analysis (which headings changed)
+- **Human-readable summaries** — "5 lines added, 2 removed in sections: Intro, Methods"
+- **Snapshot history** — SQLite storage, browse past versions of any page
+- **markgrab powered** — HTML/YouTube/PDF/DOCX extraction via [markgrab](https://github.com/QuartzUnit/markgrab)
+- **Visual diff** — optional screenshot comparison via [snapgrab](https://github.com/QuartzUnit/snapgrab)
+- **MCP server** — 5 tools for Claude Code / MCP clients
+- **CLI included** — `diffgrab track`, `check`, `diff`, `history`, `untrack`
+
+## Install
+
+```bash
+pip install diffgrab
+```
+
+Optional extras:
+
+```bash
+pip install 'diffgrab[cli]'      # CLI with click + rich
+pip install 'diffgrab[visual]'   # Visual diff with snapgrab
+pip install 'diffgrab[mcp]'      # MCP server with fastmcp
+pip install 'diffgrab[all]'      # Everything
+```
+
+## Usage
+
+### Python API
+
+```python
+import asyncio
+from diffgrab import DiffTracker
+
+async def main():
+    tracker = DiffTracker()
+
+    # Track a URL (takes initial snapshot)
+    await tracker.track("https://example.com", interval_hours=12)
+
+    # Check for changes
+    changes = await tracker.check()
+    for change in changes:
+        if change.changed:
+            print(change.summary)
+            print(change.unified_diff)
+
+    # Get diff between specific snapshots
+    result = await tracker.diff("https://example.com", before_id=1, after_id=2)
+
+    # Browse snapshot history
+    history = await tracker.history("https://example.com", count=20)
+
+    # Stop tracking
+    await tracker.untrack("https://example.com")
+
+    await tracker.close()
+
+asyncio.run(main())
+```
+
+### Convenience Functions
+
+```python
+from diffgrab import track, check, diff, history, untrack
+
+await track("https://example.com")
+changes = await check()
+result = await diff("https://example.com")
+snaps = await history("https://example.com")
+await untrack("https://example.com")
+```
+
+### CLI
+
+```bash
+# Track a URL
+diffgrab track https://example.com --interval 12
+
+# Check all tracked URLs for changes
+diffgrab check
+
+# Check a specific URL
+diffgrab check https://example.com
+
+# Show diff between snapshots
+diffgrab diff https://example.com
+diffgrab diff https://example.com --before 1 --after 3
+
+# View snapshot history
+diffgrab history https://example.com --count 20
+
+# Stop tracking
+diffgrab untrack https://example.com
+```
+
+### MCP Server
+
+Add to your Claude Code MCP config:
+
+```json
+{
+  "mcpServers": {
+    "diffgrab": {
+      "command": "diffgrab-mcp",
+      "args": []
+    }
+  }
+}
+```
+
+Or with uvx:
+
+```json
+{
+  "mcpServers": {
+    "diffgrab": {
+      "command": "uvx",
+      "args": ["--from", "diffgrab[mcp]", "diffgrab-mcp"]
+    }
+  }
+}
+```
+
+**MCP Tools:**
+
+| Tool | Description |
+|------|-------------|
+| `track_url` | Register a URL for change tracking |
+| `check_changes` | Check tracked URLs for changes |
+| `get_diff` | Get structured diff between snapshots |
+| `get_history` | Browse snapshot history |
+| `untrack_url` | Stop tracking a URL |
+
+## DiffResult
+
+Every diff operation returns a `DiffResult`:
+
+```python
+@dataclass
+class DiffResult:
+    url: str                           # The tracked URL
+    changed: bool                      # Whether content changed
+    added_lines: int                   # Lines added
+    removed_lines: int                 # Lines removed
+    changed_sections: list[str]        # Markdown headings with changes
+    unified_diff: str                  # Standard unified diff
+    summary: str                       # Human-readable summary
+    before_snapshot_id: int | None     # DB ID of older snapshot
+    after_snapshot_id: int | None      # DB ID of newer snapshot
+    before_timestamp: str              # When older snapshot was taken
+    after_timestamp: str               # When newer snapshot was taken
+```
+
+## Storage
+
+Snapshots are stored in SQLite at `~/.local/share/diffgrab/diffgrab.db` (auto-created). Custom path:
+
+```python
+tracker = DiffTracker(db_path="/path/to/custom.db")
+```
+
+## QuartzUnit Ecosystem
+
+| Package | Role | PyPI |
+|---------|------|------|
+| [markgrab](https://github.com/QuartzUnit/markgrab) | HTML/YouTube/PDF/DOCX to markdown | `pip install markgrab` |
+| [snapgrab](https://github.com/QuartzUnit/snapgrab) | URL to screenshot + metadata | `pip install snapgrab` |
+| [docpick](https://github.com/QuartzUnit/docpick) | OCR + LLM document extraction | `pip install docpick` |
+| [feedkit](https://github.com/QuartzUnit/feedkit) | RSS feed collection | `pip install feedkit` |
+| **diffgrab** | **Web page change tracking** | `pip install diffgrab` |
+| [browsegrab](https://github.com/QuartzUnit/browsegrab) | Browser agent for LLMs | Coming soon |
+
+## License
+
+[MIT](LICENSE)
+
+<!-- mcp-name: io.github.ArkNill/diffgrab -->

diffgrab-0.1.0/diffgrab/__init__.py

@@ -0,0 +1,109 @@
+"""diffgrab — Web page change tracking with structured diffs."""
+
+from __future__ import annotations
+
+from diffgrab.differ import DiffResult
+from diffgrab.tracker import DiffTracker
+
+__all__ = ["DiffTracker", "DiffResult", "track", "check", "diff", "history", "untrack"]
+__version__ = "0.1.0"
+
+
+async def track(url: str, interval_hours: int = 24, *, db_path: str = "") -> str:
+    """Register a URL for change tracking.
+
+    Args:
+        url: The URL to track.
+        interval_hours: Check interval in hours (default: 24).
+        db_path: Custom database path (optional).
+
+    Returns:
+        Status message.
+    """
+    kwargs = {"db_path": db_path} if db_path else {}
+    tracker = DiffTracker(**kwargs)
+    try:
+        return await tracker.track(url, interval_hours)
+    finally:
+        await tracker.close()
+
+
+async def check(url: str | None = None, *, db_path: str = "") -> list[DiffResult]:
+    """Check tracked URLs for changes.
+
+    Args:
+        url: Specific URL to check, or None for all.
+        db_path: Custom database path (optional).
+
+    Returns:
+        List of DiffResult objects.
+    """
+    kwargs = {"db_path": db_path} if db_path else {}
+    tracker = DiffTracker(**kwargs)
+    try:
+        return await tracker.check(url)
+    finally:
+        await tracker.close()
+
+
+async def diff(
+    url: str,
+    before_id: int | None = None,
+    after_id: int | None = None,
+    *,
+    db_path: str = "",
+) -> DiffResult:
+    """Get structured diff between two snapshots of a URL.
+
+    Args:
+        url: The URL to diff.
+        before_id: Database ID of the older snapshot.
+        after_id: Database ID of the newer snapshot.
+        db_path: Custom database path (optional).
+
+    Returns:
+        DiffResult with structured diff.
+    """
+    kwargs = {"db_path": db_path} if db_path else {}
+    tracker = DiffTracker(**kwargs)
+    try:
+        return await tracker.diff(url, before_id, after_id)
+    finally:
+        await tracker.close()
+
+
+async def history(url: str, count: int = 10, *, db_path: str = "") -> list[dict]:
+    """Get snapshot history for a URL.
+
+    Args:
+        url: The URL to get history for.
+        count: Maximum number of snapshots (default: 10).
+        db_path: Custom database path (optional).
+
+    Returns:
+        List of snapshot metadata dicts.
+    """
+    kwargs = {"db_path": db_path} if db_path else {}
+    tracker = DiffTracker(**kwargs)
+    try:
+        return await tracker.history(url, count)
+    finally:
+        await tracker.close()
+
+
+async def untrack(url: str, *, db_path: str = "") -> str:
+    """Remove a URL from tracking.
+
+    Args:
+        url: The URL to untrack.
+        db_path: Custom database path (optional).
+
+    Returns:
+        Status message.
+    """
+    kwargs = {"db_path": db_path} if db_path else {}
+    tracker = DiffTracker(**kwargs)
+    try:
+        return await tracker.untrack(url)
+    finally:
+        await tracker.close()