Metadata-Version: 2.4
Name: perusal
Version: 0.0.5
Summary: Read the web as Markdown: a CLI, a reader-browser GUI, and an optional MCP server, on the domonic Readability + Turndown ports
Author-email: byteface <byteface@googlemail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/byteface/domonic-libs/tree/master/src/perusal
Project-URL: Source, https://github.com/byteface/domonic-libs
Project-URL: Documentation, https://github.com/byteface/domonic-libs/blob/master/docs/perusal.md
Project-URL: Tracker, https://github.com/byteface/domonic-libs/issues
Keywords: readability,turndown,markdown,reader,browser,web,domonic,mcp
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
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 :: Internet :: WWW/HTTP
Classifier: Topic :: Text Processing :: Markup :: HTML
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: domonic-libs>=0.0.5
Provides-Extra: mcp
Requires-Dist: mcp<2,>=1.12; extra == "mcp"
Provides-Extra: browser
Requires-Dist: pywebview>=5.0; extra == "browser"
Provides-Extra: js
Requires-Dist: myjs>=0.0.5; extra == "js"
Dynamic: license-file

# perusal

The internet without all the 💩

```bash
pip install perusal

perusal https://en.wikipedia.org/wiki/Domino    # -> clean Markdown on stdout
perusal ./saved-page.html                        # a local HTML file works too
perusal report https://example.com               # HTML-vs-Markdown size / token savings
perusal url1 url2 url3                           # -> one combined Markdown digest
echo '<h1>hi</h1>' | perusal -                   # read HTML from stdin
```

Pages pass through the domonic Readability and Turndown ports: fetch →
readable-article extraction → Markdown → cleanup, with optional relevance
ranking (`--query`) and a hard character budget (`--max-chars`).

Pages that render client-side (an empty server response, "Enable JavaScript
to view this content") need their own JavaScript actually run first:

```bash
pip install 'perusal[js]'
perusal https://example.com/app --js             # runs the page's <script>s via myjs first
```

## The reader-browser

```bash
pip install 'perusal[browser]'
perusal browse                                   # tabbed webview reader
perusal browse https://en.wikipedia.org/wiki/Domino
```

A small tabbed reader-browser (history, incognito tabs, bookmarks, DevTools,
adjustable type, Wikipedia math rendering, "save page as Markdown") with
keyboard shortcuts: `⌘/Ctrl+T` new tab, `W` close tab, `R` reload, `D`
bookmark, `B` toggle bookmarks, `U` view page source, `L` focus the URL bar.

**DevTools** (the `</>` button): raw page **Source**, a static **Resources**
inventory (every referenced script/stylesheet/image/iframe, each viewable in
turn), and an **Info** tab with IP / reverse DNS / WHOIS / DNS records
(hand-rolled clients, no new dependency) plus certificate-transparency-log
subdomain discovery via crt.sh. Purely passive and manually triggered — no
port scanning, no active brute-forcing, nothing sent to the site itself
beyond the page fetch perusal already made.

## MCP server (optional)

```bash
pip install 'perusal[mcp]'
perusal mcp                                       # stdio MCP server
```

One read-only, idempotent tool — `web_read(url, query?, max_chars?, timeout?)` —
built on the official Python MCP SDK. Point an MCP client at `perusal mcp`.

See the [full documentation](https://github.com/byteface/domonic-libs/blob/master/docs/perusal.md).
