nexus-dev 3.2.0__tar.gz

nexus_dev-3.2.0/.agent/workflows/finish.md

@@ -0,0 +1,91 @@
+---
+description: Complete a task and record learnings
+---
+
+# Finish Task Workflow
+
+Use this workflow after completing an implementation to ensure all knowledge is captured.
+
+## Steps
+
+// turbo-all
+
+1. **Review the work done**
+   - What feature/fix was implemented?
+   - Were there any mistakes or backtracking during development?
+   - What were the key design decisions?
+
+2. **Check for uncaptured insights**
+   ```
+   search_insights("<topic related to this work>")
+   ```
+   
+   If you made mistakes or backtracked but didn't record them yet:
+   ```
+   record_insight(
+       category="mistake",  # or "backtrack", "discovery", "optimization"
+       description="<what happened>",
+       reasoning="<your thinking>",
+       correction="<how you fixed it>"
+   )
+   ```
+
+3. **Record the implementation**
+   ```
+   record_implementation(
+       title="<feature/fix title>",
+       summary="<what was built>",
+       approach="<how it was built>",
+       design_decisions=[
+           "Chose X over Y because...",
+           "Used pattern Z for..."
+       ],
+       files_changed=["list", "of", "modified", "files"]
+   )
+   ```
+
+4. **Verify it was saved**
+   ```
+   search_implementations("<feature name>")
+   ```
+
+## When to Use
+
+- After completing a user-requested feature
+- After finishing a complex refactor
+- After fixing a significant bug
+- When you want to ensure nothing was missed
+
+## Example
+
+After implementing authentication:
+
+```
+# Check if already captured
+search_insights("authentication")
+
+# Record any mistakes made
+record_insight(
+    category="mistake",
+    description="Used bcrypt 4.0 which has breaking API changes",
+    reasoning="Assumed latest version would be compatible",
+    correction="Downgraded to bcrypt 3.2 based on project dependencies"
+)
+
+# Record the implementation
+record_implementation(
+    title="Add JWT Authentication",
+    summary="Implemented JWT-based authentication with refresh tokens",
+    approach="Used PyJWT library with RSA256 signing, Redis for token blacklist",
+    design_decisions=[
+        "Chose JWT over sessions for stateless API",
+        "Used Redis for blacklist due to TTL support and speed",
+        "Implemented refresh token rotation for security"
+    ],
+    files_changed=[
+        "src/auth/jwt_handler.py",
+        "src/auth/middleware.py",
+        "src/api/routes/auth.py"
+    ]
+)
+```

nexus_dev-3.2.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/you/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-3.2.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-3.2.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-3.2.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-3.2.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-3.2.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-3.2.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-3.2.0/.gitignore

@@ -0,0 +1,85 @@
+# 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/mcp_config.json
+nexus_config.json
+~/.nexus-dev/
+
+# OS
+.DS_Store
+Thumbs.db

nexus_dev-3.2.0/.nexus/implementations/impl_aca4162d.md

@@ -0,0 +1,34 @@
+---
+title: Isolated Global Installation Support
+timestamp: '2026-01-18T15:41:09.321153+00:00'
+project_id: f959454c-12b6-4062-b411-59fa58f83777
+files_changed:
+- README.md
+- docs/quick-start.md
+- pyproject.toml
+- src/nexus_dev/cli.py
+- src/nexus_dev/templates/pre-commit-hook (moved)
+related_plan: ''
+---
+
+# Isolated Global Installation Support
+
+## Summary
+Enabled isolated global installation of Nexus-Dev via pipx or uv by fixing resource packaging and path resolution issues.
+
+## Technical Approach
+Reorganized resource files into the package source tree, updated CLI path resolution using package-relative paths, and revised build metadata in pyproject.toml. Recommended pipx/uv for isolated global installation.
+
+## Design Decisions
+
+- Moved templates to `src/nexus_dev/templates` to ensure seamless packaging without complex data-file mapping.
+- Used `Path(__file__).parent` for robust path resolution regardless of installation location.
+- Recommended `pipx` to avoid the 'sourcing venv' friction reported by the user.
+
+## Files Changed
+
+- `README.md`
+- `docs/quick-start.md`
+- `pyproject.toml`
+- `src/nexus_dev/cli.py`
+- `src/nexus_dev/templates/pre-commit-hook (moved)`