nexus-cli 0.3.0__tar.gz

nexus_cli-0.3.0/.STATUS

@@ -0,0 +1,169 @@
+status: complete
+priority: 1
+progress: 100
+next: Ready for production use
+type: dev
+checkpoint: v0.4.0 - 256 tests passing (53% coverage), GitHub Actions CI/CD configured
+
+# ═══════════════════════════════════════════════════════════════════
+# Nexus CLI - Knowledge Workflow for Research, Teaching, Writing
+# ═══════════════════════════════════════════════════════════════════
+
+🔧 Nexus CLI Development Status
+────────────────────────────────────────
+
+📍 LOCATION
+~/projects/dev-tools/nexus-cli/
+
+⏰ LAST UPDATED
+2025-12-25 - Test coverage expanded, CI/CD configured
+
+────────────────────────────────────────
+
+🎯 CURRENT STATUS
+**ALL PHASES COMPLETE - v0.4.0 PRODUCTION READY**
+
+Phase 9 test expansion completed:
+- ✅ 256 pytest tests passing (53% coverage, +10%)
+- ✅ GitHub Actions CI/CD configured (Python 3.11-3.13, Ubuntu/macOS)
+- ✅ PyPI publish workflow on release
+- ✅ QuartoManager tests (29 tests)
+- ✅ PDFExtractor tests (25 tests)
+- ✅ ZoteroClient tests (20+ tests)
+- ✅ MCP server with 17 tools
+- ✅ Validation, edge case, and integration tests
+- ✅ Claude Code plugin installed
+
+────────────────────────────────────────
+
+📊 PROGRESS
+
+Core Infrastructure:
+CLI Skeleton               ████████████████████ 100% ✅
+Configuration System       ████████████████████ 100% ✅
+Doctor Command             ████████████████████ 100% ✅
+Project Setup              ████████████████████ 100% ✅
+
+Domains:
+Phase 2: Knowledge         ████████████████████ 100% ✅
+Phase 3: Research          ████████████████████ 100% ✅
+Phase 4a: Teaching         ████████████████████ 100% ✅
+Phase 4b: Writing          ████████████████████ 100% ✅
+Phase 5: Claude Plugin     ████████████████████ 100% ✅
+Phase 6: Testing & Docs    ████████████████████ 100% ✅
+
+**Overall Progress**: 100% (v0.1.0 Release Ready)
+
+────────────────────────────────────────
+
+📋 ENHANCEMENTS COMPLETED (2025-12-25)
+
+v0.4.0 improvements (current):
+- [✅] Test coverage expanded (43% → 53%)
+- [✅] 256 tests total (79 new tests)
+- [✅] QuartoManager comprehensive tests
+- [✅] PDFExtractor with mock subprocess
+- [✅] ZoteroClient with mock SQLite database
+- [✅] GitHub Actions CI/CD configured
+
+v0.3.0 improvements:
+- [✅] 177 tests covering all domains
+- [✅] Validation tests for data models
+- [✅] Edge case and error handling
+- [✅] CLI integration tests
+
+v0.2.0 improvements:
+- [✅] MCP server for tool calling
+- [✅] PDF text extraction improvements
+- [✅] Vault graph visualization
+
+Future improvements:
+- [ ] Further test coverage improvements (target 80%)
+- [ ] MkDocs documentation site
+
+────────────────────────────────────────
+
+📊 TEST SUMMARY
+
+256 tests total, all passing (53% coverage):
+
+Core tests:
+- tests/test_config.py           - Config loading (3 tests)
+- tests/test_vault.py            - Vault operations (33 tests)
+- tests/test_manuscript.py       - Manuscript management (7 tests)
+- tests/test_bibliography.py     - Bibliography parsing (11 tests)
+- tests/test_courses.py          - Course management (10 tests)
+- tests/test_cli.py              - CLI commands (19 tests)
+- tests/test_zotero.py           - Zotero item (6 tests)
+- tests/test_pdf.py              - PDF document (4 tests)
+- tests/test_quarto.py           - Quarto project (4 tests)
+- tests/test_search.py           - Unified search (30 tests)
+
+Comprehensive tests:
+- tests/test_validation.py       - Data model validation (70 tests)
+- tests/test_cli_integration.py  - CLI integration (37 tests)
+- tests/test_edge_cases.py       - Edge cases & errors (46 tests)
+
+New in v0.4.0:
+- tests/test_quarto_manager.py   - QuartoManager (29 tests) ⭐ NEW
+- tests/test_pdf_extractor.py    - PDFExtractor (25 tests) ⭐ NEW
+- tests/test_zotero_client.py    - ZoteroClient (20+ tests) ⭐ NEW
+
+Coverage by module:
+- teaching/quarto.py: 91% | utils/config.py: 80%
+- research/pdf.py: 77% | writing/manuscript.py: 74%
+- research/zotero.py: 73% | writing/bibliography.py: 72%
+- teaching/courses.py: 70% | knowledge/vault.py: 66%
+- knowledge/search.py: 60%
+
+Run: `uv run pytest --cov=nexus`
+
+────────────────────────────────────────
+
+🔗 RELATED PROJECTS
+
+| Project | Location | Purpose |
+|---------|----------|---------|
+| Nexus MCP Server | ~/mcp-servers/nexus/ | MCP server with 17 tools ⭐ NEW |
+| Nexus (docs) | ~/projects/dev-tools/nexus/ | Architecture & vault template |
+| Scribe | ~/projects/dev-tools/scribe/ | Desktop capture app |
+| Statistical Research | ~/.claude/plugins/statistical-research/ | Existing plugin |
+
+────────────────────────────────────────
+
+💡 ARCHITECTURE
+
+**Claude Integration (No API Needed)**
+
+Four patterns:
+1. **MCP Server**: 17 tools via Model Context Protocol ⭐ NEW
+2. **Claude calls Nexus**: Claude runs `nexus` via Bash
+3. **Piping**: `nexus search | claude -p "summarize"`
+4. **Plugin skills**: Teach Claude how to use nexus
+
+**Four Domains**:
+- 🔬 Research: Zotero, PDFs, literature
+- 📚 Teaching: Courses, materials, Quarto
+- ✍️ Writing: Manuscripts, bibliography, LaTeX
+- 🧠 Knowledge: Vault, unified search
+
+────────────────────────────────────────
+
+📁 KEY FILES
+
+- nexus/cli.py                  - Main CLI (Typer) - 1800+ lines
+- nexus/utils/config.py         - Configuration
+- nexus/knowledge/vault.py      - VaultManager (Phase 2)
+- nexus/knowledge/search.py     - UnifiedSearch (Phase 2+3)
+- nexus/research/zotero.py      - ZoteroClient (Phase 3)
+- nexus/research/pdf.py         - PDFExtractor (Phase 3)
+- nexus/teaching/courses.py     - CourseManager (Phase 4a)
+- nexus/teaching/quarto.py      - QuartoManager (Phase 4a)
+- nexus/writing/manuscript.py   - ManuscriptManager (Phase 4b)
+- nexus/writing/bibliography.py - BibliographyManager (Phase 4b)
+- tests/                        - 58 pytest tests
+- pyproject.toml                - Project metadata
+- install.sh                    - Installation script
+- CLAUDE.md                     - Claude Code guidance
+- README.md                     - User documentation
+

nexus_cli-0.3.0/.github/workflows/ci.yml

@@ -0,0 +1,125 @@
+name: CI
+
+on:
+  push:
+    branches: [main, develop]
+  pull_request:
+    branches: [main, develop]
+
+jobs:
+  test:
+    name: Test on ${{ matrix.os }} with Python ${{ matrix.python-version }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+        python-version: ["3.11", "3.12", "3.13"]
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: 'pip'
+
+      - name: Install system dependencies (Ubuntu)
+        if: runner.os == 'Linux'
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y poppler-utils
+
+      - name: Install system dependencies (macOS)
+        if: runner.os == 'macOS'
+        run: |
+          brew install poppler
+
+      - name: Install Python dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+
+      - name: Run tests with coverage
+        run: |
+          pytest -v --cov=nexus --cov-report=xml --cov-report=term-missing --cov-report=html
+
+      - name: Generate coverage badge
+        if: matrix.os == 'ubuntu-latest' && matrix.python-version == '3.12'
+        run: |
+          pip install coverage-badge
+          coverage-badge -o coverage.svg -f
+
+      - name: Upload coverage reports to Codecov
+        uses: codecov/codecov-action@v4
+        if: matrix.os == 'ubuntu-latest' && matrix.python-version == '3.12'
+        with:
+          file: ./coverage.xml
+          fail_ci_if_error: false
+          verbose: true
+        env:
+          CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
+
+      - name: Archive code coverage results
+        uses: actions/upload-artifact@v4
+        if: matrix.os == 'ubuntu-latest' && matrix.python-version == '3.12'
+        with:
+          name: code-coverage-report
+          path: htmlcov/
+
+      - name: Check coverage threshold
+        if: matrix.os == 'ubuntu-latest' && matrix.python-version == '3.12'
+        run: |
+          coverage report --fail-under=40
+
+  lint:
+    name: Lint and Format Check
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: 'pip'
+
+      - name: Install linting tools
+        run: |
+          pip install ruff mypy
+
+      - name: Run ruff check
+        run: ruff check nexus/ tests/
+
+      - name: Run ruff format check
+        run: ruff format --check nexus/ tests/
+
+      - name: Run type checking
+        run: mypy nexus/ --ignore-missing-imports || true
+
+  security:
+    name: Security Scan
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install bandit
+        run: pip install bandit[toml]
+
+      - name: Run security scan
+        run: bandit -r nexus/ -f json -o bandit-report.json || true
+
+      - name: Upload security report
+        uses: actions/upload-artifact@v4
+        with:
+          name: security-report
+          path: bandit-report.json

nexus_cli-0.3.0/.github/workflows/docs.yml

@@ -0,0 +1,43 @@
+name: Deploy Documentation
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - 'docs/**'
+      - 'mkdocs.yml'
+      - '.github/workflows/docs.yml'
+  workflow_dispatch:
+
+permissions:
+  contents: write
+
+jobs:
+  deploy:
+    name: Deploy MkDocs to GitHub Pages
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+          cache: 'pip'
+
+      - name: Install dependencies
+        run: |
+          pip install -e ".[docs]"
+
+      - name: Configure Git user
+        run: |
+          git config --global user.name "GitHub Actions"
+          git config --global user.email "actions@github.com"
+
+      - name: Deploy documentation
+        run: |
+          mkdocs gh-deploy --force --clean --verbose

nexus_cli-0.3.0/.github/workflows/publish.yml

@@ -0,0 +1,44 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build dependencies
+        run: pip install build
+
+      - name: Build package
+        run: python -m build
+
+      - name: Upload artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish-pypi:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write  # Required for trusted publishing
+    steps:
+      - name: Download artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

nexus_cli-0.3.0/.gitignore

@@ -0,0 +1,27 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+
+# Testing
+.coverage
+htmlcov/
+coverage.xml
+coverage.svg
+.pytest_cache/
+bandit-report.json
+
+# IDEs
+.vscode/
+.idea/
+*.swp
+*~
+
+# OS
+.DS_Store

nexus_cli-0.3.0/.python-version

@@ -0,0 +1 @@
+3.14

nexus_cli-0.3.0/CLAUDE.md

@@ -0,0 +1,199 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code when working with the Nexus CLI.
+
+## What is Nexus?
+
+Nexus is a **knowledge workflow CLI** for academic researchers. It provides data and operations - Claude provides the thinking.
+
+**Key Principle**: Nexus does NOT do AI. It provides structured access to:
+- Zotero library (2,728 papers)
+- PDFs (~1,800 files)
+- Obsidian vault (knowledge notes)
+- Teaching materials
+- Manuscripts
+
+## Repository Structure
+
+```
+nexus-cli/
+├── nexus/                    # Python package
+│   ├── cli.py               # Main CLI (Typer)
+│   ├── research/            # 🔬 Zotero, PDFs, literature
+│   ├── teaching/            # 📚 Courses, materials
+│   ├── writing/             # ✍️ Manuscripts, LaTeX
+│   ├── knowledge/           # 🧠 Vault, search
+│   ├── integrations/        # 🔌 aiterm, R, Git
+│   └── utils/               # Config, output
+│       └── config.py        # Configuration management
+│
+├── plugin/                   # Claude Code plugin
+│   ├── skills/              # Domain skills
+│   └── commands/            # Slash commands
+│
+├── config/                   # Default configs
+├── tests/                    # pytest tests
+├── docs/                     # MkDocs documentation
+├── pyproject.toml           # Project metadata
+└── README.md
+```
+
+## CLI Architecture
+
+The CLI uses **Typer** with nested subcommands:
+
+```bash
+nexus                        # Main app
+├── research                 # 🔬 Research domain
+│   ├── zotero              # Zotero operations
+│   │   ├── search          # Search papers
+│   │   └── cite            # Generate citations
+│   ├── pdf                 # PDF operations
+│   │   ├── extract         # Extract text
+│   │   └── search          # Search PDFs
+│   └── lit                 # Literature ops
+├── teach                    # 📚 Teaching domain
+│   ├── course              # Course management
+│   └── material            # Materials search
+├── write                    # ✍️ Writing domain
+│   ├── manuscript          # Manuscript tracking
+│   ├── bib                 # Bibliography
+│   └── latex               # LaTeX helpers
+├── knowledge                # 🧠 Knowledge domain
+│   ├── vault               # Obsidian operations
+│   └── search              # Unified search
+├── integrate                # 🔌 Integrations
+├── doctor                   # Health check
+└── config                   # Configuration
+```
+
+## Development Commands
+
+```bash
+# Install dependencies
+uv sync
+
+# Run CLI
+uv run nexus --help
+uv run nexus doctor
+
+# Run tests
+uv run pytest
+
+# Type check
+uv run mypy nexus/
+
+# Lint
+uv run ruff check nexus/
+```
+
+## Configuration
+
+Configuration is stored at `~/.config/nexus/config.yaml`:
+
+```yaml
+zotero:
+  database: ~/Zotero/zotero.sqlite
+  storage: ~/Zotero/storage
+
+vault:
+  path: ~/Obsidian/Nexus
+  templates: ~/Obsidian/Nexus/_SYSTEM/templates
+
+pdf:
+  directories:
+    - ~/Documents/Research/PDFs
+    - ~/Documents/Teaching/PDFs
+```
+
+## Adding New Commands
+
+1. **Find the domain** in `nexus/cli.py`
+2. **Add a subcommand** using the `@<domain>_app.command()` decorator
+3. **Use Typer Annotations** for arguments and options
+4. **Output with Rich** for beautiful formatting
+
+Example:
+```python
+@research_app.command()
+def new_command(
+    query: Annotated[str, typer.Argument(help="The query")],
+    limit: Annotated[int, typer.Option("--limit", "-n")] = 10,
+) -> None:
+    """Description of the command."""
+    console.print(f"Running with query: {query}")
+```
+
+## Adding Domain Logic
+
+1. Create a module in the domain folder (e.g., `nexus/research/zotero.py`)
+2. Create a class or functions for the operations
+3. Import and use in `cli.py`
+
+Example:
+```python
+# nexus/research/zotero.py
+class ZoteroClient:
+    def __init__(self, db_path: Path):
+        self.db_path = db_path
+
+    def search(self, query: str) -> List[dict]:
+        # Implementation
+        ...
+
+# nexus/cli.py
+from nexus.research.zotero import ZoteroClient
+
+@zotero_app.command("search")
+def zotero_search(query: str) -> None:
+    client = ZoteroClient(config.zotero.database)
+    results = client.search(query)
+    # Display results
+```
+
+## Claude Integration Patterns
+
+### Pattern 1: Claude Calls Nexus (Primary)
+```bash
+# In Claude Code, Claude runs:
+nexus research zotero search "mediation" --json
+```
+
+### Pattern 2: Pipe to Claude
+```bash
+nexus knowledge search "topic" --json | claude -p "Summarize"
+```
+
+### Pattern 3: Plugin Skills
+Skills in `plugin/skills/` teach Claude how to use nexus effectively.
+
+## Testing
+
+```bash
+# Run all tests
+uv run pytest
+
+# Run specific domain
+uv run pytest tests/research/
+
+# With coverage
+uv run pytest --cov=nexus
+```
+
+## Code Style
+
+- **Line length**: 100 characters
+- **Formatting**: Ruff
+- **Type hints**: Required (mypy strict)
+- **Docstrings**: Google style
+
+## Implementation Phases
+
+| Phase | Focus | Hours | Status |
+|-------|-------|-------|--------|
+| 1 | Core Infrastructure | 4h | ✅ Done |
+| 2 | Knowledge Domain | 3h | Next |
+| 3 | Research Domain | 4h | Pending |
+| 4 | Teaching & Writing | 3h | Pending |
+| 5 | Claude Plugin | 3h | Pending |
+| 6 | Testing & Docs | 3h | Pending |