nexus-cli 0.3.0__tar.gz → 0.5.2__tar.gz

nexus_cli-0.5.2/.STATUS

@@ -0,0 +1,174 @@
+status: active
+priority: 1
+progress: 30
+next: Start Session 1 — courses.py coverage (feature/courses-coverage worktree)
+type: dev
+checkpoint: 2026-06-02 — dev branch created, branch protection on main, 4 specs written, ORCHESTRATE plan ready. v0.6.0 target.
+version: 0.5.1
+release_date: 2025-12-31
+release_url: https://github.com/Data-Wise/nexus-cli/releases/tag/v0.5.1
+docs_url: https://data-wise.github.io/nexus-cli/
+planning_doc: ORCHESTRATE-nexus-enhancement.md
+
+worktrees:
+  - branch: feature/nexus-enhancement
+    path: ~/.git-worktrees/nexus-cli/nexus-enhancement
+    purpose: ORCHESTRATE plan (planning only — do not implement here)
+
+# ═══════════════════════════════════════════════════════════════════
+# Nexus CLI - Knowledge Workflow for Research, Teaching, Writing
+# ═══════════════════════════════════════════════════════════════════
+
+🔧 Nexus CLI Development Status
+────────────────────────────────────────
+
+📍 LOCATION
+~/projects/dev-tools/nexus-cli/
+
+⏰ LAST UPDATED
+2025-12-31 (Evening) - Quality Improvements Complete - Website Updated!
+
+────────────────────────────────────────
+
+🎉 RELEASE v0.5.1 - INTERACTIVE TUTORIAL SYSTEM
+
+**Learning & onboarding enhancement release!**
+
+Release highlights:
+- ✅ Interactive tutorial system (30 steps across 3 levels)
+- ✅ `nexus learn` command with pause/resume capability
+- ✅ Reduces onboarding time: ~2 hours → ~30 minutes (75% reduction)
+- ✅ 638 lines tutorial engine (no new dependencies)
+- ✅ 600+ lines comprehensive documentation
+- ✅ GitHub Release with binaries published
+- ✅ Documentation automatically deployed
+
+────────────────────────────────────────
+
+🎯 CURRENT STATUS
+
+**v0.5.1 SHIPPED** ✅
+
+All v0.5.1 features complete:
+- ✅ Tutorial Engine (nexus/utils/tutorial.py - 638 lines)
+- ✅ Three progressive levels (Getting Started, Medium, Advanced)
+- ✅ 30 total hands-on steps with real commands
+- ✅ Rich terminal formatting and interactive prompts
+- ✅ Pause/resume from any step
+- ✅ Comprehensive documentation (TUTORIAL_GUIDE.md + MkDocs)
+
+Tutorial content:
+- Getting Started (7 steps, ~10 min): doctor → config → detect → search
+- Medium (11 steps, ~20 min): Research, Knowledge, Teaching, Writing workflows
+- Advanced (12 steps, ~30 min): Batch ops, graph exports, Claude integration
+
+Release artifacts:
+- Git tag: v0.5.1
+- GitHub Release: https://github.com/Data-Wise/nexus-cli/releases/tag/v0.5.1
+- Built packages: nexus_cli-0.5.1-py3-none-any.whl, nexus_cli-0.5.1.tar.gz
+- Documentation: https://data-wise.github.io/nexus-cli/ (auto-deployed)
+
+────────────────────────────────────────
+
+📊 PROJECT METRICS (Updated 2025-12-31 - Evening)
+
+Version: 0.5.1
+Tests: 500 passing (76.65% coverage) ⬆️ +38 tests today, +78 total
+Commands: 50+ across 4 domains
+Tutorial Steps: 30 (7 + 11 + 12)
+Module Coverage:
+  - Tutorial: 94.2% (nexus/utils/tutorial.py) ✅
+  - Zotero: 96.89% (nexus/research/zotero.py) 🚀 NEW!
+Type Safety: 0 mypy errors (utils + zotero) ✅
+Documentation: 10,000+ lines (MkDocs)
+Python: 3.11+ required
+
+────────────────────────────────────────
+
+🎯 QUALITY IMPROVEMENTS IN PROGRESS (Dec 31, 2025)
+
+**Phase 1: Repository Cleanup** ✅ COMPLETE
+- [x] Fix CI failures (formatting)
+- [x] Archive old session notes
+- [x] Archive testing utilities
+- [x] Add release documentation
+
+**Phase 2: Tutorial Tests** ✅ COMPLETE
+- [x] Add 39 tests for tutorial system
+- [x] Achieve 94.2% coverage for tutorial.py
+- [x] Increase overall coverage to 75% (+21pp)
+
+**Phase 3: Type Improvements** ✅ COMPLETE
+- [x] Add types-PyYAML dependency
+- [x] Fix mypy errors in utils modules
+- [x] All utils modules type-safe (0 errors)
+
+**Phase 4: Zotero Tests** ✅ COMPLETE (2.3 hours)
+- [x] Add 38 tests for Zotero integration
+- [x] Achieve 96.89% coverage for zotero.py (+24.39pp!)
+- [x] Fix 4 mypy errors - now type-safe
+- [x] Enhanced mock database (7 items, 5 tags, 4 collections, attachments)
+- [x] Comprehensive edge case testing (SQL injection, Unicode, empty DB)
+- [x] All 71 Zotero tests passing
+
+**NEXT: Phase 5 - Knowledge Domain** (See PLANNING.md, SESSION_COMPLETE.md)
+
+**Option A: Continue Quality** (RECOMMENDED)
+- [ ] Add tests for research domain (Zotero)
+- [ ] Add tests for knowledge domain (Vault)
+- [ ] Increase coverage to 80%+
+- [ ] Fix mypy errors in core domains
+
+**Option B: New Features**
+- [ ] Tutorial completion tracking
+- [ ] Advanced graph features
+- [ ] Batch operations expansion
+- [ ] New integrations
+
+**Option C: Developer Experience**
+- [ ] Plugin system
+- [ ] Shell completion
+- [ ] Enhanced error messages
+- [ ] Configuration wizard
+
+**Option D: Documentation & Community**
+- [ ] Video tutorials
+- [ ] Blog posts/case studies
+- [ ] Community building
+- [ ] Marketing/outreach
+
+────────────────────────────────────────
+
+🔗 RELATED PROJECTS
+
+| Project | Status | Purpose |
+|---------|--------|---------|
+| Nexus CLI | ✅ v0.5.1 | This project |
+| aiterm | 📋 Spec PR #7 | Interactive tutorial spec (awaiting review) |
+| Nexus MCP Server | ✅ Active | 17 tools for Claude integration |
+
+────────────────────────────────────────
+
+📁 KEY FILES (Updated Dec 31, 2025)
+
+Core:
+- nexus/cli.py                  - Main CLI - 2,060 lines
+- nexus/utils/tutorial.py       - Tutorial engine - 638 lines (94.2% coverage)
+- nexus/utils/config.py         - Configuration - 86 lines (type-safe)
+- nexus/research/zotero.py      - Zotero integration - 523 lines (96.89% coverage!)
+- pyproject.toml                - Project metadata (v0.5.1)
+
+Documentation:
+- PLANNING.md                   - Development roadmap with blueprint
+- SESSION_COMPLETE.md           - Zotero testing deep dive
+- FINAL_SUMMARY.md              - Today's session wrap-up
+- docs/                         - MkDocs website (auto-deployed)
+
+Tests:
+- tests/test_tutorial.py        - Tutorial tests (39 tests, 94.2% coverage)
+- tests/test_zotero_client.py   - Zotero tests (71 tests, 96.89% coverage)
+
+────────────────────────────────────────
+
+✅ v0.5.1 RELEASED + QUALITY IMPROVEMENTS COMPLETE - 2025-12-31
+📊 500 tests, 76.65% coverage, 2 modules at 90%+, blueprint established

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

@@ -0,0 +1,143 @@
+name: CI
+
+on:
+  push:
+    branches: [ main, develop ]
+  pull_request:
+    branches: [ main, develop ]
+  workflow_dispatch:
+
+jobs:
+  test:
+    name: Test Python ${{ matrix.python-version }} on ${{ matrix.os }}
+    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 }}
+
+    - name: Install uv
+      uses: astral-sh/setup-uv@v4
+      with:
+        enable-cache: true
+
+    - name: Install dependencies
+      run: |
+        uv sync --all-extras
+
+    - name: Run linting
+      run: |
+        uv run ruff check nexus/
+      continue-on-error: true
+
+    - name: Run type checking
+      run: |
+        uv run mypy nexus/ --ignore-missing-imports
+      continue-on-error: true
+
+    - name: Run tests with coverage
+      run: |
+        uv run pytest --cov=nexus --cov-report=xml --cov-report=term -v
+
+    - name: Upload coverage to Codecov
+      uses: codecov/codecov-action@v4
+      if: matrix.os == 'ubuntu-latest' && matrix.python-version == '3.13'
+      with:
+        file: ./coverage.xml
+        flags: unittests
+        name: codecov-umbrella
+        fail_ci_if_error: false
+      env:
+        CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
+
+  lint:
+    name: Code Quality
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: "3.13"
+
+    - name: Install uv
+      uses: astral-sh/setup-uv@v4
+      with:
+        enable-cache: true
+
+    - name: Install dependencies
+      run: uv sync --all-extras
+
+    - name: Check code formatting with ruff
+      run: |
+        uv run ruff format --check nexus/ tests/
+
+    - name: Lint with ruff
+      run: |
+        uv run ruff check nexus/ tests/
+
+  type-check:
+    name: Type Checking
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: "3.13"
+
+    - name: Install uv
+      uses: astral-sh/setup-uv@v4
+      with:
+        enable-cache: true
+
+    - name: Install dependencies
+      run: uv sync --all-extras
+
+    - name: Run mypy
+      run: |
+        uv run mypy nexus/ --ignore-missing-imports --no-error-summary
+
+  coverage:
+    name: Coverage Report
+    runs-on: ubuntu-latest
+    needs: test
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: "3.13"
+
+    - name: Install uv
+      uses: astral-sh/setup-uv@v4
+      with:
+        enable-cache: true
+
+    - name: Install dependencies
+      run: uv sync --all-extras
+
+    - name: Generate coverage report
+      run: |
+        uv run pytest --cov=nexus --cov-report=html --cov-report=term
+
+    - name: Upload coverage HTML report
+      uses: actions/upload-artifact@v4
+      with:
+        name: coverage-report
+        path: htmlcov/
+        retention-days: 30

nexus_cli-0.5.2/.github/workflows/homebrew-release.yml

@@ -0,0 +1,62 @@
+name: Homebrew Release
+
+on:
+  workflow_run:
+    workflows: ["Publish to PyPI"]
+    types: [completed]
+  workflow_dispatch:
+    inputs:
+      version:
+        description: 'Version to release (e.g., 0.5.1)'
+        required: true
+        type: string
+      auto_merge:
+        description: 'Auto-merge the formula PR'
+        required: false
+        type: boolean
+        default: true
+
+jobs:
+  prepare:
+    name: Prepare Release Info
+    runs-on: ubuntu-latest
+    if: ${{ github.event.workflow_run.conclusion == 'success' || github.event_name == 'workflow_dispatch' }}
+    outputs:
+      version: ${{ steps.release.outputs.version }}
+      sha256: ${{ steps.release.outputs.sha256 }}
+
+    steps:
+      - name: Get version from PyPI
+        id: release
+        run: |
+          if [ "${{ github.event_name }}" = "workflow_dispatch" ]; then
+            VERSION="${{ github.event.inputs.version }}"
+          else
+            # Wait for PyPI to index the package
+            sleep 30
+            # Get latest version from PyPI
+            VERSION=$(curl -s https://pypi.org/pypi/nexus-cli/json | jq -r '.info.version')
+          fi
+
+          echo "version=$VERSION" >> $GITHUB_OUTPUT
+
+          # Get SHA256 from PyPI
+          SHA256=$(curl -s "https://pypi.org/pypi/nexus-cli/json" | \
+            jq -r ".releases[\"$VERSION\"][] | select(.packagetype==\"sdist\") | .digests.sha256")
+
+          echo "sha256=$SHA256" >> $GITHUB_OUTPUT
+          echo "Version: $VERSION"
+          echo "SHA256: $SHA256"
+
+  update-homebrew:
+    name: Update Homebrew Formula
+    needs: prepare
+    uses: Data-Wise/homebrew-tap/.github/workflows/update-formula.yml@main
+    with:
+      formula_name: nexus-cli
+      version: ${{ needs.prepare.outputs.version }}
+      sha256: ${{ needs.prepare.outputs.sha256 }}
+      source_type: pypi
+      auto_merge: ${{ github.event.inputs.auto_merge == 'true' || github.event_name == 'workflow_dispatch' }}
+    secrets:
+      tap_token: ${{ secrets.HOMEBREW_TAP_GITHUB_TOKEN }}

nexus_cli-0.5.2/.github/workflows/quality.yml

@@ -0,0 +1,110 @@
+name: Code Quality
+
+on:
+  push:
+    branches: [ main, develop ]
+  pull_request:
+    branches: [ main ]
+  workflow_dispatch:
+
+jobs:
+  lint:
+    name: Linting
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: "3.13"
+
+    - name: Install uv
+      uses: astral-sh/setup-uv@v4
+
+    - name: Install dependencies
+      run: uv sync --all-extras --dev
+
+    - name: Run ruff check
+      run: |
+        uv run ruff check nexus/ tests/ --output-format=github
+
+    - name: Run ruff format check
+      run: |
+        uv run ruff format --check nexus/ tests/
+
+  type-check:
+    name: Type Checking
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: "3.13"
+
+    - name: Install uv
+      uses: astral-sh/setup-uv@v4
+
+    - name: Install dependencies
+      run: uv sync --all-extras --dev
+
+    - name: Run mypy
+      run: |
+        uv run mypy nexus/ --ignore-missing-imports --show-error-codes
+      continue-on-error: true
+
+  security:
+    name: Security Scan
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: "3.13"
+
+    - name: Install uv
+      uses: astral-sh/setup-uv@v4
+
+    - name: Install dependencies
+      run: uv sync --all-extras --dev
+
+    - name: Run bandit security scan
+      run: |
+        uv run bandit -r nexus/ -f json -o bandit-report.json
+      continue-on-error: true
+
+    - name: Upload security report
+      uses: actions/upload-artifact@v4
+      if: always()
+      with:
+        name: security-scan-report
+        path: bandit-report.json
+        retention-days: 30
+
+  dependency-check:
+    name: Dependency Security
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: "3.13"
+
+    - name: Install uv
+      uses: astral-sh/setup-uv@v4
+
+    - name: Check for vulnerabilities
+      run: |
+        uv pip list --format=json > deps.json
+        echo "Dependency check complete"
+      continue-on-error: true

nexus_cli-0.5.2/.github/workflows/release.yml

@@ -0,0 +1,125 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+permissions:
+  contents: write
+  id-token: write
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - 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/
+
+  release:
+    needs: build
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Download artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Get version from tag
+        id: get_version
+        run: echo "VERSION=${GITHUB_REF#refs/tags/v}" >> $GITHUB_OUTPUT
+
+      - name: Generate changelog
+        id: changelog
+        run: |
+          # Get commits since last tag
+          LAST_TAG=$(git describe --tags --abbrev=0 HEAD^ 2>/dev/null || echo "")
+          if [ -z "$LAST_TAG" ]; then
+            COMMITS=$(git log --oneline --pretty=format:"- %s" | head -20)
+          else
+            COMMITS=$(git log --oneline --pretty=format:"- %s" ${LAST_TAG}..HEAD)
+          fi
+
+          # Create changelog
+          echo "CHANGELOG<<EOF" >> $GITHUB_OUTPUT
+          echo "## What's Changed" >> $GITHUB_OUTPUT
+          echo "" >> $GITHUB_OUTPUT
+          echo "$COMMITS" >> $GITHUB_OUTPUT
+          echo "" >> $GITHUB_OUTPUT
+          echo "**Full Changelog**: https://github.com/${{ github.repository }}/compare/${LAST_TAG}...v${{ steps.get_version.outputs.VERSION }}" >> $GITHUB_OUTPUT
+          echo "EOF" >> $GITHUB_OUTPUT
+
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v1
+        with:
+          name: v${{ steps.get_version.outputs.VERSION }}
+          body: ${{ steps.changelog.outputs.CHANGELOG }}
+          files: dist/*
+          draft: false
+          prerelease: ${{ contains(github.ref, 'alpha') || contains(github.ref, 'beta') || contains(github.ref, 'rc') }}
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+  publish-pypi:
+    needs: release
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    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
+
+  docs:
+    needs: release
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install dependencies
+        run: |
+          pip install mkdocs-material mkdocstrings[python] mkdocs-git-revision-date-localized-plugin
+
+      - name: Build and deploy docs
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          mkdocs gh-deploy --force