nexus-dev 1.0.0__tar.gz

nexus_dev-1.0.0/.agent/workflows/index-code.md

@@ -0,0 +1,46 @@
+---
+description: Index new files after creating important modules
+---
+
+# Index New Code Workflow
+
+Use this workflow after creating new important files to add them to the knowledge base.
+
+## Steps
+
+1. After creating a new file, index it:
+   ```
+   index_file("<path/to/new/file.py>")
+   ```
+
+2. Verify it was indexed:
+   ```
+   search_code("<main function or class name from new file>")
+   ```
+
+## When to Index
+
+**DO index:**
+- New modules with reusable functions or classes
+- New API endpoints or handlers
+- Configuration files with important settings
+- Important utility functions
+
+**DON'T index (automatically handled by reindex):**
+- Test files
+- Generated files
+- Temporary or scratch files
+
+## Bulk Reindex
+
+To reindex the entire project:
+// turbo
+```bash
+cd /Users/mmornati/Projects/nexus-dev && nexus-reindex --yes
+```
+
+## When to Use
+
+- After creating a new important source file
+- After major refactoring that changes file structure
+- When you notice search results are stale

nexus_dev-1.0.0/.agent/workflows/record-lesson.md

@@ -0,0 +1,44 @@
+---
+description: Record a debugging lesson after solving a problem
+---
+
+# Record Lesson Workflow
+
+Use this workflow after solving a non-trivial bug or problem to save it for future reference.
+
+## Steps
+
+1. Identify the problem you just solved
+   - What error or unexpected behavior occurred?
+   - What file(s) were affected?
+
+2. Document the solution:
+   ```
+   record_lesson(
+       problem="<clear description of the problem>",
+       solution="<how you fixed it>",
+       context="<file path or additional context>"
+   )
+   ```
+
+3. Verify the lesson was recorded:
+   ```
+   search_lessons("<keywords from your problem>")
+   ```
+
+## Example
+
+```
+record_lesson(
+    problem="TypeError: Cannot read property 'id' of undefined when fetching user",
+    solution="Added null check before accessing user.id, return early if user is undefined",
+    context="src/services/user_service.py line 45"
+)
+```
+
+## When to Use
+
+- After fixing a bug that took more than a few minutes
+- After solving a tricky edge case
+- After debugging a configuration issue
+- After resolving a dependency conflict

nexus_dev-1.0.0/.agent/workflows/search-first.md

@@ -0,0 +1,49 @@
+---
+description: Search the knowledge base before implementing a feature
+---
+
+# Search Before Implementing Workflow
+
+Use this workflow before writing new code to find existing implementations and patterns.
+
+## Steps
+
+1. Search for similar existing code:
+   ```
+   search_code("<feature or function description>")
+   ```
+
+2. Check documentation for guidance:
+   ```
+   search_docs("<topic or configuration>")
+   ```
+
+3. Look for relevant lessons:
+   ```
+   search_lessons("<potential issues in this area>")
+   ```
+
+4. Review results and identify:
+   - Existing patterns to follow
+   - Potential pitfalls to avoid
+   - Related code that might need updates
+
+## Example: Implementing User Authentication
+
+```
+# Find existing auth code
+search_code("authentication login")
+
+# Check for auth documentation
+search_docs("authentication setup")
+
+# Look for past auth issues
+search_lessons("authentication error")
+```
+
+## When to Use
+
+- Before implementing any new feature
+- Before refactoring existing code
+- When you're unsure how something is currently done
+- When joining a new area of the codebase

nexus_dev-1.0.0/.agent/workflows/start-session.md

@@ -0,0 +1,30 @@
+---
+description: Start a coding session with Nexus-Dev knowledge base
+---
+
+# Start Session Workflow
+
+Use this workflow at the beginning of any coding session to load context from the knowledge base.
+
+## Steps
+
+1. Get project context to understand what's indexed:
+   ```
+   get_project_context()
+   ```
+
+2. If working on a specific area, search for relevant code:
+   ```
+   search_code("<feature or component name>")
+   ```
+
+3. Check for any relevant lessons from past debugging:
+   ```
+   search_lessons("<area you're working on>")
+   ```
+
+## When to Use
+
+- At the start of any new coding session
+- When switching to a different part of the codebase
+- Before implementing a new feature

nexus_dev-1.0.0/.github/workflows/ci.yml

@@ -0,0 +1,122 @@
+# Nexus-Dev CI Pipeline
+# =====================
+# Validates code quality, runs tests, and publishes coverage
+
+name: CI
+
+on:
+  push:
+    branches: [main, develop]
+  pull_request:
+    branches: [main]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  lint:
+    name: Code Quality
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python 3.13
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.13'
+
+      - name: Cache pip dependencies
+        uses: actions/cache@v4
+        with:
+          path: ~/.cache/pip
+          key: ${{ runner.os }}-pip-${{ hashFiles('pyproject.toml') }}
+          restore-keys: |
+            ${{ runner.os }}-pip-
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+
+      - name: Run linter (ruff)
+        run: ruff check src/ tests/
+
+      - name: Check formatting (ruff format)
+        run: ruff format --check src/ tests/
+
+      - name: Run type checker (mypy)
+        run: mypy src/
+
+  test:
+    name: Tests
+    runs-on: ubuntu-latest
+    needs: lint
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python 3.13
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.13'
+
+      - name: Cache pip dependencies
+        uses: actions/cache@v4
+        with:
+          path: ~/.cache/pip
+          key: ${{ runner.os }}-pip-${{ hashFiles('pyproject.toml') }}
+          restore-keys: |
+            ${{ runner.os }}-pip-
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+
+      - name: Run tests with coverage
+        run: |
+          pytest tests/ -v \
+            --cov=nexus_dev \
+            --cov-report=xml \
+            --cov-report=term-missing \
+            --cov-fail-under=45
+
+      - name: Upload coverage to Codecov
+        uses: codecov/codecov-action@v5
+        with:
+          token: ${{ secrets.CODECOV_TOKEN }}
+          files: ./coverage.xml
+          flags: unittests
+          name: nexus-dev-coverage
+          fail_ci_if_error: false
+          verbose: true
+
+  build:
+    name: Build Package
+    runs-on: ubuntu-latest
+    needs: test
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python 3.13
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.13'
+
+      - name: Install build dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install build
+
+      - name: Build package
+        run: python -m build
+
+      - name: Upload build artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+          retention-days: 7

nexus_dev-1.0.0/.github/workflows/create-release.yml

@@ -0,0 +1,114 @@
+name: Create Release
+
+on:
+  workflow_dispatch:
+    inputs:
+      version:
+        description: 'Version number (e.g., v1.0.0)'
+        required: true
+        type: string
+
+permissions:
+  contents: write
+  id-token: write
+
+jobs:
+  prepare_release:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Configure Git
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+
+      - name: Check and Update Version
+        id: version_check
+        run: |
+          VERSION="${{ inputs.version }}"
+          # Remove 'v' prefix for pyproject.toml
+          VERSION_NO_V="${VERSION#v}"
+
+          # Get current version from pyproject.toml
+          # Assumes version = "x.y.z" format
+          CURRENT_VERSION=$(grep -m1 '^version = ' pyproject.toml | cut -d'"' -f2)
+
+          echo "Current version: ${CURRENT_VERSION}"
+          echo "Requested version: ${VERSION_NO_V}"
+
+          if [ "${CURRENT_VERSION}" = "${VERSION_NO_V}" ]; then
+            echo "Version is already correct in pyproject.toml"
+            echo "needs_update=false" >> "$GITHUB_OUTPUT"
+          else
+            echo "Updating pyproject.toml from ${CURRENT_VERSION} to ${VERSION_NO_V}"
+            sed -i "s/^version = \"${CURRENT_VERSION}\"/version = \"${VERSION_NO_V}\"/" pyproject.toml
+            echo "needs_update=true" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Commit Version Update
+        if: steps.version_check.outputs.needs_update == 'true'
+        run: |
+          git add pyproject.toml
+          git commit -m "Bump version to ${{ inputs.version }}"
+          git push origin main
+
+      - name: Create and Push Tag
+        run: |
+          # Check if tag already exists locally
+          if git rev-parse "${{ inputs.version }}" >/dev/null 2>&1; then
+            echo "Tag ${{ inputs.version }} already exists locally, skipping creation"
+          else
+            git tag ${{ inputs.version }}
+            echo "Created tag ${{ inputs.version }}"
+          fi
+
+          # Push tag
+          git push origin ${{ inputs.version }} || {
+            echo "Failed to push tag, it might already exist remotely"
+            exit 1
+          }
+
+      - name: Create Release
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const tagName = '${{ inputs.version }}';
+
+            // Check if release already exists
+            try {
+              const { data: existingRelease } = await github.rest.repos.getReleaseByTag({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                tag: tagName
+              });
+              console.log(`Release ${tagName} already exists: ${existingRelease.html_url}`);
+              return;
+            } catch (error) {
+              if (error.status !== 404) {
+                throw error;
+              }
+            }
+
+            // Create the release
+            const { data: release } = await github.rest.repos.createRelease({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              tag_name: tagName,
+              name: tagName,
+              draft: false,
+              prerelease: false,
+              generate_release_notes: true
+            });
+            console.log(`Created release ${release.html_url}`);
+
+  trigger_publish:
+    needs: prepare_release
+    uses: ./.github/workflows/release.yml
+    with:
+      tag_name: ${{ inputs.version }}
+    secrets: inherit

nexus_dev-1.0.0/.github/workflows/release.yml

@@ -0,0 +1,77 @@
+name: Release
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+  workflow_call:
+    inputs:
+      tag_name:
+        required: true
+        type: string
+
+jobs:
+  pypi-publish:
+    name: Publish to PyPI
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write  # IMPORTANT: this permission is mandatory for trusted publishing
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: ${{ inputs.tag_name || github.ref }}
+      
+      - name: Set up Python 3.13
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.13'
+
+      - name: Install build dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install build
+
+      - name: Build package
+        run: python -m build
+
+      - name: Publish package distributions to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          password: ${{ secrets.PYPI_API_TOKEN }}
+
+  docker-publish:
+    name: Publish to Docker Hub
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: ${{ inputs.tag_name || github.ref }}
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Login to Docker Hub
+        uses: docker/login-action@v3
+        with:
+          username: ${{ secrets.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_TOKEN }}
+
+      - name: Extract metadata (tags, labels) for Docker
+        id: meta
+        uses: docker/metadata-action@v5
+        with:
+          images: ${{ secrets.DOCKERHUB_USERNAME }}/nexus-dev
+          tags: |
+            type=raw,value=${{ inputs.tag_name }},enable=${{ inputs.tag_name != '' }}
+            type=raw,value=latest,enable=${{ inputs.tag_name != '' }}
+            type=semver,pattern={{version}},enable=${{ inputs.tag_name == '' }}
+            type=semver,pattern={{major}}.{{minor}},enable=${{ inputs.tag_name == '' }}
+            type=raw,value=latest,enable=${{ inputs.tag_name == '' && !contains(github.ref, '-') }}
+
+      - name: Build and push Docker image
+        uses: docker/build-push-action@v5
+        with:
+          context: .
+          push: true
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}

nexus_dev-1.0.0/.gitignore

@@ -0,0 +1,84 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# PyInstaller
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+
+# Translations
+*.mo
+*.pot
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# ruff
+.ruff_cache/
+
+# Nexus-Dev specific
+.nexus/
+nexus_config.json
+~/.nexus-dev/
+
+# OS
+.DS_Store
+Thumbs.db

nexus_dev-1.0.0/.python-version

@@ -0,0 +1 @@
+3.13

nexus_dev-1.0.0/AGENTS.md

@@ -0,0 +1,98 @@
+# AGENTS.md - Nexus-Dev Project Guidelines
+
+> Guidelines for AI coding assistants working on the Nexus-Dev codebase.
+
+## Project Overview
+
+Nexus-Dev is a local RAG (Retrieval-Augmented Generation) MCP server that provides persistent memory for AI coding assistants. It indexes code, documentation, and lessons into a LanceDB vector database.
+
+## Architecture
+
+```
+src/nexus_dev/
+├── server.py         # FastMCP server with tool handlers
+├── cli.py            # Click CLI commands (nexus-init, nexus-index, etc.)
+├── database.py       # LanceDB wrapper (NexusDatabase, Document, SearchResult)
+├── embeddings.py     # Embedding providers (OpenAI, Ollama)
+├── config.py         # NexusConfig dataclass
+└── chunkers/         # Language-specific code chunkers
+    ├── base.py       # BaseChunker, ChunkerRegistry
+    ├── python_chunker.py
+    ├── java_chunker.py
+    ├── javascript_chunker.py
+    └── docs_chunker.py
+```
+
+## Development Commands
+
+```bash
+make dev          # Install in dev mode
+make test         # Run tests
+make test-cov     # Run tests with coverage
+make lint         # Run ruff linter
+make format       # Format code
+make check        # Run all checks (lint + format + type-check)
+```
+
+## Before Pushing Code (CI Alignment)
+
+**MANDATORY**: Always run these checks before committing/pushing to avoid CI failures:
+
+```bash
+make check   # Runs: lint + format-check + type-check (same as CI)
+```
+
+Or run them individually:
+
+```bash
+ruff check src/ tests/          # Linting (same as CI)
+ruff format --check src/ tests/ # Format check (same as CI)
+mypy src/                       # Type checking (same as CI)
+```
+
+### Auto-fix Lint Issues
+
+To automatically fix linting and formatting issues:
+
+```bash
+make format  # Formats code + auto-fixes lint issues
+```
+
+> **Important**: The CI runs `ruff check src/ tests/`, `ruff format --check src/ tests/`, and `mypy src/`.  
+> Local checks MUST pass before pushing or the CI build will fail.
+
+## Coding Standards
+
+- **Python 3.13+** with type hints
+- **Ruff** for linting and formatting
+- **MyPy** for type checking
+- **Pytest** with pytest-asyncio for async tests
+- Follow PEP 8 naming conventions
+- Use `async/await` for I/O operations
+
+## Testing Guidelines
+
+1. **Unit tests** go in `tests/unit/`
+2. **Mock external dependencies** (LanceDB, HTTP clients) - don't make real API calls
+3. Use `pytest.mark.asyncio` for async tests
+4. Target 80%+ code coverage
+
+## Key Patterns
+
+### Adding a New MCP Tool
+
+1. Add function in `server.py` with `@mcp.tool()` decorator
+2. Add tests in `tests/unit/test_server.py`
+3. Update `AGENTS.md` if user-facing
+
+### Adding a New Chunker
+
+1. Create `src/nexus_dev/chunkers/<language>_chunker.py`
+2. Inherit from `BaseChunker`
+3. Register in `ChunkerRegistry`
+4. Add tests in `tests/chunkers/`
+
+### Adding a CLI Command
+
+1. Add function in `cli.py` with Click decorators
+2. Add tests in `tests/unit/test_cli.py`