decant-cli 0.1.0__tar.gz

decant_cli-0.1.0/LICENSE

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

decant_cli-0.1.0/PKG-INFO

@@ -0,0 +1,63 @@
+Metadata-Version: 2.4
+Name: decant-cli
+Version: 0.1.0
+Summary: Convert semantic HTML to dyslexia-friendly readable HTML
+Author: Dave Zack
+License: MIT
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: beautifulsoup4>=4.12.0
+Requires-Dist: lxml>=5.0.0
+Requires-Dist: nh3>=0.2.0
+Requires-Dist: trafilatura>=1.8.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: flask>=3.0.0; extra == "dev"
+Requires-Dist: requests>=2.31.0; extra == "dev"
+Dynamic: license-file
+
+# Flowdoc
+
+Flowdoc is a free, open-source CLI tool that converts web articles into clean, accessible, self-contained HTML files styled for readers with dyslexia and related conditions. It strips site chrome, extracts article content, and produces a single portable document with BDA-recommended typography -- printable, offline-readable, and ready to hand to a student or email to a teacher.
+
+Many documents are technically "readable" but visually fatiguing for readers with dyslexia due to cramped line length, poor spacing, and layout choices that prioritize appearance over readability. Browser Reader Mode helps but is ephemeral -- you cannot save it, print it with controlled typography, or share it reliably. Flowdoc produces actual documents.
+
+## v1 scope (summary)
+
+- Input: HTML with semantic structure (headings, paragraphs, lists)
+- Output: a single, self-contained HTML file (no external CSS/fonts/scripts/images)
+- Readability over fidelity: no attempt to preserve original styling or branding
+- Optional font toggle: `--font opendyslexic` (not default)
+
+Full boundaries: see [SCOPE.md](SCOPE.md).
+
+## Status
+
+Phase 2 complete. Core pipeline built and tested against 11 real-world fixtures (8 clean passes, 1 marginal, 2 known limitations). Preparing for v1 open-source release.
+
+## Planned CLI
+
+```bash
+flowdoc convert input.html
+flowdoc convert input.html -o output.html
+flowdoc convert input.html --font opendyslexic
+```
+
+Print to PDF: open the output in a browser and use print-to-PDF.
+
+## Documentation
+
+- [SCOPE.md](SCOPE.md) - frozen v1 product boundaries and success criteria
+- [docs/decisions.md](docs/decisions.md) - authoritative implementation/test spec (contracts + invariants)
+- [docs/architecture.md](docs/architecture.md) - locked v1 implementation choices (runtime, libraries, module structure, pipeline, testing)
+- [docs/flowdoc-v1-plan.md](docs/flowdoc-v1-plan.md) - execution checklist for v1
+- [docs/flowdoc-v1-success-contract.md](docs/flowdoc-v1-success-contract.md) - locked v1 success contract (takes precedence over all other docs where conflicts exist)
+- [docs/research_typography_guidelines.md](docs/research_typography_guidelines.md) - typography research/reference
+- [flowdoc-elevator-pitch.md](flowdoc-elevator-pitch.md) - what Flowdoc is in 60 seconds
+- [docs/flowdoc-project-summary.md](docs/flowdoc-project-summary.md) - project history and context
+- [ABOUT.md](ABOUT.md) - project origin story and motivation
+
+## License
+
+[MIT](LICENSE)

decant_cli-0.1.0/README.md

@@ -0,0 +1,44 @@
+# Flowdoc
+
+Flowdoc is a free, open-source CLI tool that converts web articles into clean, accessible, self-contained HTML files styled for readers with dyslexia and related conditions. It strips site chrome, extracts article content, and produces a single portable document with BDA-recommended typography -- printable, offline-readable, and ready to hand to a student or email to a teacher.
+
+Many documents are technically "readable" but visually fatiguing for readers with dyslexia due to cramped line length, poor spacing, and layout choices that prioritize appearance over readability. Browser Reader Mode helps but is ephemeral -- you cannot save it, print it with controlled typography, or share it reliably. Flowdoc produces actual documents.
+
+## v1 scope (summary)
+
+- Input: HTML with semantic structure (headings, paragraphs, lists)
+- Output: a single, self-contained HTML file (no external CSS/fonts/scripts/images)
+- Readability over fidelity: no attempt to preserve original styling or branding
+- Optional font toggle: `--font opendyslexic` (not default)
+
+Full boundaries: see [SCOPE.md](SCOPE.md).
+
+## Status
+
+Phase 2 complete. Core pipeline built and tested against 11 real-world fixtures (8 clean passes, 1 marginal, 2 known limitations). Preparing for v1 open-source release.
+
+## Planned CLI
+
+```bash
+flowdoc convert input.html
+flowdoc convert input.html -o output.html
+flowdoc convert input.html --font opendyslexic
+```
+
+Print to PDF: open the output in a browser and use print-to-PDF.
+
+## Documentation
+
+- [SCOPE.md](SCOPE.md) - frozen v1 product boundaries and success criteria
+- [docs/decisions.md](docs/decisions.md) - authoritative implementation/test spec (contracts + invariants)
+- [docs/architecture.md](docs/architecture.md) - locked v1 implementation choices (runtime, libraries, module structure, pipeline, testing)
+- [docs/flowdoc-v1-plan.md](docs/flowdoc-v1-plan.md) - execution checklist for v1
+- [docs/flowdoc-v1-success-contract.md](docs/flowdoc-v1-success-contract.md) - locked v1 success contract (takes precedence over all other docs where conflicts exist)
+- [docs/research_typography_guidelines.md](docs/research_typography_guidelines.md) - typography research/reference
+- [flowdoc-elevator-pitch.md](flowdoc-elevator-pitch.md) - what Flowdoc is in 60 seconds
+- [docs/flowdoc-project-summary.md](docs/flowdoc-project-summary.md) - project history and context
+- [ABOUT.md](ABOUT.md) - project origin story and motivation
+
+## License
+
+[MIT](LICENSE)

decant_cli-0.1.0/decant/cli/main.py

@@ -0,0 +1,158 @@
+"""
+Decant CLI entry point.
+
+Provides convert command for HTML to readable HTML conversion.
+"""
+import argparse
+import sys
+
+from decant.core.content_selector import detect_mode
+from decant.core.parser import parse, extract_with_trafilatura, ValidationError, harvest_captions
+from decant.core.renderer import render
+from decant.io.reader import read_html
+from decant.io.writer import write_html
+
+
+def main():
+    """
+    Main CLI entry point.
+
+    Exit codes:
+    - 0: Success
+    - 1: Validation/parse error
+    - 2: Render error
+    - 3: I/O error
+    """
+    parser = argparse.ArgumentParser(
+        prog='decant',
+        description='Convert semantic HTML to accessible readable HTML'
+    )
+
+    parser.add_argument(
+        'input',
+        nargs='?',
+        help='Input HTML file (omit for stdin)'
+    )
+
+    parser.add_argument(
+        '-o', '--output',
+        help='Output file path (default: <input>.decant.html or stdout)'
+    )
+
+    parser.add_argument(
+        '--font',
+        choices=['opendyslexic'],
+        help='Use alternative font (opendyslexic)'
+    )
+
+    parser.add_argument(
+        '--mode',
+        choices=['transform', 'extract', 'auto'],
+        default='auto',
+        help=(
+            'Processing mode (default: auto). '
+            'transform: fidelity-first, no boilerplate removal. '
+            'extract: boilerplate removal via Trafilatura, formatting best-effort. '
+            'auto: detect mode from input (defaults to transform when ambiguous).'
+        )
+    )
+
+    parser.add_argument(
+        '--source-url',
+        default='',
+        help='URL of the original source page (used for "View original" links)'
+    )
+
+    parser.add_argument(
+        '--verbose',
+        action='store_true',
+        help='Print processing decisions to stderr'
+    )
+
+    args = parser.parse_args()
+
+    # Determine input/output paths
+    input_path = args.input
+    output_path = args.output
+
+    # If no output specified and reading from file, use default naming
+    if not output_path and input_path:
+        if input_path.endswith('.html'):
+            output_path = input_path.replace('.html', '.decant.html')
+        else:
+            output_path = input_path + '.decant.html'
+
+    # Font flag
+    use_opendyslexic = args.font == 'opendyslexic'
+
+    try:
+        # Read input
+        html_input = read_html(input_path)
+
+        # Determine mode
+        if args.mode == 'auto':
+            mode = detect_mode(html_input)
+            if args.verbose:
+                print(f"Mode: {mode} (auto-detected)", file=sys.stderr)
+        else:
+            mode = args.mode
+            if args.verbose:
+                print(f"Mode: {mode} (explicit)", file=sys.stderr)
+
+        # Route to appropriate pipeline
+        original_title = None
+        caption_map = None
+        if mode == 'extract':
+            # Capture title before Trafilatura strips <head>
+            from bs4 import BeautifulSoup
+            original_soup = BeautifulSoup(html_input, "lxml")
+            original_title = original_soup.find("title")
+
+            # Harvest captions before Trafilatura strips figcaptions
+            caption_map = harvest_captions(html_input)
+
+            if args.verbose:
+                print("Extract mode: running Trafilatura boilerplate removal", file=sys.stderr)
+
+            html_input = extract_with_trafilatura(html_input)
+
+            if args.verbose:
+                print("Extract mode: boilerplate removal complete", file=sys.stderr)
+        else:
+            if args.verbose:
+                print("Transform mode: fidelity-first parsing, no boilerplate removal", file=sys.stderr)
+
+        # Parse to model
+        document = parse(
+            html_input,
+            original_title=original_title,
+            require_article_body=(mode == "extract"),
+            caption_map=caption_map,
+            source_url=args.source_url,
+        )
+
+        # Render to readable HTML
+        html_output = render(document, use_opendyslexic=use_opendyslexic)
+
+        # Write output
+        write_html(html_output, output_path)
+
+        # Success
+        sys.exit(0)
+
+    except IOError as e:
+        print(f"I/O error: {e}", file=sys.stderr)
+        sys.exit(3)
+    except ValidationError as e:
+        print(str(e), file=sys.stderr)
+        sys.exit(1)
+    except ValueError as e:
+        print(f"Validation error: {e}", file=sys.stderr)
+        sys.exit(1)
+    except Exception as e:
+        print(f"Unexpected error: {e}", file=sys.stderr)
+        sys.exit(2)
+
+
+if __name__ == '__main__':
+    main()