md2plain 0.1.0__tar.gz

md2plain-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,30 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  test:
+    name: ${{ matrix.os }} / Python ${{ matrix.python-version }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+        python-version: ["3.10", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install -e ".[dev]"
+      - name: Test
+        run: python -m unittest discover -s tests -v
+      - name: Lint
+        run: |
+          ruff check src tests
+          black --check src tests

md2plain-0.1.0/.gitignore

@@ -0,0 +1,16 @@
+# Python
+*.egg-info/
+build/
+dist/
+__pycache__/
+*.py[cod]
+.venv/
+.ruff_cache/
+
+# macOS
+.DS_Store
+
+# Local test letters
+test.md
+test2.md
+test3.md

md2plain-0.1.0/CHANGELOG.md

@@ -0,0 +1,18 @@
+# Changelog
+
+All notable changes to this project are documented here. The format is based
+on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project
+follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2026-10-18
+
+### Added
+
+- Markdown to plain-text email rendering: `=` / `-` / `~` headings, `*` lists,
+  `>` quotes, four-space code blocks, and 75-column hard wrapping with CJK
+  width support.
+- Clipboard output as `text/plain` only, for Gmail's Plain text mode.
+- CLI options: `--width`, `--watch`, `--print`, `-o/--output`,
+  `--soft-breaks`, and `--version`.
+- Test suite covering the renderer, CLI, clipboard, edge cases, fuzzing, and
+  performance.

md2plain-0.1.0/LICENSE

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

md2plain-0.1.0/PKG-INFO

@@ -0,0 +1,201 @@
+Metadata-Version: 2.5
+Name: md2plain
+Version: 0.1.0
+Summary: Convert Markdown to plain-text email for Gmail's Plain text mode.
+Project-URL: Homepage, https://github.com/hoshF/md2plain
+Project-URL: Issues, https://github.com/hoshF/md2plain/issues
+Author-email: hoshF <noveor.ol@gmail.com>
+License: MIT License
+        
+        Copyright (c) 2026 hoshF
+        
+        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.
+License-File: LICENSE
+Keywords: cli,email,gmail,markdown,plain-text
+Classifier: Environment :: Console
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: MacOS
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Communications :: Email
+Classifier: Topic :: Text Processing :: Markup
+Requires-Python: >=3.10
+Requires-Dist: linkify-it-py>=2.0
+Requires-Dist: markdown-it-py>=3.0
+Requires-Dist: pyobjc-framework-cocoa>=10.0; sys_platform == 'darwin'
+Provides-Extra: dev
+Requires-Dist: black>=24; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# md2plain
+
+[![CI](https://github.com/hoshF/md2plain/actions/workflows/ci.yml/badge.svg)](https://github.com/hoshF/md2plain/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue)](pyproject.toml)
+[![Platform: macOS](https://img.shields.io/badge/platform-macOS-lightgrey)](pyproject.toml)
+
+**Markdown in, plain-text email out.**
+
+`md2plain` renders Markdown as a plain-text email and copies it to the macOS
+clipboard as `text/plain`. Paste it into Gmail's **Plain text mode** and the
+message is sent as a real `text/plain` message: hard-wrapped, with no HTML,
+no fonts, and no client-side reflow.
+
+## Demo
+
+Input:
+
+```markdown
+# Quarterly Update
+
+This is a **short** note with a [link](https://example.com).
+
+* one
+* two
+
+> quoted
+```
+
+Output:
+
+```text
+Quarterly Update
+================
+
+This is a short note with a link (https://example.com).
+
+* one
+* two
+
+> quoted
+```
+
+## Why
+
+- Gmail's normal compose always sends HTML, even when you paste plain text.
+- Rich text copied from Typora carries its own CSS, which mail clients mangle.
+- Plain text has no automatic reflow, so the sender has to control line width.
+- A 75-column limit leaves room for `> ` quote prefixes and stays within
+  RFC 5322's recommended 78 characters.
+
+## Requirements
+
+- macOS (the clipboard is written through AppKit)
+- Python 3.10 or newer
+
+## Install
+
+With [pipx](https://pipx.pypa.io/):
+
+```bash
+pipx install .
+```
+
+Or from a checkout, in a virtual environment:
+
+```bash
+python3 -m venv .venv
+.venv/bin/pip install -e .
+```
+
+## Usage
+
+```bash
+md2plain note.md
+```
+
+Then in Gmail: open the compose window, click the three-dot menu, choose
+**Plain text mode**, and press `Cmd+V`.
+
+To verify, send a message to yourself and use **Show original**. The message
+should contain only:
+
+```text
+Content-Type: text/plain; charset="UTF-8"
+```
+
+No `multipart/alternative`, no `text/html`.
+
+## Options
+
+| Option | Description |
+|---|---|
+| `--width N` | Line width in columns (default: 75) |
+| `--watch` | Update the clipboard whenever the file is saved |
+| `--print` | Write to stdout instead of the clipboard |
+| `-o, --output FILE` | Also write the plain text to a file |
+| `--soft-breaks` | Treat single newlines as spaces |
+| `--version` | Print the version and exit |
+
+## Output format
+
+| Markdown | Output |
+|---|---|
+| `# Heading` | heading + `====` underline |
+| `## Heading` | heading + `----` underline |
+| `### Heading` | heading + `~~~~` underline |
+| Paragraph | hard-wrapped at 75 columns (CJK counts as two) |
+| `- item` | `* item`, with hanging indent |
+| `1. item` | `1. item` |
+| `> quote` | `> quote` |
+| Code block | indented by four spaces |
+| `[text](url)` | `text (url)` |
+| Table | column-aligned plain text |
+| Single newline | kept (signatures and dates stay on their own lines) |
+
+## How it works
+
+1. `markdown-it-py` parses CommonMark plus tables, strikethrough, and
+   autolinks.
+2. `src/md2plain/render.py` wraps text by display width (CJK counts as two
+   columns), renders headings, lists, quotes, and tables.
+3. `src/md2plain/cli.py` reads UTF-8 (BOM tolerant) and writes exactly one
+   clipboard type: `text/plain`.
+
+## Limitations
+
+- macOS only; the clipboard backend is AppKit.
+- Plain text has no bold, italics, or clickable links. Link URLs are kept as
+  text, and links inside headings or table cells lose the URL.
+- Images become alt text. YAML front matter, footnotes, math, and Mermaid
+  diagrams are not converted.
+- Tables are aligned with spaces, so proportional fonts break the alignment.
+- Gmail may collapse `>` quote blocks behind a three-dot control; this is
+  display only and the content stays intact.
+
+## Development
+
+```bash
+python3 -m venv .venv
+.venv/bin/pip install -e ".[dev]"
+.venv/bin/python -m unittest discover -s tests -v
+.venv/bin/ruff check src tests
+.venv/bin/black --check src tests
+```
+
+The `./md2plain` script in the repository root is a development launcher; it
+runs the package from `.venv`. Installed users get the `md2plain` command from
+`pyproject.toml`.
+
+## License
+
+[MIT](LICENSE). See [CHANGELOG.md](CHANGELOG.md) for release history.

md2plain-0.1.0/README.md

@@ -0,0 +1,153 @@
+# md2plain
+
+[![CI](https://github.com/hoshF/md2plain/actions/workflows/ci.yml/badge.svg)](https://github.com/hoshF/md2plain/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue)](pyproject.toml)
+[![Platform: macOS](https://img.shields.io/badge/platform-macOS-lightgrey)](pyproject.toml)
+
+**Markdown in, plain-text email out.**
+
+`md2plain` renders Markdown as a plain-text email and copies it to the macOS
+clipboard as `text/plain`. Paste it into Gmail's **Plain text mode** and the
+message is sent as a real `text/plain` message: hard-wrapped, with no HTML,
+no fonts, and no client-side reflow.
+
+## Demo
+
+Input:
+
+```markdown
+# Quarterly Update
+
+This is a **short** note with a [link](https://example.com).
+
+* one
+* two
+
+> quoted
+```
+
+Output:
+
+```text
+Quarterly Update
+================
+
+This is a short note with a link (https://example.com).
+
+* one
+* two
+
+> quoted
+```
+
+## Why
+
+- Gmail's normal compose always sends HTML, even when you paste plain text.
+- Rich text copied from Typora carries its own CSS, which mail clients mangle.
+- Plain text has no automatic reflow, so the sender has to control line width.
+- A 75-column limit leaves room for `> ` quote prefixes and stays within
+  RFC 5322's recommended 78 characters.
+
+## Requirements
+
+- macOS (the clipboard is written through AppKit)
+- Python 3.10 or newer
+
+## Install
+
+With [pipx](https://pipx.pypa.io/):
+
+```bash
+pipx install .
+```
+
+Or from a checkout, in a virtual environment:
+
+```bash
+python3 -m venv .venv
+.venv/bin/pip install -e .
+```
+
+## Usage
+
+```bash
+md2plain note.md
+```
+
+Then in Gmail: open the compose window, click the three-dot menu, choose
+**Plain text mode**, and press `Cmd+V`.
+
+To verify, send a message to yourself and use **Show original**. The message
+should contain only:
+
+```text
+Content-Type: text/plain; charset="UTF-8"
+```
+
+No `multipart/alternative`, no `text/html`.
+
+## Options
+
+| Option | Description |
+|---|---|
+| `--width N` | Line width in columns (default: 75) |
+| `--watch` | Update the clipboard whenever the file is saved |
+| `--print` | Write to stdout instead of the clipboard |
+| `-o, --output FILE` | Also write the plain text to a file |
+| `--soft-breaks` | Treat single newlines as spaces |
+| `--version` | Print the version and exit |
+
+## Output format
+
+| Markdown | Output |
+|---|---|
+| `# Heading` | heading + `====` underline |
+| `## Heading` | heading + `----` underline |
+| `### Heading` | heading + `~~~~` underline |
+| Paragraph | hard-wrapped at 75 columns (CJK counts as two) |
+| `- item` | `* item`, with hanging indent |
+| `1. item` | `1. item` |
+| `> quote` | `> quote` |
+| Code block | indented by four spaces |
+| `[text](url)` | `text (url)` |
+| Table | column-aligned plain text |
+| Single newline | kept (signatures and dates stay on their own lines) |
+
+## How it works
+
+1. `markdown-it-py` parses CommonMark plus tables, strikethrough, and
+   autolinks.
+2. `src/md2plain/render.py` wraps text by display width (CJK counts as two
+   columns), renders headings, lists, quotes, and tables.
+3. `src/md2plain/cli.py` reads UTF-8 (BOM tolerant) and writes exactly one
+   clipboard type: `text/plain`.
+
+## Limitations
+
+- macOS only; the clipboard backend is AppKit.
+- Plain text has no bold, italics, or clickable links. Link URLs are kept as
+  text, and links inside headings or table cells lose the URL.
+- Images become alt text. YAML front matter, footnotes, math, and Mermaid
+  diagrams are not converted.
+- Tables are aligned with spaces, so proportional fonts break the alignment.
+- Gmail may collapse `>` quote blocks behind a three-dot control; this is
+  display only and the content stays intact.
+
+## Development
+
+```bash
+python3 -m venv .venv
+.venv/bin/pip install -e ".[dev]"
+.venv/bin/python -m unittest discover -s tests -v
+.venv/bin/ruff check src tests
+.venv/bin/black --check src tests
+```
+
+The `./md2plain` script in the repository root is a development launcher; it
+runs the package from `.venv`. Installed users get the `md2plain` command from
+`pyproject.toml`.
+
+## License
+
+[MIT](LICENSE). See [CHANGELOG.md](CHANGELOG.md) for release history.

md2plain-0.1.0/md2plain

@@ -0,0 +1,8 @@
+#!/bin/sh
+# Development launcher. Install with `pipx install .` for the real command.
+DIR=$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)
+if [ ! -x "$DIR/.venv/bin/python" ]; then
+  echo "Missing .venv. Run: python3 -m venv .venv && .venv/bin/pip install -e ." >&2
+  exit 1
+fi
+exec "$DIR/.venv/bin/python" -m md2plain "$@"

md2plain-0.1.0/pyproject.toml

@@ -0,0 +1,51 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "md2plain"
+dynamic = ["version"]
+description = "Convert Markdown to plain-text email for Gmail's Plain text mode."
+readme = "README.md"
+license = { file = "LICENSE" }
+requires-python = ">=3.10"
+authors = [{ name = "hoshF", email = "noveor.ol@gmail.com" }]
+keywords = ["markdown", "plain-text", "email", "gmail", "cli"]
+classifiers = [
+  "Environment :: Console",
+  "License :: OSI Approved :: MIT License",
+  "Operating System :: MacOS",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Topic :: Communications :: Email",
+  "Topic :: Text Processing :: Markup",
+]
+dependencies = [
+  "markdown-it-py>=3.0",
+  "linkify-it-py>=2.0",
+  "pyobjc-framework-Cocoa>=10.0; sys_platform == 'darwin'",
+]
+
+[project.optional-dependencies]
+dev = ["black>=24", "ruff>=0.6"]
+
+[project.scripts]
+md2plain = "md2plain.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/hoshF/md2plain"
+Issues = "https://github.com/hoshF/md2plain/issues"
+
+[tool.hatch.version]
+path = "src/md2plain/__init__.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/md2plain"]
+
+[tool.black]
+line-length = 88
+
+[tool.ruff]
+line-length = 88

md2plain-0.1.0/src/md2plain/__init__.py

@@ -0,0 +1,3 @@
+"""Convert Markdown into plain-text email."""
+
+__version__ = "0.1.0"

md2plain-0.1.0/src/md2plain/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+raise SystemExit(main())

md2plain-0.1.0/src/md2plain/cli.py

@@ -0,0 +1,143 @@
+#!/usr/bin/env python3
+"""Convert Markdown to a plain-text email and copy it to the macOS clipboard.
+
+Only text/plain is placed on the clipboard, so pasting into Gmail's
+"Plain text mode" produces a real text/plain message.
+
+Usage:
+    md2plain note.md
+    md2plain note.md --width 72
+    md2plain note.md --watch
+    md2plain note.md --print
+    md2plain note.md -o out.txt
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+import time
+from pathlib import Path
+
+from . import __version__
+from .render import render_plain
+
+
+def positive_width(value: str) -> int:
+    width = int(value)
+    if width < 1:
+        raise argparse.ArgumentTypeError("width must be at least 1")
+    return width
+
+
+def read_input(path: str) -> str:
+    if path == "-":
+        return sys.stdin.read()
+    try:
+        return Path(path).read_text(encoding="utf-8-sig", errors="replace")
+    except FileNotFoundError:
+        sys.exit(f"File not found: {path}")
+    except OSError as exc:
+        sys.exit(f"Cannot read {path}: {exc}")
+
+
+def copy_text(text: str) -> None:
+    """Write plain text only, so Gmail's plain-text mode gets it verbatim."""
+    from AppKit import NSPasteboard, NSPasteboardTypeString
+
+    name = os.environ.get("MD2PLAIN_PASTEBOARD", "general")
+    board = (
+        NSPasteboard.generalPasteboard()
+        if name == "general"
+        else NSPasteboard.pasteboardWithName_(name)
+    )
+    board.clearContents()
+    board.declareTypes_owner_([NSPasteboardTypeString], None)
+    board.setString_forType_(text, NSPasteboardTypeString)
+
+
+def finish(text: str, args: argparse.Namespace) -> None:
+    if args.output:
+        Path(args.output).write_text(text, encoding="utf-8")
+    if args.show:
+        sys.stdout.write(text)
+    if args.no_copy:
+        return
+
+    try:
+        copy_text(text)
+    except ImportError:
+        sys.exit("pyobjc is not installed; use --print or -o instead")
+
+    print(
+        f"Copied {len(text.splitlines())} lines / {len(text)} chars of plain text. "
+        "Enable Gmail's Plain text mode, then press Cmd+V.",
+        file=sys.stderr,
+    )
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(
+        prog="md2plain",
+        description="Convert Markdown to plain-text email and copy it to the clipboard.",
+    )
+    parser.add_argument(
+        "--version", action="version", version=f"%(prog)s {__version__}"
+    )
+    parser.add_argument("input", help="Markdown file, or - for stdin")
+    parser.add_argument("-o", "--output", help="also write the plain text to a file")
+    parser.add_argument(
+        "--print", dest="show", action="store_true", help="write to stdout"
+    )
+    parser.add_argument(
+        "--no-copy", action="store_true", help="do not touch the clipboard"
+    )
+    parser.add_argument(
+        "--watch", action="store_true", help="update the clipboard on save"
+    )
+    parser.add_argument(
+        "--width", type=positive_width, default=75, help="line width (default: 75)"
+    )
+    parser.add_argument(
+        "--soft-breaks",
+        action="store_true",
+        help="treat a single newline as a space (default: keep line breaks)",
+    )
+    args = parser.parse_args()
+
+    if args.watch and args.input == "-":
+        parser.error("--watch requires a file, not stdin")
+
+    text = read_input(args.input)
+    if not text.strip():
+        sys.exit("Input is empty.")
+
+    preserve_breaks = not args.soft_breaks
+
+    def convert(src: str) -> None:
+        finish(render_plain(src, args.width, preserve_breaks), args)
+
+    if not args.watch:
+        convert(text)
+        return 0
+
+    last_mtime: float | None = None
+    try:
+        while True:
+            try:
+                mtime = os.stat(args.input).st_mtime
+            except FileNotFoundError:
+                time.sleep(1)
+                continue
+            if mtime != last_mtime:
+                convert(read_input(args.input))
+                last_mtime = mtime
+            time.sleep(1)
+    except KeyboardInterrupt:
+        print("\nStopped watching.", file=sys.stderr)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

md2plain-0.1.0/src/md2plain/render.py

@@ -0,0 +1,280 @@
+"""Render Markdown as plain-text email in reStructuredText style.
+
+Headings use = / - / ~ underlines, paragraphs are hard-wrapped at 75
+columns (CJK counts as two), lists use "*", quotes use ">", and code is
+indented by four spaces.
+"""
+
+from __future__ import annotations
+
+import re
+import unicodedata
+
+from markdown_it import MarkdownIt
+from markdown_it.tree import SyntaxTreeNode
+
+UNDERLINE = {1: "=", 2: "-", 3: "~", 4: "^", 5: '"', 6: "'"}
+QUOTE = ">"
+
+# Punctuation that must not start a line (CJK line-breaking rule).
+NO_LINE_START = set("。，、；：！？）〕］｝》」』】’”…·%,.;:!?)]}'\"")
+# Link schemes that are safe to keep.
+SAFE_LINK = re.compile(r"^(https?://|mailto:|#)", re.IGNORECASE)
+
+
+def char_width(ch: str) -> int:
+    """Display width of one character: 2 for wide (CJK) characters."""
+    return 2 if unicodedata.east_asian_width(ch) in "WF" else 1
+
+
+def disp_width(text: str) -> int:
+    return sum(char_width(c) for c in text)
+
+
+# --------------------------------------------------------------------- inline
+
+
+def inline_text(node: SyntaxTreeNode, with_urls: bool = True) -> str:
+    """Flatten an inline node to text; links become "label (url)"."""
+    kind = node.type
+
+    if kind in ("text", "code_inline"):
+        return node.content
+    if kind == "softbreak":
+        return " "
+    if kind == "hardbreak":
+        return "\n"
+    if kind == "image":
+        return node.content or (node.attrs.get("src") or "")
+    if kind == "html_inline":
+        return ""
+    if kind == "link":
+        label = "".join(inline_text(c, False) for c in node.children)
+        href = node.attrs.get("href") or ""
+        if not with_urls or not href or not SAFE_LINK.match(href):
+            return label
+        # Do not repeat a bare address: mailto:a@b.com with label a@b.com.
+        if href.lower().startswith("mailto:") and href[7:] == label:
+            return label
+        # A URL used as its own label needs no "(url)" suffix, even when the
+        # target only differs by tracking parameters.
+        if label.startswith(("http://", "https://")):
+            base = href.split("?", 1)[0].split("#", 1)[0].rstrip("/")
+            if base == label.rstrip("/"):
+                return label
+        if href != label:
+            return f"{label} ({href})"
+        return label
+
+    return "".join(inline_text(c, with_urls) for c in node.children)
+
+
+def plain_of(node: SyntaxTreeNode) -> str:
+    return inline_text(node, with_urls=False)
+
+
+# ----------------------------------------------------------------------- wrap
+
+
+def wrap_line(line: str, width: int) -> list[str]:
+    """Wrap one line at spaces, breaking CJK text between characters."""
+    line = re.sub(r"[ \t]+", " ", line).strip()
+    if not line:
+        return [""]
+
+    out: list[str] = []
+    current: list[str] = []
+    current_width = 0
+    last_space = -1
+
+    for ch in line:
+        w = char_width(ch)
+        if current and current_width + w > width:
+            if ch in NO_LINE_START:
+                current.append(ch)
+                current_width += w
+                continue
+
+            if last_space > 0:
+                out.append("".join(current[:last_space]).rstrip())
+                current = current[last_space + 1 :]
+            else:
+                out.append("".join(current).rstrip())
+                current = []
+
+            current_width = sum(char_width(c) for c in current)
+            last_space = -1
+            for i, c in enumerate(current):
+                if c == " ":
+                    last_space = i
+
+        current.append(ch)
+        current_width += w
+        if ch == " ":
+            last_space = len(current) - 1
+
+    if current:
+        out.append("".join(current).rstrip())
+    # Very small widths can produce blank lines; keep the result non-empty.
+    return [line for line in out if line] or [""]
+
+
+def wrap_text(text: str, width: int) -> list[str]:
+    lines: list[str] = []
+    for part in text.split("\n"):
+        lines.extend(wrap_line(part, width))
+    return lines
+
+
+# --------------------------------------------------------------------- blocks
+
+
+def render_blocks(nodes: list[SyntaxTreeNode], width: int) -> list[str]:
+    out: list[str] = []
+
+    for node in nodes:
+        kind = node.type
+
+        if kind == "heading":
+            level = int(node.tag[1])
+            text = plain_of(node.children[0]).strip()
+            if not text:
+                continue
+            mark = UNDERLINE.get(level, "-")
+            out += [text, mark * max(disp_width(text), 3), ""]
+
+        elif kind == "paragraph":
+            out += wrap_text(inline_text(node.children[0]), width)
+            out.append("")
+
+        elif kind in ("bullet_list", "ordered_list"):
+            out += render_list(node, width)
+
+        elif kind == "blockquote":
+            body = render_blocks(node.children, width - 2)
+            while body and not body[-1]:
+                body.pop()
+            out += [QUOTE if not line else f"{QUOTE} {line}" for line in body]
+            out.append("")
+
+        elif kind in ("fence", "code_block"):
+            code = (node.content or "").rstrip("\n").split("\n")
+            out += ["    " + line for line in code]
+            out.append("")
+
+        elif kind == "hr":
+            out += ["-" * min(width, 72), ""]
+
+        elif kind == "table":
+            out += render_table(node, width)
+            out.append("")
+
+        elif kind == "html_block":
+            continue
+
+        elif node.children:
+            out += render_blocks(node.children, width)
+
+    return out
+
+
+def render_list(node: SyntaxTreeNode, width: int) -> list[str]:
+    ordered = node.type == "ordered_list"
+    start = int(node.attrs.get("start", 1)) if ordered else None
+    out: list[str] = []
+
+    for i, item in enumerate(node.children):
+        marker = f"{start + i}. " if start is not None else "* "
+        body = render_blocks(item.children, width - len(marker))
+        while body and not body[-1]:
+            body.pop()
+
+        # Keep nested lists tight: drop the blank line before them.
+        tight: list[str] = []
+        for k, line in enumerate(body):
+            if not line:
+                nxt = k + 1
+                while nxt < len(body) and not body[nxt]:
+                    nxt += 1
+                if nxt < len(body) and re.match(r"^(\* |\d+\. )", body[nxt]):
+                    continue
+            tight.append(line)
+
+        for j, line in enumerate(tight):
+            out.append((marker if j == 0 else " " * len(marker)) + line)
+
+    out.append("")
+    return out
+
+
+def render_table(node: SyntaxTreeNode, width: int) -> list[str]:
+    rows: list[list[str]] = []
+    for section in node.children:
+        for tr in section.children:
+            cells = [
+                "".join(plain_of(c) for c in cell.children).strip()
+                for cell in tr.children
+            ]
+            if cells:
+                rows.append(cells)
+    if not rows:
+        return []
+
+    ncols = max(len(row) for row in rows)
+    for row in rows:
+        row.extend([""] * (ncols - len(row)))
+
+    widths = [max(disp_width(row[c]) for row in rows) for c in range(ncols)]
+    while sum(widths) + 2 * (ncols - 1) > width and max(widths) > 4:
+        widths[widths.index(max(widths))] -= 1
+
+    def fmt(row: list[str]) -> str:
+        padded = []
+        for c, cell in enumerate(row):
+            padded.append(cell + " " * max(widths[c] - disp_width(cell), 0))
+        return "  ".join(padded).rstrip()
+
+    lines = [fmt(rows[0]), "  ".join("-" * w for w in widths)]
+    lines += [fmt(row) for row in rows[1:]]
+    return lines
+
+
+# --------------------------------------------------------------------- output
+
+
+def parse(md_text: str, preserve_breaks: bool = True) -> SyntaxTreeNode:
+    md = MarkdownIt(
+        "commonmark", {"html": False, "linkify": True, "typographer": False}
+    )
+    md.enable(["table", "strikethrough", "linkify"])
+    tokens = md.parse(md_text)
+
+    if preserve_breaks:
+        # A single newline usually means a real line break here (signatures,
+        # dates), unlike CommonMark's default of joining it with a space.
+        for token in tokens:
+            if token.type == "inline" and token.children:
+                for child in token.children:
+                    if child.type == "softbreak":
+                        child.type = "hardbreak"
+
+    return SyntaxTreeNode(tokens)
+
+
+def tidy(lines: list[str]) -> list[str]:
+    out: list[str] = []
+    for line in lines:
+        line = line.rstrip()
+        if not line and out and not out[-1]:
+            continue
+        out.append(line)
+    while out and not out[0]:
+        out.pop(0)
+    while out and not out[-1]:
+        out.pop()
+    return out
+
+
+def render_plain(md_text: str, width: int = 75, preserve_breaks: bool = True) -> str:
+    lines = tidy(render_blocks(parse(md_text, preserve_breaks).children, width))
+    return "\n".join(lines) + "\n"

md2plain-0.1.0/tests/test_md2plain.py

@@ -0,0 +1,455 @@
+"""Tests for md2plain: renderer, CLI, clipboard and output invariants."""
+
+from __future__ import annotations
+
+import os
+import subprocess
+import sys
+import tempfile
+import time
+import unittest
+from pathlib import Path
+
+from md2plain.render import disp_width, render_plain
+
+ROOT = Path(__file__).resolve().parents[1]
+CLI = [sys.executable, "-m", "md2plain"]
+MACOS = sys.platform == "darwin"
+
+SAMPLE_MD = """\
+# Format Test
+
+Dear Tester,
+
+This is a sample letter with **bold text**, *italics* and `inline code`.
+It also has a [link](https://example.com) and a bare URL https://example.org.
+
+## A List
+
+* first item
+* second item, long enough to wrap onto another line when the width is small
+* third item
+
+1. one
+2. two
+
+## A Quote
+
+> quoted line one
+> quoted line two
+
+## A Table
+
+| name | count |
+| --- | --- |
+| apple | 3 |
+| pear | 12 |
+
+## Code
+
+```python
+print("hello")
+```
+
+---
+
+Best regards,
+Test User
+2026-01-01
+"""
+
+
+def r(md: str, width: int = 75, preserve: bool = True) -> str:
+    return render_plain(md, width, preserve)
+
+
+def run_cli(*args: str, stdin: str | None = None) -> subprocess.CompletedProcess:
+    return subprocess.run(
+        CLI + list(args),
+        input=stdin,
+        text=True,
+        capture_output=True,
+        cwd=ROOT,
+        check=False,
+    )
+
+
+class SampleCase(unittest.TestCase):
+    """Provide a temporary Markdown file for CLI tests."""
+
+    def setUp(self) -> None:
+        self.tmp = tempfile.TemporaryDirectory()
+        self.addCleanup(self.tmp.cleanup)
+        self.sample = Path(self.tmp.name) / "sample.md"
+        self.sample.write_text(SAMPLE_MD, encoding="utf-8")
+
+
+class Headings(unittest.TestCase):
+    def test_levels_use_underline(self):
+        out = r(
+            "# One\n\n## Two\n\n### Three\n\n#### Four\n\n##### Five\n\n###### Six\n"
+        )
+        self.assertIn("One\n===", out)
+        self.assertIn("Two\n---", out)
+        self.assertIn("Three\n~~~~~", out)
+        self.assertIn("Four\n^^^^", out)
+        self.assertIn('Five\n""""', out)
+        self.assertIn("Six\n'''", out)
+
+    def test_underline_matches_cjk_width(self):
+        self.assertEqual(r("# 标题\n"), "标题\n====\n")
+
+    def test_empty_heading_skipped(self):
+        self.assertEqual(r("#\n\ntext\n"), "text\n")
+
+
+class Paragraphs(unittest.TestCase):
+    def test_wrap_respects_width(self):
+        out = r("word " * 60, 75)
+        for line in out.splitlines():
+            self.assertLessEqual(disp_width(line), 75)
+
+    def test_cjk_wraps_by_display_width(self):
+        out = r("这是一段很长的中文文字，用于测试按两列宽度换行。" * 5, 40)
+        for line in out.splitlines():
+            self.assertLessEqual(disp_width(line), 40)
+
+    def test_no_closing_punctuation_at_line_start(self):
+        out = r("字" * 74 + "。下一句。", 75)
+        for line in out.splitlines():
+            self.assertFalse(line.startswith("。"))
+
+    def test_single_newline_is_kept(self):
+        self.assertEqual(r("Dear A,\nBest regards\n"), "Dear A,\nBest regards\n")
+
+    def test_soft_breaks_join_lines(self):
+        self.assertEqual(r("a\nb\n", 75, preserve=False), "a b\n")
+
+    def test_hard_break_two_spaces(self):
+        self.assertEqual(r("a  \nb\n"), "a\nb\n")
+
+    def test_hard_break_backslash(self):
+        self.assertEqual(r("a\\\nb\n"), "a\nb\n")
+
+    def test_tabs_collapse(self):
+        self.assertEqual(r("a\tb\n"), "a b\n")
+
+    def test_long_token_is_split(self):
+        out = r("x" * 120, 40)
+        self.assertEqual([len(line) for line in out.splitlines()], [40, 40, 40])
+
+
+class Lists(unittest.TestCase):
+    def test_bullets(self):
+        self.assertEqual(r("- a\n- b\n"), "* a\n* b\n")
+
+    def test_ordered(self):
+        self.assertEqual(r("1. a\n2. b\n"), "1. a\n2. b\n")
+
+    def test_ordered_start(self):
+        self.assertEqual(r("3. c\n4. d\n"), "3. c\n4. d\n")
+
+    def test_nested_is_tight(self):
+        self.assertEqual(r("- a\n  - b\n  - c\n- d\n"), "* a\n  * b\n  * c\n* d\n")
+
+    def test_hanging_indent(self):
+        out = r("- " + "word " * 30 + "\n", 40)
+        self.assertTrue(out.startswith("* word"))
+        self.assertTrue(out.splitlines()[1].startswith("  "))
+
+
+class Quotes(unittest.TestCase):
+    def test_simple(self):
+        self.assertEqual(r("> a\n> b\n"), "> a\n> b\n")
+
+    def test_blank_line(self):
+        self.assertEqual(r("> a\n>\n> b\n"), "> a\n>\n> b\n")
+
+    def test_nested(self):
+        self.assertEqual(r("> a\n> > b\n"), "> a\n>\n> > b\n")
+
+    def test_respects_width(self):
+        out = r("> " + "word " * 40, 40)
+        for line in out.splitlines():
+            self.assertLessEqual(disp_width(line), 40)
+
+
+class Code(unittest.TestCase):
+    def test_fence_indented(self):
+        self.assertEqual(r("```\nx = 1\n```\n"), "    x = 1\n")
+
+    def test_fence_not_wrapped(self):
+        long_line = "x" * 100
+        self.assertIn("    " + long_line, r(f"```\n{long_line}\n```\n"))
+
+    def test_inline_code(self):
+        self.assertEqual(r("use `x` here\n"), "use x here\n")
+
+
+class Tables(unittest.TestCase):
+    def test_alignment(self):
+        out = r("| a | b |\n| --- | --- |\n| 1 | 2 |\n")
+        self.assertEqual(out, "a  b\n-  -\n1  2\n")
+
+    def test_cjk_columns(self):
+        out = r("| 名称 | n |\n| --- | --- |\n| 苹果 | 3 |\n")
+        lines = out.splitlines()
+        self.assertEqual(lines[0], "名称  n")
+        self.assertEqual(lines[1], "----  -")
+
+
+class Inline(unittest.TestCase):
+    def test_markdown_link(self):
+        self.assertEqual(r("[x](https://e.com)\n"), "x (https://e.com)\n")
+
+    def test_url_label_with_tracking_param(self):
+        self.assertEqual(
+            r("[https://e.com](https://e.com?utm_source=x)\n"), "https://e.com\n"
+        )
+
+    def test_bare_url_not_duplicated(self):
+        self.assertEqual(r("https://e.com\n"), "https://e.com\n")
+
+    def test_mailto_not_duplicated(self):
+        self.assertEqual(r("<a@b.com>\n"), "a@b.com\n")
+
+    def test_unsafe_scheme_not_linked(self):
+        self.assertEqual(r("[x](javascript:alert(1))\n"), "[x](javascript:alert(1))\n")
+
+    def test_image_alt(self):
+        self.assertEqual(r("![alt text](i.png)\n"), "alt text\n")
+
+    def test_emphasis_stripped(self):
+        self.assertEqual(r("**bold** *it* ~~gone~~\n"), "bold it gone\n")
+
+    def test_html_is_literal(self):
+        self.assertEqual(r("<b>x</b>\n"), "<b>x</b>\n")
+
+
+class Blocks(unittest.TestCase):
+    def test_hr(self):
+        self.assertEqual(r("---\n"), "-" * 72 + "\n")
+
+    def test_empty_input(self):
+        self.assertEqual(r(""), "\n")
+
+
+class Widths(unittest.TestCase):
+    def test_no_wrap_when_width_is_large(self):
+        out = r("word " * 40, 1000)
+        self.assertEqual(len(out.splitlines()), 1)
+
+    def test_width_one_has_no_blank_lines(self):
+        out = r("a b c\n", 1)
+        self.assertEqual([line for line in out.splitlines() if not line], [])
+
+
+class Cli(SampleCase):
+    def test_print_matches_renderer(self):
+        proc = run_cli(str(self.sample), "--print", "--no-copy")
+        self.assertEqual(proc.returncode, 0)
+        self.assertEqual(proc.stdout, render_plain(SAMPLE_MD))
+
+    def test_output_file(self):
+        out = Path(self.tmp.name) / "out.txt"
+        proc = run_cli(str(self.sample), "--no-copy", "-o", str(out))
+        self.assertEqual(proc.returncode, 0)
+        self.assertEqual(out.read_text(encoding="utf-8"), render_plain(SAMPLE_MD))
+
+    def test_stdin(self):
+        proc = run_cli("-", "--print", "--no-copy", stdin="# Hi\n")
+        self.assertEqual(proc.stdout, "Hi\n===\n")
+
+    def test_missing_file(self):
+        proc = run_cli("nope.md", "--no-copy")
+        self.assertEqual(proc.returncode, 1)
+        self.assertIn("File not found", proc.stderr)
+
+    def test_empty_input(self):
+        proc = run_cli("-", "--no-copy", stdin="")
+        self.assertEqual(proc.returncode, 1)
+        self.assertIn("Input is empty", proc.stderr)
+
+    def test_invalid_width(self):
+        proc = run_cli(str(self.sample), "--width", "0", "--no-copy")
+        self.assertEqual(proc.returncode, 2)
+        self.assertIn("at least 1", proc.stderr)
+
+    def test_watch_requires_file(self):
+        proc = run_cli("-", "--watch", stdin="x")
+        self.assertEqual(proc.returncode, 2)
+        self.assertIn("requires a file", proc.stderr)
+
+    def test_bom_stripped(self):
+        path = Path(self.tmp.name) / "bom.md"
+        path.write_bytes(b"\xef\xbb\xbf# Title\n\nBody\n")
+        proc = run_cli(str(path), "--print", "--no-copy")
+        self.assertFalse(proc.stdout.startswith("\ufeff"))
+        self.assertTrue(proc.stdout.startswith("Title"))
+
+    def test_crlf(self):
+        path = Path(self.tmp.name) / "crlf.md"
+        path.write_bytes(b"a\r\nb\r\n")
+        proc = run_cli(str(path), "--print", "--no-copy")
+        self.assertEqual(proc.stdout, "a\nb\n")
+
+    def test_invalid_utf8(self):
+        path = Path(self.tmp.name) / "bad.md"
+        path.write_bytes(b"hello \xff world\n")
+        proc = run_cli(str(path), "--print", "--no-copy")
+        self.assertEqual(proc.returncode, 0)
+
+    def test_directory_input(self):
+        proc = run_cli(self.tmp.name, "--no-copy")
+        self.assertEqual(proc.returncode, 1)
+        self.assertIn("Cannot read", proc.stderr)
+
+    def test_path_with_spaces(self):
+        path = Path(self.tmp.name) / "a b.md"
+        path.write_text("# Hi\n", encoding="utf-8")
+        proc = run_cli(str(path), "--print", "--no-copy")
+        self.assertEqual(proc.stdout, "Hi\n===\n")
+
+    def test_cli_width_matches_renderer(self):
+        proc = run_cli(str(self.sample), "--print", "--no-copy", "--width", "60")
+        self.assertEqual(proc.stdout, render_plain(SAMPLE_MD, 60))
+
+    def test_output_path_with_spaces(self):
+        out = Path(self.tmp.name) / "out file.txt"
+        proc = run_cli(str(self.sample), "--no-copy", "-o", str(out))
+        self.assertEqual(proc.returncode, 0)
+        self.assertTrue(out.exists())
+
+
+class Invariants(unittest.TestCase):
+    def check(self, out: str) -> None:
+        self.assertTrue(out.endswith("\n"))
+        self.assertFalse(out.endswith("\n\n"))
+        self.assertNotIn("\x00", out)
+        self.assertNotIn("\r", out)
+        for line in out.splitlines():
+            self.assertEqual(line, line.rstrip())
+            self.assertLessEqual(disp_width(line), 76)
+            self.assertFalse(line[:1] in set("。，、；：！？"))
+
+    def test_sample(self):
+        self.check(r(SAMPLE_MD))
+
+    def test_cjk(self):
+        self.check(r("中文段落。" * 40))
+
+    def test_deterministic(self):
+        self.assertEqual(r(SAMPLE_MD), r(SAMPLE_MD))
+
+
+class Performance(unittest.TestCase):
+    def test_large_document(self):
+        md = ("word " * 20000 + "\n\n") + ("中文段落。" * 5000)
+        start = time.perf_counter()
+        out = r(md)
+        elapsed = time.perf_counter() - start
+        self.assertGreater(len(out), 10000)
+        self.assertLess(elapsed, 2.0)
+
+
+class Fuzz(unittest.TestCase):
+    def test_random_markdown_never_crashes(self):
+        import random
+
+        random.seed(7)
+        parts = [
+            "# Title",
+            "## Sub",
+            "text",
+            "中文段落",
+            "- item",
+            "1. one",
+            "> quote",
+            "```",
+            "code()",
+            "| a | b |",
+            "| --- | --- |",
+            "**bold**",
+            "[link](https://e.com)",
+            "https://e.com",
+            "---",
+            "",
+            "  ",
+            "\t",
+            "😀",
+            "a" * 90,
+        ]
+        for _ in range(200):
+            md = "\n".join(random.choice(parts) for _ in range(random.randint(1, 25)))
+            out = r(md + "\n", random.choice([1, 10, 40, 75, 200]))
+            self.assertTrue(out.endswith("\n"))
+            self.assertNotIn("\x00", out)
+            self.assertNotIn("\r", out)
+            for line in out.splitlines():
+                self.assertEqual(line, line.rstrip())
+
+
+@unittest.skipUnless(MACOS, "clipboard tests need macOS")
+class Clipboard(SampleCase):
+    def test_text_only_and_content(self):
+        from AppKit import NSPasteboard, NSPasteboardTypeHTML, NSPasteboardTypeString
+
+        name = f"md2plain-test-{os.getpid()}"
+        env = dict(os.environ, MD2PLAIN_PASTEBOARD=name)
+        proc = subprocess.run(
+            CLI + [str(self.sample)],
+            env=env,
+            text=True,
+            capture_output=True,
+            cwd=ROOT,
+            check=False,
+        )
+        self.assertEqual(proc.returncode, 0)
+        board = NSPasteboard.pasteboardWithName_(name)
+        self.assertIsNone(board.dataForType_(NSPasteboardTypeHTML))
+        self.assertEqual(
+            board.stringForType_(NSPasteboardTypeString), render_plain(SAMPLE_MD)
+        )
+
+
+@unittest.skipUnless(MACOS, "clipboard tests need macOS")
+class Watch(unittest.TestCase):
+    def test_watch_updates_clipboard(self):
+        from AppKit import NSPasteboard, NSPasteboardTypeString
+
+        name = f"md2plain-watch-{os.getpid()}"
+        with tempfile.NamedTemporaryFile("w", suffix=".md", delete=False) as f:
+            f.write("# A\n\nfirst\n")
+            path = f.name
+        env = dict(os.environ, MD2PLAIN_PASTEBOARD=name)
+        proc = subprocess.Popen(
+            CLI + [path, "--watch"],
+            env=env,
+            cwd=ROOT,
+            stdout=subprocess.DEVNULL,
+            stderr=subprocess.DEVNULL,
+        )
+        board = NSPasteboard.pasteboardWithName_(name)
+        try:
+            deadline = time.time() + 6
+            while time.time() < deadline:
+                if "A" in (board.stringForType_(NSPasteboardTypeString) or ""):
+                    break
+                time.sleep(0.2)
+            Path(path).write_text("# B\n\nsecond\n", encoding="utf-8")
+            deadline = time.time() + 6
+            text = ""
+            while time.time() < deadline:
+                text = board.stringForType_(NSPasteboardTypeString) or ""
+                if "B" in text:
+                    break
+                time.sleep(0.2)
+            self.assertIn("B", text)
+        finally:
+            proc.terminate()
+            proc.wait(timeout=5)
+            os.unlink(path)
+
+
+if __name__ == "__main__":
+    unittest.main(verbosity=2)