mdfetch 0.4.0__tar.gz → 0.5.0__tar.gz

mdfetch-0.5.0/.gitattributes

@@ -0,0 +1,2 @@
+*.sh linguist-vendored
+*.ps1 linguist-vendored

{mdfetch-0.4.0 → mdfetch-0.5.0}/.specify/extensions.yml

@@ -22,7 +22,7 @@ hooks:
   - extension: git
     command: speckit.git.commit
     enabled: true
-    optional: true
+    optional: false
     prompt: Commit outstanding changes before clarification?
     description: Auto-commit before spec clarification
     condition: null
@@ -30,7 +30,7 @@ hooks:
   - extension: git
     command: speckit.git.commit
     enabled: true
-    optional: true
+    optional: false
     prompt: Commit outstanding changes before planning?
     description: Auto-commit before implementation planning
     condition: null
@@ -38,7 +38,7 @@ hooks:
   - extension: git
     command: speckit.git.commit
     enabled: true
-    optional: true
+    optional: false
     prompt: Commit outstanding changes before task generation?
     description: Auto-commit before task generation
     condition: null
@@ -46,7 +46,7 @@ hooks:
   - extension: git
     command: speckit.git.commit
     enabled: true
-    optional: true
+    optional: false
     prompt: Commit outstanding changes before implementation?
     description: Auto-commit before implementation
     condition: null
@@ -54,7 +54,7 @@ hooks:
   - extension: git
     command: speckit.git.commit
     enabled: true
-    optional: true
+    optional: false
     prompt: Commit outstanding changes before checklist?
     description: Auto-commit before checklist generation
     condition: null
@@ -62,7 +62,7 @@ hooks:
   - extension: git
     command: speckit.git.commit
     enabled: true
-    optional: true
+    optional: false
     prompt: Commit outstanding changes before analysis?
     description: Auto-commit before analysis
     condition: null
@@ -70,7 +70,7 @@ hooks:
   - extension: git
     command: speckit.git.commit
     enabled: true
-    optional: true
+    optional: false
     prompt: Commit outstanding changes before issue sync?
     description: Auto-commit before tasks-to-issues conversion
     condition: null
@@ -78,7 +78,7 @@ hooks:
   - extension: git
     command: speckit.git.commit
     enabled: true
-    optional: true
+    optional: false
     prompt: Commit constitution changes?
     description: Auto-commit after constitution update
     condition: null
@@ -86,7 +86,7 @@ hooks:
   - extension: git
     command: speckit.git.commit
     enabled: true
-    optional: true
+    optional: false
     prompt: Commit specification changes?
     description: Auto-commit after specification
     condition: null
@@ -94,7 +94,7 @@ hooks:
   - extension: git
     command: speckit.git.commit
     enabled: true
-    optional: true
+    optional: false
     prompt: Commit clarification changes?
     description: Auto-commit after spec clarification
     condition: null
@@ -102,7 +102,7 @@ hooks:
   - extension: git
     command: speckit.git.commit
     enabled: true
-    optional: true
+    optional: false
     prompt: Commit plan changes?
     description: Auto-commit after implementation planning
     condition: null
@@ -110,7 +110,7 @@ hooks:
   - extension: git
     command: speckit.git.commit
     enabled: true
-    optional: true
+    optional: false
     prompt: Commit task changes?
     description: Auto-commit after task generation
     condition: null
@@ -118,7 +118,7 @@ hooks:
   - extension: git
     command: speckit.git.commit
     enabled: true
-    optional: true
+    optional: false
     prompt: Commit implementation changes?
     description: Auto-commit after implementation
     condition: null
@@ -126,7 +126,7 @@ hooks:
   - extension: git
     command: speckit.git.commit
     enabled: true
-    optional: true
+    optional: false
     prompt: Commit checklist changes?
     description: Auto-commit after checklist generation
     condition: null
@@ -134,7 +134,7 @@ hooks:
   - extension: git
     command: speckit.git.commit
     enabled: true
-    optional: true
+    optional: false
     prompt: Commit analysis results?
     description: Auto-commit after analysis
     condition: null
@@ -142,7 +142,7 @@ hooks:
   - extension: git
     command: speckit.git.commit
     enabled: true
-    optional: true
+    optional: false
     prompt: Commit after syncing issues?
     description: Auto-commit after tasks-to-issues conversion
     condition: null

mdfetch-0.5.0/.specify/feature.json

@@ -0,0 +1,3 @@
+{
+  "feature_directory": "specs/008-mdfetch-cli"
+}

{mdfetch-0.4.0 → mdfetch-0.5.0}/.specify/memory/changelog.md

@@ -1,3 +1,26 @@
+### mdfetch — Architecture Refactoring & CLI Improvements — 2026-05-16
+
+**Branch**: `refactor/reduce-duplication-and-robustness`
+
+**What was added**:
+- Centralized duplicated markdown conversion and iframe stripping into `BaseExtractor`, utilizing a `_markdownify_kwargs()` hook.
+- Added strict `Content-Type` header validation in `_do_fetch` to eagerly reject non-HTML responses (e.g., `application/json`, `application/pdf`).
+- Implemented `httpx.Client` connection pooling across retry attempts.
+- Exported new public API `mdfetch.supported_domains()` which returns a `frozenset[str]` of all registered domains.
+- Expanded the CLI (`mdfetch.cli:main`) with configurable options: `--retries`, `--retry-delay` (with click `IntRange`/`FloatRange` validation), and `--version`.
+- Removed control-flow assertions in favor of explicit `RuntimeError` guards.
+- Consolidated test helpers (`make_stream_mock`) into `tests/conftest.py`.
+- Bumped package version to `0.5.0`.
+
+**New Components**:
+- Updates across `base.py`, `router.py`, `cli.py`, and `__init__.py`.
+- Refactored providers (`devto.py`, `substack.py`, `thenewstack.py`, `dzone.py`) to leverage `BaseExtractor` defaults.
+- Additional unit and integration test coverage for CLI flags and content types.
+
+**Tasks Completed**: Refactoring and PR Review updates
+
+---
+
 # Merged Features Log
 
 ---

{mdfetch-0.4.0 → mdfetch-0.5.0}/.specify/memory/plan.md

@@ -44,7 +44,9 @@ BaseExtractor (ABC)               — src/mdfetch/base.py
 │                                   fixed delay of retry_delay seconds between attempts (not exponential);
 │                                   codes in _no_retry_codes (or class attribute) raise immediately
 ├── clean_html(soup) → Tag        — abstract: platform-specific HTML isolation
-├── convert_to_markdown(tag) → str— abstract: platform-specific Markdown conversion
+├── _markdownify_kwargs() → dict  — hook: platform-specific markdownify options (defaults to ATX + empty language)
+├── _replace_iframes_with_links(container, soup) — helper: converts <iframe> embeds to plain anchors
+├── convert_to_markdown(tag) → str— concrete: base implementation using markdownify and 3+ newlines collapse
 └── extract(url) → str            — concrete template method (orchestrates the above)
 
 MediumExtractor(BaseExtractor)    — src/mdfetch/providers/medium.py
@@ -59,33 +61,35 @@ MediumExtractor(BaseExtractor)    — src/mdfetch/providers/medium.py
 
 DevToExtractor(BaseExtractor)     — src/mdfetch/providers/devto.py
 ├── DOMAINS = frozenset({"dev.to"})
-├── clean_html() → locates div#article-body; raises UnsupportedContentTypeError if absent;
-│                  replaces iframes and ltag embeds with anchor links; strips empty anchor-name
-│                  elements; prepends h1 + cover image from crayons-article__header
-└── convert_to_markdown() → markdownify with ATX headings; collapses 3+ newlines to 2
+└── clean_html() → locates div#article-body; raises UnsupportedContentTypeError if absent;
+                   replaces iframes and ltag embeds with anchor links (via helper); strips empty anchor-name
+                   elements; prepends h1 + cover image from crayons-article__header
 
 SubstackExtractor(BaseExtractor)  — src/mdfetch/providers/substack.py  [005-substack-provider]
 ├── DOMAINS = frozenset({"substack.com"})  — also matches *.substack.com via suffix routing
 ├── _no_retry_status_codes = frozenset()  — HTTP 429 retried (no Freedium-style fallback)
-├── clean_html() → locates div.body.markup; raises UnsupportedContentTypeError if absent;
-│                  strips div.subscription-widget-wrap (inline CTAs + paywall terminal);
-│                  replaces iframes with anchor links using src/data-src;
-│                  replaces div[data-component-name] (except SubscribeWidget, Image2ToDOM) with anchor links;
-│                  prepends h3.subtitle from div.post-header (if present);
-│                  prepends h1.post-title from div.post-header (unconditional — structurally outside body)
-└── convert_to_markdown() → markdownify with ATX headings; collapses 3+ newlines to 2; raises EmptyContentError if empty
+└── clean_html() → locates div.body.markup; raises UnsupportedContentTypeError if absent;
+                   strips div.subscription-widget-wrap (inline CTAs + paywall terminal);
+                   replaces iframes with anchor links (via helper);
+                   replaces div[data-component-name] (except SubscribeWidget, Image2ToDOM) with anchor links;
+                   prepends h3.subtitle from div.post-header (if present);
+                   prepends h1.post-title from div.post-header (unconditional — structurally outside body)
 
 TheNewStackExtractor(BaseExtractor) — src/mdfetch/providers/thenewstack.py  [006-thenewstack-provider]
 ├── DOMAINS = frozenset({"thenewstack.io"})  — no subdomain routing needed (single-site WordPress)
 ├── _no_retry_status_codes = frozenset()  — inherits base class default (no overrides needed)
-├── clean_html() → locates div#tns-post-body-content; raises UnsupportedContentTypeError if absent;
-│                  decomposes 4 sponsored-content selectors: div.sponsored-post-disclosure,
-│                    div.tns-sponsored-post-disclosure, div.sponsor-disclosure, div.tns-sponsor-note;
-│                  replaces iframes with anchor links using src/data-src (defensive; not observed in reference articles);
-│                  prepends div.post-excerpt text as new <p> tag (deck) from div#tns-post-headline (if present);
-│                  prepends copy.copy(h1.title) from div#tns-post-headline (if present)
-│                  Note: VoxPop polls (div.tns-voxpop-screen) are page-level modals outside body — no stripping needed
-└── convert_to_markdown() → markdownify with ATX headings; collapses 3+ newlines to 2; raises EmptyContentError if empty
+└── clean_html() → locates div#tns-post-body-content; raises UnsupportedContentTypeError if absent;
+                   decomposes 4 sponsored-content selectors: div.sponsored-post-disclosure,
+                     div.tns-sponsored-post-disclosure, div.sponsor-disclosure, div.tns-sponsor-note;
+                   replaces iframes with anchor links (via helper);
+                   prepends div.post-excerpt text as new <p> tag (deck) from div#tns-post-headline (if present);
+                   prepends copy.copy(h1.title) from div#tns-post-headline (if present)
+                   Note: VoxPop polls (div.tns-voxpop-screen) are page-level modals outside body — no stripping needed
+
+DZoneExtractor(BaseExtractor) — src/mdfetch/providers/dzone.py
+├── DOMAINS = frozenset({"dzone.com"})
+├── _markdownify_kwargs() → overrides to add code_language_callback
+└── clean_html() → locates div.content-html; raises UnsupportedContentTypeError if absent;
 ```
 
 ### Router / Auto-Discovery
@@ -95,6 +99,7 @@ router.py
 ├── _REGISTRY: dict[str, type[BaseExtractor]]
 ├── @register decorator          — self-enrolls provider at class definition time
 ├── _autodiscover_providers()    — pkgutil.iter_modules scans mdfetch/providers/ at import
+├── supported_domains() → frozenset[str] — returns all registered domain strings
 ├── route(url) → BaseExtractor   — exact hostname match, then longest-suffix fallback
 └── Duplicate domain registration raises ValueError
 ```
@@ -118,13 +123,15 @@ src/
     ├── __init__.py          # Public surface: exposes extract(), exception re-exports
     ├── exceptions.py        # MdfetchError hierarchy (6 exception classes)
     ├── router.py            # @register, _autodiscover_providers(), route()
-    ├── base.py              # BaseExtractor ABC + fetch_html() + extract() template
+    ├── base.py              # BaseExtractor ABC + fetch_html() + convert_to_markdown() + extract() template
+    ├── cli.py               # click-based command line interface
     └── providers/
         ├── __init__.py      # Empty — auto-discovery handles registration
         ├── medium.py        # MediumExtractor
         ├── devto.py         # DevToExtractor [002-devto-provider]
         ├── substack.py      # SubstackExtractor [005-substack-provider]
-        └── thenewstack.py   # TheNewStackExtractor [006-thenewstack-provider]
+        ├── thenewstack.py   # TheNewStackExtractor [006-thenewstack-provider]
+        └── dzone.py         # DZoneExtractor
 
 tests/
 ├── unit/

mdfetch-0.5.0/.vscode/settings.json

@@ -0,0 +1,10 @@
+{
+    "files.exclude": {
+        "**/.git": true,
+        "**/.svn": true,
+        "**/.hg": true,
+        "**/.DS_Store": true,
+        "**/Thumbs.db": true,
+        ".mule": true
+    }
+}

{mdfetch-0.4.0 → mdfetch-0.5.0}/CLAUDE.md

@@ -7,6 +7,7 @@ Python library that extracts article content from web platforms and returns it a
 ```
 src/mdfetch/
 ├── __init__.py       # extract() public API + exception re-exports
+├── cli.py            # Command-line interface and argument parsing
 ├── exceptions.py     # MdfetchError hierarchy (7 exception classes)
 ├── base.py           # BaseExtractor ABC
 ├── router.py         # Domain-to-provider routing
@@ -15,7 +16,8 @@ src/mdfetch/
     ├── medium.py     # MediumExtractor (medium.com + *.medium.com)
     ├── devto.py      # DevToExtractor (dev.to)
     ├── substack.py   # SubstackExtractor (substack.com + *.substack.com)
-    └── thenewstack.py  # TheNewStackExtractor (thenewstack.io)
+    ├── thenewstack.py  # TheNewStackExtractor (thenewstack.io)
+    └── dzone.py      # DZoneExtractor (dzone.com)
 
 tests/
 ├── unit/             # pytest unit tests (no network)
@@ -34,7 +36,7 @@ Makefile              # setup / test / lint / format / build / upgrade-deps / cl
 ## Key conventions
 
 - **Package manager**: `uv` for all dev workflows — never use `pip`, `venv`, or `pip-tools` directly
-- **Provider pattern**: new platforms = one new file under `src/mdfetch/providers/`, no changes to shared code
+- **Provider pattern**: new platforms = one new file under `src/mdfetch/providers/` subclassing `BaseExtractor` and utilizing its shared conversion methods.
 - **No logging**: all failures communicated via typed exceptions only (FR-013)
 - **Type hints**: strict (`mypy src/` must pass with zero errors)
 - **Linter/formatter**: `ruff` (`make lint` / `make format`)
@@ -49,13 +51,13 @@ make format       # ruff format
 make build        # uv build (wheel + sdist)
 make upgrade-deps # uv sync --all-extras --upgrade
 make integration  # integration tests (network required)
-uv run mypy src/  # type check
+make typecheck    # type check
 ```
 
 <!-- SPECKIT START -->
 ## Active Feature Plan
 
-Active feature: `007-dzone-provider`. Implementation plan: [`specs/007-dzone-provider/plan.md`](specs/007-dzone-provider/plan.md).
+Active feature: `008-mdfetch-cli`. Implementation plan: [`specs/008-mdfetch-cli/plan.md`](specs/008-mdfetch-cli/plan.md).
 
 ## Known Issues & Gotchas
 

{mdfetch-0.4.0 → mdfetch-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mdfetch
-Version: 0.4.0
+Version: 0.5.0
 Summary: Extract article content from web platforms and return it as clean Markdown.
 Project-URL: Homepage, https://github.com/stn1slv/md-fetch
 Project-URL: Source, https://github.com/stn1slv/md-fetch
@@ -20,11 +20,13 @@ Classifier: Topic :: Internet :: WWW/HTTP
 Classifier: Topic :: Text Processing :: Markup :: Markdown
 Requires-Python: >=3.12
 Requires-Dist: beautifulsoup4>=4.12
+Requires-Dist: click>=8.1
 Requires-Dist: httpx>=0.27
 Requires-Dist: lxml>=5.0
 Requires-Dist: markdownify>=0.13
 Provides-Extra: dev
 Requires-Dist: mypy>=1.9; extra == 'dev'
+Requires-Dist: pytest-mock>=3.14.0; extra == 'dev'
 Requires-Dist: pytest>=8.0; extra == 'dev'
 Requires-Dist: ruff>=0.4; extra == 'dev'
 Description-Content-Type: text/markdown
@@ -39,7 +41,19 @@ A Python library that extracts article content from web platforms and returns it
 pip install mdfetch
 ```
 
-## Usage
+## CLI Usage
+
+You can use the built-in `md-fetch` command directly from your terminal:
+
+```bash
+# Fetch and print Markdown to standard output
+md-fetch https://medium.com/example/article
+
+# Fetch and save Markdown to a file
+md-fetch https://dev.to/example/article --output article.md
+```
+
+## Python Usage
 
 ```python
 from mdfetch import extract

{mdfetch-0.4.0 → mdfetch-0.5.0}/README.md

@@ -8,7 +8,19 @@ A Python library that extracts article content from web platforms and returns it
 pip install mdfetch
 ```
 
-## Usage
+## CLI Usage
+
+You can use the built-in `md-fetch` command directly from your terminal:
+
+```bash
+# Fetch and print Markdown to standard output
+md-fetch https://medium.com/example/article
+
+# Fetch and save Markdown to a file
+md-fetch https://dev.to/example/article --output article.md
+```
+
+## Python Usage
 
 ```python
 from mdfetch import extract

{mdfetch-0.4.0 → mdfetch-0.5.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "mdfetch"
-version = "0.4.0"
+version = "0.5.0"
 description = "Extract article content from web platforms and return it as clean Markdown."
 readme = "README.md"
 license = { text = "MIT" }
@@ -27,11 +27,16 @@ dependencies = [
     "beautifulsoup4>=4.12",
     "lxml>=5.0",
     "markdownify>=0.13",
+    "click>=8.1",
 ]
 
+[project.scripts]
+md-fetch = "mdfetch.cli:main"
+
 [project.optional-dependencies]
 dev = [
     "pytest>=8.0",
+    "pytest-mock>=3.14.0",
     "ruff>=0.4",
     "mypy>=1.9",
 ]

mdfetch-0.5.0/specs/008-mdfetch-cli/checklists/requirements.md

@@ -0,0 +1,35 @@
+# Specification Quality Checklist: mdfetch-cli
+
+**Purpose**: Validate specification completeness and quality before proceeding to planning
+**Created**: Saturday, May 16, 2026
+**Feature**: [spec.md](../spec.md)
+
+## Content Quality
+
+- [x] No implementation details (languages, frameworks, APIs)
+- [x] Focused on user value and business needs
+- [x] Written for non-technical stakeholders
+- [x] All mandatory sections completed
+
+## Requirement Completeness
+
+- [x] No [NEEDS CLARIFICATION] markers remain
+- [x] Requirements are testable and unambiguous
+- [x] Success criteria are measurable
+- [x] Success criteria are technology-agnostic (no implementation details)
+- [x] All acceptance scenarios are defined
+- [x] Edge cases are identified
+- [x] Scope is clearly bounded
+- [x] Dependencies and assumptions identified
+
+## Feature Readiness
+
+- [x] All functional requirements have clear acceptance criteria
+- [x] User scenarios cover primary flows
+- [x] Feature meets measurable outcomes defined in Success Criteria
+- [x] No implementation details leak into specification
+
+## Notes
+
+- All checklist items pass. The specification is complete and valid.
+- The feature is straightforward and maps clearly to standard CLI conventions.

mdfetch-0.5.0/specs/008-mdfetch-cli/contracts/cli.md

@@ -0,0 +1,32 @@
+# CLI Contract: mdfetch-cli
+
+## Command Signature
+
+```bash
+md-fetch [OPTIONS] URL
+```
+
+### Positional Arguments
+- `URL`: The web article URL to extract.
+
+### Options
+- `-o, --output PATH`: Write the Markdown output to the specified file path instead of standard output.
+- `--retries INTEGER`: Total number of fetch attempts on transient errors (default: 3, minimum: 1).
+- `--retry-delay FLOAT`: Seconds to wait between retry attempts (default: 2.0, minimum: 0).
+- `--version`: Show the installed version and exit.
+- `--help`: Show the usage instructions and exit.
+
+## Exit Codes
+- `0`: Success. The Markdown was printed to stdout or successfully written to the output file.
+- `1` (or other non-zero): Failure. A network error occurred, the domain is unsupported, or no extractable content was found. An error message is printed to `stderr`.
+
+## Unsupported Domain Error Format
+
+When the URL's domain has no registered provider, the error is printed to `stderr` in this format:
+
+```
+Error: '<domain>' is not a supported platform.
+Supported domains: dev.to, dzone.com, medium.com, substack.com, thenewstack.io
+```
+
+The supported-domain list is sorted alphabetically and reflects all registered providers at runtime.

mdfetch-0.5.0/specs/008-mdfetch-cli/data-model.md

@@ -0,0 +1,9 @@
+# Data Model: mdfetch-cli
+
+No new database or internal domain entities are introduced.
+
+## CLI Execution State
+
+- **Input URL** (`str`): The target URL to fetch.
+- **Output File** (`str | None`): An optional file path provided via `--output`.
+- **Exit Code** (`int`): `0` for success, non-zero (`1`) for failure.

mdfetch-0.5.0/specs/008-mdfetch-cli/plan.md

@@ -0,0 +1,96 @@
+# Implementation Plan: mdfetch-cli
+
+**Branch**: `008-mdfetch-cli` | **Date**: 2026-05-16 | **Spec**: [spec.md](./spec.md)
+
+**Input**: Feature specification from `/specs/008-mdfetch-cli/spec.md`
+
+## Summary
+
+Add a CLI entry point named `md-fetch` using the `click` framework. This CLI will accept a single URL, fetch the Markdown utilizing the existing library, and print it to standard output or save it to a specified file while providing graceful error handling.
+
+## Technical Context
+
+**Language/Version**: Python 3.12+
+
+**Primary Dependencies**: `httpx`, `BeautifulSoup`, `markdownify`, `pytest`, `click` (new dependency for CLI)
+
+**Target Platform**: PyPI library (cross-platform CLI tool)
+
+**Project Type**: Library + CLI
+
+**Performance Goals**: Inherits base class 30-second fetch timeout.
+
+**Constraints**: Must use `click` framework. Handle `MdfetchError` subclasses explicitly without tracebacks.
+
+## Constitution Check
+
+*GATE: Must pass before implementation. Re-check after design phase.*
+
+- [x] Validates Provider Pattern Architecture (N/A - does not create a new provider, but wraps existing logic cleanly)
+- [x] Confirms Technology Stack (Using `click` as per application blueprint for CLI frameworks)
+- [x] Adheres to Coding Standards (PEP 8, Type Hinting, Clear Vocabulary)
+- [x] Incorporates Integration Testing (Requires CLI invocation tests, though it's mainly wrapping tested logic)
+- [x] Respects Packaging and Distribution standards (`pyproject.toml` integration via `[project.scripts]`)
+
+## Project Structure
+
+### Documentation (this feature)
+
+```text
+specs/008-mdfetch-cli/
+├── plan.md              # This file
+├── research.md          # Phase 0 output
+├── data-model.md        # Phase 1 output
+├── quickstart.md        # Phase 1 output
+├── contracts/           # Phase 1 output
+└── tasks.md             # Phase 2 output (future)
+```
+
+### Source Code
+
+```text
+src/mdfetch/
+└── cli.py                 # NEW: click command implementation
+
+tests/integration/
+└── test_cli_integration.py # NEW: testing the CLI entry point
+```
+
+**Non-runtime changes**: Update `pyproject.toml` to add `click` dependency and `project.scripts` configuration. Update `README.md` to document CLI usage.
+
+## Extraction Algorithm (CLI Wrapper)
+
+```python
+import click
+from mdfetch import extract
+from mdfetch.exceptions import MdfetchError
+
+@click.command()
+@click.argument("url")
+@click.option("-o", "--output", type=click.Path(writable=True, dir_okay=False), help="Save Markdown to this file")
+def main(url, output):
+    try:
+        content = extract(url)
+        if output:
+            with open(output, "w", encoding="utf-8") as f:
+                f.write(content)
+        else:
+            click.echo(content)
+    except MdfetchError as e:
+        click.secho(str(e), err=True, fg="red")
+        raise click.Abort()
+```
+
+## Error Mapping
+
+| Condition | Exception | CLI Behavior |
+|-----------|-----------|--------------|
+| Any `MdfetchError` | `MdfetchError` subclasses | Catch, print `str(e)` to stderr, exit code `1` |
+| File write error | `IOError` / `OSError` | Propagated or caught by Click Path validation |
+| Invalid URL option | N/A | Click usage error, exits with `2` |
+
+## Complexity Tracking
+
+| Violation | Why Needed | Simpler Alternative Rejected Because |
+|-----------|------------|--------------------------------------|
+| None | N/A | N/A |

mdfetch-0.5.0/specs/008-mdfetch-cli/quickstart.md

@@ -0,0 +1,13 @@
+# Quickstart: mdfetch-cli
+
+Once installed or running via `uv run`, you can use the `md-fetch` command directly from your terminal.
+
+## Print to stdout
+```bash
+md-fetch https://medium.com/example/article
+```
+
+## Save to a file
+```bash
+md-fetch https://dev.to/example/article --output my_article.md
+```

mdfetch-0.5.0/specs/008-mdfetch-cli/research.md

@@ -0,0 +1,15 @@
+# Research: mdfetch-cli
+
+## CLI Framework Decision
+
+- **Decision**: Use `click`.
+- **Rationale**: The project's Python Application Blueprint mandates `click` or `typer`. `click` is a lightweight, widely adopted standard for CLI tools in Python. It handles argument parsing, standard help interfaces, and exit codes elegantly.
+- **Alternatives considered**:
+  - `typer`: Adds type-hint-based parsing but introduces another dependency layer (Pydantic). `click` is simpler for a single-command tool.
+  - `argparse`: Built-in, but the project blueprint specifically prefers `click` or `typer` for consistency across tools.
+
+## Error Handling
+
+- **Decision**: Catch `mdfetch.exceptions.MdfetchError` (and its subclasses) in the CLI entry point, print `str(err)` to `sys.stderr` via `click.secho(err='red')`, and call `sys.exit(1)`.
+- **Rationale**: `mdfetch` already encapsulates all expected failures in the `MdfetchError` hierarchy. We avoid exposing tracebacks to end users unless an unexpected bug occurs.
+- **Alternatives considered**: Silently returning empty output or logging the error. However, CLI tools should clearly indicate failure via non-zero exit codes and standard error.