dead-letter 0.1.0__tar.gz

dead_letter-0.1.0/LICENSE

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

dead_letter-0.1.0/PKG-INFO

@@ -0,0 +1,239 @@
+Metadata-Version: 2.4
+Name: dead-letter
+Version: 0.1.0
+Summary: Convert .eml email exports to Markdown with YAML front matter
+Author: Big Cactus Labs
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/BigCactusLabs/dead-letter
+Project-URL: Repository, https://github.com/BigCactusLabs/dead-letter
+Project-URL: Issues, https://github.com/BigCactusLabs/dead-letter/issues
+Keywords: eml,email,markdown,converter,archive
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Environment :: Web Environment
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Communications :: Email
+Classifier: Topic :: Text Processing :: Markup :: Markdown
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: icalendar>=6.1.1
+Requires-Dist: mail-parser>=4.1.4
+Requires-Dist: mail-parser-reply>=1.35
+Requires-Dist: nh3>=0.2.20
+Requires-Dist: html-to-markdown>=2.9.1
+Requires-Dist: selectolax>=0.3.28
+Requires-Dist: pyyaml>=6.0.2
+Provides-Extra: cli
+Requires-Dist: watchfiles>=1.0.0; extra == "cli"
+Provides-Extra: ui
+Requires-Dist: dead-letter[cli]; extra == "ui"
+Requires-Dist: fastapi>=0.111.0; extra == "ui"
+Requires-Dist: httpx>=0.28.0; extra == "ui"
+Requires-Dist: python-multipart>=0.0.18; extra == "ui"
+Requires-Dist: uvicorn[standard]>=0.30.0; extra == "ui"
+Provides-Extra: dev
+Requires-Dist: dead-letter[ui]; extra == "dev"
+Requires-Dist: anyio>=4.0.0; extra == "dev"
+Requires-Dist: pytest>=9.0.0; extra == "dev"
+Requires-Dist: pytest-cov>=5.0.0; extra == "dev"
+Dynamic: license-file
+
+<p align="center">
+  <img src="docs/brand/production/readme-logo.png" width="128" alt="dead-letter">
+</p>
+
+# dead-letter
+
+[![PyPI](https://img.shields.io/pypi/v/dead-letter)](https://pypi.org/project/dead-letter/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+**Your `.eml` files deserve a second life.**
+
+dead-letter converts email exports into clean Markdown with YAML front matter — threads split, signatures stripped, attachments extracted, calendars parsed. One file or ten thousand.
+
+## ✨ Features
+
+- **Full-fidelity conversion** — HTML sanitization, Gmail/Outlook thread segmentation, inline image handling, and calendar event summaries
+- **CLI** — point it at a file or a directory and go
+- **Local web UI** — dark command-center interface with drag-and-drop import, watch mode, conversion grade badges, processing history, and per-job diagnostics
+- **Inbox/Cabinet workflow** — drop `.eml` files into an Inbox, let dead-letter organize the Markdown bundles into a Cabinet
+- **Install validation** — `dead-letter doctor` checks your runtime environment
+- **Conversion report** — opt-in JSON report with per-file diagnostics for automation and audit
+- **Python API** — `from dead_letter import convert` and you're off
+
+## 🧠 Built for LLM Pipelines
+
+Raw `.eml` files are noisy input for downstream LLM and retrieval pipelines — MIME headers, multipart boundaries, duplicated HTML/plain bodies, and encoded attachments all get mixed into the text path.
+
+dead-letter normalizes that into Markdown with YAML front matter, so message text and metadata are ready for chunking or indexing without MIME parsing or base64 cleanup. Default `convert()` and `convert_dir()` runs write a single `.md` per message and keep attachment names in front matter.
+
+If you want the filesystem artifacts separated too, bundle and Cabinet workflows write `message.md` plus decoded files under `attachments/`. The Markdown is ready for text ingestion, while PDFs, spreadsheets, calendar files, and other binary attachments stay cleanly split out for whatever downstream parser you already use.
+
+## 📦 Install
+
+```bash
+pip install dead-letter            # core + CLI
+pip install dead-letter[cli]       # + watch mode (watchfiles)
+pip install dead-letter[ui]        # + web UI, API server, and watch mode
+```
+
+Or use [pipx](https://pipx.pypa.io/) for an isolated install:
+
+```bash
+pipx install 'dead-letter[ui]'   # installs dead-letter and dead-letter-ui commands
+```
+
+From source:
+
+```bash
+git clone https://github.com/BigCactusLabs/dead-letter.git
+cd dead-letter
+uv sync --extra dev
+```
+
+## 🚀 Quick Start
+
+**CLI** — convert a single file:
+
+```bash
+dead-letter convert message.eml
+```
+
+Convert a whole directory:
+
+```bash
+dead-letter convert inbox/ --output out/
+```
+
+Generate a JSON conversion report alongside the output:
+
+```bash
+dead-letter convert inbox/ --output out/ --report
+```
+
+With `--output`, the report is written to that output directory as
+`.dead-letter-report.json`. Without `--output`, file conversions write the
+report next to the source message and directory conversions write it to the
+input directory root.
+
+Check your runtime environment:
+
+```bash
+dead-letter doctor
+```
+
+Directory conversion scans recursively for `.eml` files, matches the suffix
+case-insensitively, and skips symlinked files whose resolved targets escape the
+requested input tree.
+
+**Web UI** — start the local server:
+
+```bash
+dead-letter-ui --host 127.0.0.1 --port 8765
+```
+
+Open `http://127.0.0.1:8765`, save your Inbox and Cabinet folders in Settings, then import `.eml` files with drag and drop or the file picker. Single-file imports use file mode, while multi-file drops create one directory-mode batch job. Mixed drops ask for confirmation before skipping non-`.eml` files.
+
+From a source checkout, prefix with `uv run`:
+
+```bash
+uv run dead-letter convert message.eml
+uv run dead-letter-ui --host 127.0.0.1 --port 8765
+```
+
+## 🐍 Python API
+
+```python
+from dead_letter import convert
+
+result = convert("message.eml")
+print(result.subject, result.sender)
+print(result.output)  # path to the generated .md
+```
+
+With options:
+
+```python
+from dead_letter import convert, ConvertOptions
+
+result = convert("message.eml", options=ConvertOptions(
+    strip_signatures=True,
+    strip_quoted_headers=True,
+))
+```
+
+Strip signature images (logos, social icons) and tracking pixels:
+
+```python
+result = convert("message.eml", options=ConvertOptions(
+    strip_signature_images=True,
+    strip_tracking_pixels=True,
+))
+```
+
+Bundle conversion (Markdown + attachments + source in one directory):
+
+```python
+from dead_letter import convert_to_bundle
+
+bundle = convert_to_bundle("message.eml", bundle_root="cabinet/")
+print(bundle.markdown)     # cabinet/message/message.md
+print(bundle.attachments)  # [cabinet/message/attachments/logo.png, ...]
+```
+
+Extracted attachment filenames are normalized to safe basenames before they are
+written under `attachments/`.
+
+Batch:
+
+```python
+from dead_letter import convert_dir
+
+for r in convert_dir("inbox/", output="out/"):
+    print(f"{'✓' if r.success else '✗'} {r.source.name}")
+```
+
+## 🗂 Project Structure
+
+```
+src/dead_letter/
+├── core/           # conversion pipeline (MIME, HTML, threads, rendering)
+├── backend/        # CLI, API server, job runner, watch mode
+└── frontend/       # static web UI (htmx + Alpine.js)
+tests/
+├── core/           # conversion pipeline tests with .eml fixtures
+├── backend/        # API, job, and watch tests
+└── frontend/       # JS unit tests
+```
+
+## 🧪 Testing
+
+```bash
+uv run pytest tests/core           # conversion pipeline
+uv run pytest tests/backend        # API and job runner
+node --test tests/frontend/*.test.js     # frontend
+```
+
+CI runs all three on every push and PR.
+
+## 📚 Docs
+
+- [Docs Index](docs/README.md) — public docs landing page
+- [Runtime Contracts](docs/reference/v4-runtime-contracts.md) — full API and core behavior spec
+- [Frontend State Model](docs/reference/frontend-state-model.md)
+- [Quality Diagnostics](docs/reference/quality-diagnostics.md)
+- [Brand & Style Guide](docs/brand/style-guide.md)
+- [Changelog](CHANGELOG.md)
+- [Contributing](CONTRIBUTING.md)
+
+## ⚠️ Known Limitations (v0.1)
+
+- Local-only — no remote server, no auth
+- In-memory job registry (state resets on restart)
+- Single-user, single-machine
+
+## License
+
+[MIT](LICENSE)

dead_letter-0.1.0/README.md

@@ -0,0 +1,197 @@
+<p align="center">
+  <img src="docs/brand/production/readme-logo.png" width="128" alt="dead-letter">
+</p>
+
+# dead-letter
+
+[![PyPI](https://img.shields.io/pypi/v/dead-letter)](https://pypi.org/project/dead-letter/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+**Your `.eml` files deserve a second life.**
+
+dead-letter converts email exports into clean Markdown with YAML front matter — threads split, signatures stripped, attachments extracted, calendars parsed. One file or ten thousand.
+
+## ✨ Features
+
+- **Full-fidelity conversion** — HTML sanitization, Gmail/Outlook thread segmentation, inline image handling, and calendar event summaries
+- **CLI** — point it at a file or a directory and go
+- **Local web UI** — dark command-center interface with drag-and-drop import, watch mode, conversion grade badges, processing history, and per-job diagnostics
+- **Inbox/Cabinet workflow** — drop `.eml` files into an Inbox, let dead-letter organize the Markdown bundles into a Cabinet
+- **Install validation** — `dead-letter doctor` checks your runtime environment
+- **Conversion report** — opt-in JSON report with per-file diagnostics for automation and audit
+- **Python API** — `from dead_letter import convert` and you're off
+
+## 🧠 Built for LLM Pipelines
+
+Raw `.eml` files are noisy input for downstream LLM and retrieval pipelines — MIME headers, multipart boundaries, duplicated HTML/plain bodies, and encoded attachments all get mixed into the text path.
+
+dead-letter normalizes that into Markdown with YAML front matter, so message text and metadata are ready for chunking or indexing without MIME parsing or base64 cleanup. Default `convert()` and `convert_dir()` runs write a single `.md` per message and keep attachment names in front matter.
+
+If you want the filesystem artifacts separated too, bundle and Cabinet workflows write `message.md` plus decoded files under `attachments/`. The Markdown is ready for text ingestion, while PDFs, spreadsheets, calendar files, and other binary attachments stay cleanly split out for whatever downstream parser you already use.
+
+## 📦 Install
+
+```bash
+pip install dead-letter            # core + CLI
+pip install dead-letter[cli]       # + watch mode (watchfiles)
+pip install dead-letter[ui]        # + web UI, API server, and watch mode
+```
+
+Or use [pipx](https://pipx.pypa.io/) for an isolated install:
+
+```bash
+pipx install 'dead-letter[ui]'   # installs dead-letter and dead-letter-ui commands
+```
+
+From source:
+
+```bash
+git clone https://github.com/BigCactusLabs/dead-letter.git
+cd dead-letter
+uv sync --extra dev
+```
+
+## 🚀 Quick Start
+
+**CLI** — convert a single file:
+
+```bash
+dead-letter convert message.eml
+```
+
+Convert a whole directory:
+
+```bash
+dead-letter convert inbox/ --output out/
+```
+
+Generate a JSON conversion report alongside the output:
+
+```bash
+dead-letter convert inbox/ --output out/ --report
+```
+
+With `--output`, the report is written to that output directory as
+`.dead-letter-report.json`. Without `--output`, file conversions write the
+report next to the source message and directory conversions write it to the
+input directory root.
+
+Check your runtime environment:
+
+```bash
+dead-letter doctor
+```
+
+Directory conversion scans recursively for `.eml` files, matches the suffix
+case-insensitively, and skips symlinked files whose resolved targets escape the
+requested input tree.
+
+**Web UI** — start the local server:
+
+```bash
+dead-letter-ui --host 127.0.0.1 --port 8765
+```
+
+Open `http://127.0.0.1:8765`, save your Inbox and Cabinet folders in Settings, then import `.eml` files with drag and drop or the file picker. Single-file imports use file mode, while multi-file drops create one directory-mode batch job. Mixed drops ask for confirmation before skipping non-`.eml` files.
+
+From a source checkout, prefix with `uv run`:
+
+```bash
+uv run dead-letter convert message.eml
+uv run dead-letter-ui --host 127.0.0.1 --port 8765
+```
+
+## 🐍 Python API
+
+```python
+from dead_letter import convert
+
+result = convert("message.eml")
+print(result.subject, result.sender)
+print(result.output)  # path to the generated .md
+```
+
+With options:
+
+```python
+from dead_letter import convert, ConvertOptions
+
+result = convert("message.eml", options=ConvertOptions(
+    strip_signatures=True,
+    strip_quoted_headers=True,
+))
+```
+
+Strip signature images (logos, social icons) and tracking pixels:
+
+```python
+result = convert("message.eml", options=ConvertOptions(
+    strip_signature_images=True,
+    strip_tracking_pixels=True,
+))
+```
+
+Bundle conversion (Markdown + attachments + source in one directory):
+
+```python
+from dead_letter import convert_to_bundle
+
+bundle = convert_to_bundle("message.eml", bundle_root="cabinet/")
+print(bundle.markdown)     # cabinet/message/message.md
+print(bundle.attachments)  # [cabinet/message/attachments/logo.png, ...]
+```
+
+Extracted attachment filenames are normalized to safe basenames before they are
+written under `attachments/`.
+
+Batch:
+
+```python
+from dead_letter import convert_dir
+
+for r in convert_dir("inbox/", output="out/"):
+    print(f"{'✓' if r.success else '✗'} {r.source.name}")
+```
+
+## 🗂 Project Structure
+
+```
+src/dead_letter/
+├── core/           # conversion pipeline (MIME, HTML, threads, rendering)
+├── backend/        # CLI, API server, job runner, watch mode
+└── frontend/       # static web UI (htmx + Alpine.js)
+tests/
+├── core/           # conversion pipeline tests with .eml fixtures
+├── backend/        # API, job, and watch tests
+└── frontend/       # JS unit tests
+```
+
+## 🧪 Testing
+
+```bash
+uv run pytest tests/core           # conversion pipeline
+uv run pytest tests/backend        # API and job runner
+node --test tests/frontend/*.test.js     # frontend
+```
+
+CI runs all three on every push and PR.
+
+## 📚 Docs
+
+- [Docs Index](docs/README.md) — public docs landing page
+- [Runtime Contracts](docs/reference/v4-runtime-contracts.md) — full API and core behavior spec
+- [Frontend State Model](docs/reference/frontend-state-model.md)
+- [Quality Diagnostics](docs/reference/quality-diagnostics.md)
+- [Brand & Style Guide](docs/brand/style-guide.md)
+- [Changelog](CHANGELOG.md)
+- [Contributing](CONTRIBUTING.md)
+
+## ⚠️ Known Limitations (v0.1)
+
+- Local-only — no remote server, no auth
+- In-memory job registry (state resets on restart)
+- Single-user, single-machine
+
+## License
+
+[MIT](LICENSE)

dead_letter-0.1.0/pyproject.toml

@@ -0,0 +1,68 @@
+[build-system]
+requires = ["setuptools>=69", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "dead-letter"
+version = "0.1.0"
+description = "Convert .eml email exports to Markdown with YAML front matter"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.12"
+authors = [{ name = "Big Cactus Labs" }]
+keywords = ["eml", "email", "markdown", "converter", "archive"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Environment :: Console",
+  "Environment :: Web Environment",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3.12",
+  "Topic :: Communications :: Email",
+  "Topic :: Text Processing :: Markup :: Markdown",
+]
+dependencies = [
+  "icalendar>=6.1.1",
+  "mail-parser>=4.1.4",
+  "mail-parser-reply>=1.35",
+  "nh3>=0.2.20",
+  "html-to-markdown>=2.9.1",
+  "selectolax>=0.3.28",
+  "pyyaml>=6.0.2",
+]
+
+[project.optional-dependencies]
+cli = ["watchfiles>=1.0.0"]
+ui = [
+  "dead-letter[cli]",
+  "fastapi>=0.111.0",
+  "httpx>=0.28.0",
+  "python-multipart>=0.0.18",
+  "uvicorn[standard]>=0.30.0",
+]
+dev = [
+  "dead-letter[ui]",
+  "anyio>=4.0.0",
+  "pytest>=9.0.0",
+  "pytest-cov>=5.0.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/BigCactusLabs/dead-letter"
+Repository = "https://github.com/BigCactusLabs/dead-letter"
+Issues = "https://github.com/BigCactusLabs/dead-letter/issues"
+
+[project.scripts]
+dead-letter = "dead_letter.backend.cli:main"
+dead-letter-ui = "dead_letter.backend.ui_server:main"
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+"dead_letter" = ["frontend/**/*"]
+
+[tool.pytest.ini_options]
+addopts = "--import-mode=importlib"

dead_letter-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

dead_letter-0.1.0/src/dead_letter/__init__.py

@@ -0,0 +1,21 @@
+"""dead-letter: Convert .eml email exports to Markdown with YAML front matter."""
+
+from dead_letter.core import (
+    BundleResult,
+    ConvertOptions,
+    ConvertResult,
+    convert,
+    convert_dir,
+    convert_to_bundle,
+)
+
+__all__ = [
+    "__version__",
+    "BundleResult",
+    "ConvertOptions",
+    "ConvertResult",
+    "convert",
+    "convert_dir",
+    "convert_to_bundle",
+]
+__version__ = "0.1.0"

dead_letter-0.1.0/src/dead_letter/backend/__init__.py

@@ -0,0 +1 @@
+"""Backend package for dead-letter CLI and API."""