resolves 16: refactor article cli lifecycle commands and add robust setupdoctor workflows

.github/workflows/ci.yml

@@ -10,39 +10,48 @@ jobs:
   test:
     runs-on: ubuntu-latest
     strategy:
+      fail-fast: false
       matrix:
-        python-version: [3.8, 3.9, "3.10", "3.11", "3.12"]
+        python-version: [3.9, "3.10", "3.11", "3.12", "3.13"]
 
     steps:
     - uses: actions/checkout@v4
-    
-    - name: Set up Python ${{ matrix.python-version }}
-      uses: actions/setup-python@v5
+
+    - name: Set up uv
+      uses: astral-sh/setup-uv@v8.1.0
       with:
-        python-version: ${{ matrix.python-version }}
-
-    - name: Install dependencies
+        version: "latest"
+        enable-cache: true
+
+    - name: Set up Python ${{ matrix.python-version }}
+      run: uv python install ${{ matrix.python-version }}
+
+    - name: Install dependencies with uv
       run: |
-        python -m pip install --upgrade pip
-        pip install -e .
-        pip install pytest black flake8 mypy types-requests
-
+        uv sync --all-extras --dev --python ${{ matrix.python-version }}
+
     - name: Lint with flake8
       run: |
-        flake8 src/ --count --select=E9,F63,F7,F82 --show-source --statistics
-        flake8 src/ --count --exit-zero --max-complexity=10 --max-line-length=127 --statistics
-    
+        uv run flake8 src/ --count --select=E9,F63,F7,F82 --show-source --statistics
+        uv run flake8 src/ --count --exit-zero --max-complexity=10 --max-line-length=127 --statistics
+
     - name: Check formatting with black
-      run: black --check src/
-    
+      run: uv run black --check src tests
+
     - name: Type check with mypy
-      run: mypy src/
-
+      run: uv run mypy src/
+
+    - name: Run tests
+      run: uv run pytest
+
     - name: Test CLI installation
       run: |
-        article-cli --version
-        article-cli --help
-
+        uv run article-cli --version
+        uv run article-cli --help
+        uv run article-cli doctor --help
+        uv run article-cli doctor --json > article-cli-doctor.json || true
+        python -m json.tool article-cli-doctor.json > /dev/null
+
     - name: Generate test summary
       if: always()
       run: |
@@ -51,6 +60,7 @@ jobs:
         echo "- ✅ Formatting (black): Passed" >> $GITHUB_STEP_SUMMARY  
         echo "- ✅ Type checking (mypy): Passed" >> $GITHUB_STEP_SUMMARY
         echo "- ✅ CLI installation: Passed" >> $GITHUB_STEP_SUMMARY
+        echo "- ✅ Doctor JSON smoke test: Passed" >> $GITHUB_STEP_SUMMARY
 
   build:
     needs: test
@@ -59,23 +69,25 @@ jobs:
 
     steps:
     - uses: actions/checkout@v4
-    
-    - name: Set up Python
-      uses: actions/setup-python@v5
+
+    - name: Set up uv
+      uses: astral-sh/setup-uv@v8.1.0
       with:
-        python-version: "3.11"
-
-    - name: Install build dependencies
-      run: |
-        python -m pip install --upgrade pip
-        pip install build twine
-
+        version: "latest"
+        enable-cache: true
+
+    - name: Set up Python
+      run: uv python install 3.11
+
+    - name: Install dependencies with uv
+      run: uv sync --all-extras --dev --python 3.11
+
     - name: Build package
-      run: python -m build
-    
+      run: uv build
+
     - name: Check package
-      run: twine check dist/*
-    
+      run: uv run twine check dist/*
+
     - name: Upload artifacts
       uses: actions/upload-artifact@v4
       with:
@@ -93,4 +105,4 @@ jobs:
         echo "### 📋 Package Details" >> $GITHUB_STEP_SUMMARY
         echo "\`\`\`" >> $GITHUB_STEP_SUMMARY
         ls -la dist/ >> $GITHUB_STEP_SUMMARY
-        echo "\`\`\`" >> $GITHUB_STEP_SUMMARY
+        echo "\`\`\`" >> $GITHUB_STEP_SUMMARY

.github/workflows/docs.yml

@@ -0,0 +1,53 @@
+name: Documentation
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: npm
+
+      - name: Install documentation dependencies
+        run: npm ci
+
+      - name: Build Antora site
+        run: npm run docs:build
+
+      - name: Upload Pages artifact
+        if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: build/site
+
+  deploy:
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.github/workflows/publish.yml

@@ -13,20 +13,19 @@ jobs:
 
     steps:
     - uses: actions/checkout@v4
-    
-    - name: Set up Python
-      uses: actions/setup-python@v5
+
+    - name: Set up uv
+      uses: astral-sh/setup-uv@v8.1.0
       with:
-        python-version: "3.11"
-
-    - name: Install dependencies
-      run: |
-        python -m pip install --upgrade pip
-        pip install build
-
+        version: "latest"
+        enable-cache: true
+
+    - name: Set up Python
+      run: uv python install 3.11
+
     - name: Build package
-      run: python -m build
-    
+      run: uv build
+
     - name: Publish to PyPI
       uses: pypa/gh-action-pypi-publish@release/v1
       # Uses trusted publishing - no tokens needed!
@@ -45,5 +44,5 @@ jobs:
         echo "" >> $GITHUB_STEP_SUMMARY
         echo "### 📋 Installation" >> $GITHUB_STEP_SUMMARY
         echo "\`\`\`bash" >> $GITHUB_STEP_SUMMARY
-        echo "pip install --upgrade article-cli" >> $GITHUB_STEP_SUMMARY
-        echo "\`\`\`" >> $GITHUB_STEP_SUMMARY
+        echo "uv tool install article-cli" >> $GITHUB_STEP_SUMMARY
+        echo "\`\`\`" >> $GITHUB_STEP_SUMMARY

.gitignore

@@ -27,6 +27,16 @@ share/python-wheels/
 *.egg
 MANIFEST
 
+# Node / Antora documentation
+node_modules/
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+# Generated/downloaded font assets
+fonts/
+fonts-test/
+
 # PyInstaller
 #  Usually these files are written by a python script from a template
 #  before PyInstaller builds the exe, so as to inject date/other infos into it.
@@ -139,4 +149,4 @@ dmypy.json
 Thumbs.db
 
 # Test configurations
-test-config.toml
+test-config.toml

DEVELOPMENT.md

@@ -22,27 +22,26 @@ This guide helps you set up the article-cli package for development and distribu
        └── test_config.py
    ```
 
-2. **Install in development mode**:
+2. **Install development dependencies with uv**:
    ```bash
    cd article-cli-package
-   pip install -e .
+   uv sync --all-extras --dev
    ```
 
-3. **Install development dependencies**:
+3. **Run checks through uv**:
    ```bash
-   pip install -e ".[dev]"
+   uv run pytest
+   uv run black --check src tests
+   uv run mypy src
    ```
 
 ## Building and Publishing
 
 ### Build the Package
 
 ```bash
-# Install build tool
-pip install build
-
 # Build the package
-python -m build
+uv build
 ```
 
 This creates `dist/` directory with:
@@ -52,35 +51,30 @@ This creates `dist/` directory with:
 ### Test the Package Locally
 
 ```bash
-# Install from wheel
-pip install dist/article_cli-1.0.0-py3-none-any.whl
+# Install the local wheel into uv's tool environment
+uv tool install dist/article_cli-1.0.0-py3-none-any.whl --force
 
 # Test the CLI
 article-cli --help
 ```
 
 ### Publish to PyPI
 
-1. **Install twine**:
-   ```bash
-   pip install twine
-   ```
-
-2. **Test upload to TestPyPI first**:
+1. **Test upload to TestPyPI first**:
    ```bash
    # Register at https://test.pypi.org/ first
-   twine upload --repository testpypi dist/*
+   uv run twine upload --repository testpypi dist/*
    ```
 
-3. **Install from TestPyPI to verify**:
+2. **Install from TestPyPI to verify**:
    ```bash
-   pip install --index-url https://test.pypi.org/simple/ article-cli
+   uv tool install --index-url https://test.pypi.org/simple/ article-cli
    ```
 
-4. **Upload to real PyPI**:
+3. **Upload to real PyPI**:
    ```bash
    # Register at https://pypi.org/ first
-   twine upload dist/*
+   uv run twine upload dist/*
    ```
 
 ## Migration Strategy
@@ -100,8 +94,8 @@ article-cli --help
    # Remove old a.cli
    rm a.cli
 
-   # Create requirements.txt
-   echo "article-cli>=1.0.0" > requirements.txt
+   # Create or update pyproject.toml with article-cli as a dependency
+   uv add article-cli
 
    # Update setup instructions in README
    ```
@@ -111,15 +105,12 @@ article-cli --help
    #!/bin/bash
    echo "Setting up article repository..."
 
-   # Install article-cli
-   pip install article-cli
-
-   # Setup git hooks
-   article-cli setup
+   # Run article-cli from uv
+   uvx article-cli setup
 
    # Create local config if it doesn't exist
    if [ ! -f .article-cli.toml ]; then
-       article-cli config create
+       uvx article-cli config create
        echo "Please edit .article-cli.toml with your Zotero credentials"
    fi
 
@@ -137,7 +128,7 @@ For each existing article repository:
 
 2. **Install the package**:
    ```bash
-   pip install article-cli
+   uv tool install article-cli
    ```
 
 3. **Create local configuration**:
@@ -196,7 +187,7 @@ auto_push = true
 ## Benefits of This Approach
 
 1. **Centralized Maintenance**: Update once, benefit everywhere
-2. **Easy Installation**: `pip install article-cli`
+2. **Easy Installation**: `uv tool install article-cli`
 3. **Configuration Management**: Project-specific and global settings
 4. **Better Error Handling**: Improved user experience
 5. **Documentation**: Comprehensive help and examples
@@ -207,15 +198,15 @@ auto_push = true
 
 ```bash
 # Run tests
-pytest tests/
+uv run pytest
 
 # Run with coverage
-pytest --cov=article_cli tests/
+uv run pytest --cov=article_cli
 
 # Lint code
-flake8 src/
-black src/ tests/
-mypy src/
+uv run flake8 src/
+uv run black src tests
+uv run mypy src/
 ```
 
 ## Continuous Updates
@@ -225,4 +216,4 @@ When you need to update the tool:
 1. Make changes to the source code
 2. Update version in `pyproject.toml`
 3. Build and publish new version
-4. Users update with: `pip install --upgrade article-cli`
+4. Users update with: `uv tool upgrade article-cli`