Claude/project review ynoju5

.github/workflows/ci.yml

@@ -7,51 +7,28 @@ on:
     branches: [ main ]
 
 jobs:
-  matrix-test:
-    name: Python ${{ matrix.python-version }} Matrix Test
+  test:
+    name: Python ${{ matrix.python-version }}
     runs-on: ubuntu-latest
     strategy:
+      fail-fast: false
       matrix:
-        python-version: ['3.8', '3.9', '3.10', '3.11', '3.12', '3.13']
+        python-version: ['3.10', '3.11', '3.12', '3.13', '3.14']
     steps:
     - uses: actions/checkout@v4
+      with:
+        fetch-depth: 0  # Required for setuptools_scm
     - uses: actions/setup-python@v5
       with:
         python-version: ${{ matrix.python-version }}
         cache: 'pip'
-    - name: Install dependencies
+    - name: Install package
       run: |
         python -m pip install --upgrade pip
-        pip install pytest beautifulsoup4 ruff
-    - name: Run ruff
+        pip install -e ".[dev]"
+    - name: Lint
       run: |
         ruff check .
         ruff format --check .
-    - name: Install package
-      run: pip install -e .
-    - name: Run tests
+    - name: Test
       run: pytest -v
-
-  tox-test:
-    name: Tox Test with UV
-    runs-on: ubuntu-latest
-    steps:
-    - uses: actions/checkout@v4
-      with:
-        fetch-depth: 0  # Required for setuptools_scm
-    - uses: actions/setup-python@v5
-      with:
-        python-version: '3.13'
-        cache: 'pip'
-    - name: Install uv and tox
-      run: |
-        python -m pip install --upgrade pip
-        pip install uv
-        uv tool install tox --with tox-uv
-    - name: Run tox with UV
-      run: |
-        echo "Current directory: $(pwd)"
-        ls -la
-        echo "Content of pyproject.toml:"
-        cat pyproject.toml
-        PYTHONPATH=/home/runner/work/mdtk/mdtk tox r --verbose

.github/workflows/publish.yml

@@ -5,22 +5,46 @@ on:
     types: [published]
 
 jobs:
-  publish:
+  test:
     runs-on: ubuntu-latest
     steps:
     - uses: actions/checkout@v4
       with:
-        fetch-depth: 0
+        fetch-depth: 0  # Required for setuptools_scm
     - uses: actions/setup-python@v5
       with:
-        python-version: '3.13'
+        python-version: '3.x'
         cache: 'pip'
+    - name: Install package
+      run: |
+        python -m pip install --upgrade pip
+        pip install -e ".[dev]"
+    - name: Lint and test
+      run: |
+        ruff check .
+        ruff format --check .
+        pytest
+
+  publish:
+    needs: test
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/mdtk
+    permissions:
+      id-token: write  # Required for PyPI trusted publishing (OIDC)
+    steps:
+    - uses: actions/checkout@v4
+      with:
+        fetch-depth: 0  # Required for setuptools_scm
+    - uses: actions/setup-python@v5
+      with:
+        python-version: '3.x'
     - name: Build package
       run: |
         python -m pip install --upgrade pip
-        pip install build
+        pip install build twine
         python -m build
+        twine check dist/*
     - name: Publish to PyPI
       uses: pypa/gh-action-pypi-publish@release/v1
-      with:
-        password: ${{ secrets.PYPI_API_TOKEN }}

LICENSE

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

README.md

@@ -2,12 +2,84 @@
 
 Tools for working with markdown files.
 
+[![PyPI version](https://img.shields.io/pypi/v/mdtk.svg)](https://pypi.org/project/mdtk/)
+[![CI](https://github.com/tommcd/mdtk/actions/workflows/ci.yml/badge.svg)](https://github.com/tommcd/mdtk/actions/workflows/ci.yml)
+[![Documentation](https://img.shields.io/badge/docs-latest-blue.svg)](https://tommcd.github.io/mdtk)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](https://github.com/tommcd/mdtk/blob/main/LICENSE)
+
 ## Installation
 
 ```bash
 pip install mdtk
 ```
 
-## Features
+Requires Python 3.10+.
+
+## Usage
+
+### Chrome bookmarks to markdown
+
+1. In Chrome, open the bookmark manager (`chrome://bookmarks`), put the links
+   you want to export into one folder, and use **Export bookmarks** to save an
+   HTML file.
+2. Convert that folder to a markdown link list:
+
+```bash
+mdtk-bookmarks bookmarks.html links.md --folder "Reading List"
+```
+
+```console
+$ cat links.md
+- [GitHub - Where the world builds software](https://github.com)
+- [Welcome to Python.org](https://python.org)
+```
+
+Options:
+
+- `--folder NAME` - the bookmark folder to extract (default: `EXPORT_FOLDER`)
+- `--version` - print the mdtk version and exit
+
+Behavior notes:
+
+- Bookmarks inside nested subfolders are included, flattened in document order.
+- If several folders share the same name, the first one in the file is used.
+- Titles and URLs are escaped so the generated markdown links stay valid.
+- If the folder is not found, the error message lists the folders the export
+  does contain.
+
+### Python API
+
+```python
+from mdtk import BookmarkError, convert_bookmarks
+
+count = convert_bookmarks("bookmarks.html", "links.md", folder_name="Reading List")
+print(f"exported {count} bookmarks")
+```
+
+`convert_bookmarks` returns the number of bookmarks written and raises
+`BookmarkError` for anything that goes wrong (missing file, unknown folder,
+input that is not a bookmarks export, ...).
+
+## Development
+
+```bash
+git clone https://github.com/tommcd/mdtk.git
+cd mdtk
+pip install -e ".[dev]"
+
+pytest                # run the tests
+ruff check .          # lint
+ruff format --check . # formatting
+tox                   # everything, on all supported Python versions
+```
+
+## Links
+
+- [Documentation](https://tommcd.github.io/mdtk)
+- [PyPI package](https://pypi.org/project/mdtk/)
+- [Issue tracker](https://github.com/tommcd/mdtk/issues)
+- [Changelog](https://github.com/tommcd/mdtk/releases)
+
+## License
 
-- Chrome bookmarks to markdown converter
+[MIT](https://github.com/tommcd/mdtk/blob/main/LICENSE)