sentrux 0.1.0__tar.gz

sentrux-0.1.0/.claude-plugin/marketplace.json

@@ -0,0 +1,23 @@
+{
+  "$schema": "https://anthropic.com/claude-code/marketplace.schema.json",
+  "name": "sentrux-marketplace",
+  "version": "1.0.0",
+  "description": "Sentrux — live codebase visualization and structural quality gate for AI-agent-written code",
+  "owner": {
+    "name": "yjing",
+    "email": "yjing@sentrux.dev"
+  },
+  "plugins": [
+    {
+      "name": "sentrux",
+      "description": "MCP server for structural health analysis — 14 dimensions graded A-F, dependency cycles, coupling, dead code, test coverage, and quality gates",
+      "version": "0.3.12",
+      "author": {
+        "name": "yjing",
+        "email": "yjing@sentrux.dev"
+      },
+      "source": "./claude-plugin",
+      "category": "development"
+    }
+  ]
+}

sentrux-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,48 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ['3.9', '3.10', '3.11', '3.12']
+        os: [ubuntu-latest, macos-latest]
+    runs-on: ${{ matrix.os }}
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v4
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v2
+
+      - name: Install dependencies
+        run: |
+          uv sync --all-extras
+
+      - name: Lint with ruff
+        run: |
+          uv run ruff check sentrux tests
+
+      - name: Format check with black
+        run: |
+          uv run black --check sentrux tests
+
+      - name: Run tests
+        run: |
+          uv run pytest tests/ -v --cov=sentrux
+
+      - name: Test CLI
+        run: |
+          uv run sentrux scan .
+          uv run sentrux check .

sentrux-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,25 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    environment:
+      name: release
+      url: https://pypi.org/p/${{ github.event.repository.name }}
+    permissions:
+      id-token: write
+
+    steps:
+      - uses: actions/checkout@v4
+      
+      - uses: astral-sh/setup-uv@v2
+      
+      - name: Build
+        run: uv build
+      
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

sentrux-0.1.0/.gitignore

@@ -0,0 +1,41 @@
+# Build
+target/
+build/
+dist/
+*.egg-info/
+
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+.Python
+env/
+venv/
+ENV/
+.venv
+.pytest_cache/
+.coverage
+htmlcov/
+
+# OS
+.DS_Store
+
+# Local config
+.mcp.json
+!claude-plugin/.mcp.json
+
+# Runtime data
+.sentrux/baseline.json
+*.key
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# Local tools
+.beemem*/
+.claude/
+.wrangler/
+sentrux-core/src/analysis/plugin/embedded.rs

sentrux-0.1.0/.sentrux/baseline.toml

@@ -0,0 +1,8 @@
+# Quality baseline
+[baseline]
+overall_score = 7563
+modularity = 0.7391304347826086
+acyclicity = 0.8
+depth = 0.8
+equality = 0.47531868370902364
+redundancy = 0.935064935064935

sentrux-0.1.0/.sentrux/rules.toml

@@ -0,0 +1,50 @@
+# Sentrux Architectural Rules
+# These constraints are checked by `sentrux check` and the `check_rules` MCP tool.
+
+[constraints]
+max_cycles = 0           # No circular dependencies allowed
+max_cc = 25              # Max cyclomatic complexity per function
+max_fn_lines = 100       # Max function length
+no_god_files = false     # Allow god files for now
+
+# Layer definitions: higher order depends on lower order only.
+[[layers]]
+name = "core"
+paths = ["src/core/*"]
+order = 0
+
+[[layers]]
+name = "analysis"
+paths = ["src/analysis/*"]
+order = 1
+
+[[layers]]
+name = "metrics"
+paths = ["src/metrics/*"]
+order = 2
+
+[[layers]]
+name = "layout"
+paths = ["src/layout/*"]
+order = 3
+
+[[layers]]
+name = "renderer"
+paths = ["src/renderer/*"]
+order = 4
+
+[[layers]]
+name = "app"
+paths = ["src/app/*"]
+order = 5
+
+# Boundary rules: forbidden cross-layer shortcuts
+[[boundaries]]
+from = "src/renderer/*"
+to = "src/analysis/*"
+reason = "Renderer must not depend on analysis directly"
+
+[[boundaries]]
+from = "src/layout/*"
+to = "src/app/*"
+reason = "Layout must not depend on app layer"

sentrux-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sentrux
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

sentrux-0.1.0/PKG-INFO

@@ -0,0 +1,252 @@
+Metadata-Version: 2.4
+Name: sentrux
+Version: 0.1.0
+Summary: Structural quality analysis and governance tool for AI-assisted code development
+Author: Sentrux Contributors
+License: MIT
+License-File: LICENSE
+Requires-Python: >=3.9
+Requires-Dist: click>=8.1.0
+Requires-Dist: tomli>=2.0.0; python_version < '3.11'
+Provides-Extra: dev
+Requires-Dist: black>=23.0; extra == 'dev'
+Requires-Dist: pytest-cov>=4.0; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Provides-Extra: test
+Requires-Dist: pytest-cov>=4.0; extra == 'test'
+Requires-Dist: pytest>=7.0; extra == 'test'
+Description-Content-Type: text/markdown
+
+<div align="center">
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="assets/logo-dark.svg?v=2">
+  <source media="(prefers-color-scheme: light)" srcset="assets/logo-light.svg?v=2">
+  <img alt="sentrux" src="assets/logo-dark.svg?v=2" width="500">
+</picture>
+
+<br>
+
+**The sensor that helps AI agents close the feedback loop.**<br>Structural quality analysis for Python code.
+
+[![CI](https://github.com/sentrux/sentrux/actions/workflows/ci.yml/badge.svg)](https://github.com/sentrux/sentrux/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+**English** | [中文](README.zh-CN.md) | [Deutsch](README.de.md) | [日本語](README.ja.md)
+
+[How it Works](#how-it-works) · [Quick Start](#quick-start) · [MCP Integration](#mcp-server) · [Rules Engine](#rules-engine)
+
+</div>
+
+## How it works
+
+AI agents write code at machine speed. But without visibility into architectural health, codebases degrade just as fast.
+
+sentrux measures structural quality in real-time:
+
+- **5 root cause metrics** (modularity, acyclicity, depth, equality, redundancy)
+- **One continuous score** (0–10000)
+- **Architectural rules engine** (CI-friendly constraints)
+- **MCP integration** (real-time feedback for Claude, Cursor, etc.)
+
+When your agent writes code, you see immediately whether quality improved or degraded.
+
+## Quick Start
+
+**Install** (Python 3.9+)
+
+```bash
+# Using uv (recommended)
+uv pip install sentrux
+
+# Or using pip
+pip install sentrux
+```
+
+**Run it**
+
+```bash
+sentrux scan .              # Analyze current project and show quality score
+sentrux check .             # Check if project meets architectural rules
+sentrux gate --save .       # Save baseline before starting an AI session
+sentrux gate .              # Compare after — catches quality degradation
+sentrux --mcp               # Start MCP server for AI agent integration
+```
+
+**Connect to your AI agent** (optional)
+
+Claude Code:
+```
+/plugin marketplace add sentrux/sentrux
+/plugin install sentrux
+```
+
+Cursor / Windsurf / any MCP client — add to your MCP config:
+```json
+{
+  "mcpServers": {
+    "sentrux": {
+      "command": "sentrux",
+      "args": ["--mcp"]
+    }
+  }
+}
+```
+
+**From source**
+
+```bash
+git clone https://github.com/sentrux/sentrux.git
+cd sentrux
+
+# Using uv (recommended)
+uv sync
+
+# Or using pip
+pip install -e .
+```
+
+## The Problem
+
+You start a project with Claude Code or Cursor. Day one is magic. The agent writes clean code, understands your intent, ships features fast.
+
+Then something shifts.
+
+The agent starts hallucinating functions that don't exist. It puts new code in the wrong place. It introduces bugs in files it touched yesterday. You're spending more time fixing the agent's output than writing it yourself.
+
+Everyone assumes the AI got worse. **It didn't.** Your codebase did.
+
+Here's what happened: you lost visibility into architecture. The agent modifies dozens of files per session. You see `Modified src/foo.py` in the terminal, but you've lost spatial awareness. You don't see the dependency graph. You don't see that it just created a cycle. You don't see that three modules now depend on a file that was supposed to be internal.
+
+**Every AI session silently degrades your architecture.**
+
+Same function names, different purposes, scattered across files. Unrelated code dumped in the same folder. Dependencies tangling into spaghetti. When the agent searches your project, it finds twenty conflicting matches — and picks the wrong one. Every session makes the mess worse.
+
+**The traditional answer doesn't work.** Tools like GitHub Spec Kit try to plan architecture first, then let AI implement. But there's zero visibility into whether the implementation actually matches the spec. No feedback loop.
+
+**You don't need a better plan. You need a better sensor.**
+
+## The Solution
+
+sentrux is the missing feedback loop for AI-assisted development.
+
+It watches your Python codebase in real-time — every file, every dependency, every architectural relationship. Computed in milliseconds.
+
+**5 root cause metrics, one continuous score.**
+
+- **Modularity**: Are dependencies contained or scattered?
+- **Acyclicity**: Are there circular dependencies?
+- **Depth**: How deep is the import structure?
+- **Equality**: Is complexity evenly distributed or concentrated?
+- **Redundancy**: How much code is duplicated?
+
+When architecture degrades, you see it immediately — not two weeks later when everything is broken.
+
+sentrux gives you the sensor. Your rules give you the spec. The agent is the actuator. **The loop closes.**
+
+## MCP Server
+
+Connect sentrux to any AI agent via Model Context Protocol.
+
+```
+Agent: scan("/Users/me/myproject")
+  → { overall_score: 7342, file_count: 139, modularity: 0.73, acyclicity: 0.92 }
+
+Agent: session_start()
+  → { status: "Baseline saved", score: 7342 }
+
+  ... agent writes code ...
+
+Agent: health()
+  → { overall_score: 6891, modularity: 0.58, acyclicity: 0.85 }
+  → Quality degraded during this session
+```
+
+**Available MCP tools:**
+
+- `scan` – Analyze workspace and get quality metrics
+- `health` – Get current project quality score
+- `check_rules` – Verify architectural rules compliance
+- `session_start` – Initialize a session and save baseline
+- `session_end` – End session and compare results
+- `evolution` – Track quality over time
+- `test_gaps` – Identify untested modules
+
+## Rules Engine
+
+Define architectural constraints. Enforce them in CI. Let the agent know the boundaries.
+
+**Example `.sentrux/rules.toml`**
+
+```toml
+[constraints]
+max_cycles = 0              # No circular dependencies allowed
+max_cc = 25                 # Max cyclomatic complexity per function
+max_fn_lines = 100          # Max function length
+
+[[layers]]
+name = "core"
+paths = ["src/core/*"]
+order = 0
+
+[[layers]]
+name = "analysis"
+paths = ["src/analysis/*"]
+order = 1
+
+[[layers]]
+name = "app"
+paths = ["src/app/*"]
+order = 2
+
+[[boundaries]]
+from = "src/app/*"
+to = "src/core/internal/*"
+reason = "App must not depend on core internals"
+```
+
+```bash
+sentrux check .
+# ❌ Violations found:
+#   - src/app/main.py: Cyclomatic complexity 28.0 exceeds max 25
+```
+
+Or in CI:
+```bash
+sentrux check . && echo "Architecture check passed"
+```
+
+## Supported Languages
+
+Python 3.9+. Analyzes Python projects using the Python `ast` module.
+
+Can be extended to support additional languages using tree-sitter Python bindings.
+
+## Philosophy
+
+The human role is changing — from writing code to governing code.
+
+sentrux is built on three beliefs:
+
+**1. Human-in-the-loop is non-negotiable.** AI agents are powerful but limited. They cannot hold the big picture and small details at once. A human must see what the agent is doing to the whole — not just which file it touched, but what that means to architecture.
+
+**2. Verification is more valuable than generation.** Generating a correct solution is harder than verifying one. You don't need to out-code the machine. You need to out-evaluate it — specify what "correct" looks like, recognize when the output misses, judge whether the direction is right.
+
+**3. Good systems make good outcomes inevitable.** A well-designed system constrains behavior so that the right thing is the easy thing. A quality gate that blocks degradation. A rules engine that encodes architectural decisions. A sensor that makes structural rot impossible to ignore.
+
+Once you have a feedback loop that works, you don't go back to doing it by hand.
+
+---
+
+<div align="center">
+
+<sub>AI agents write code at machine speed. Without structural governance, codebases decay at machine speed too.<br><b>sentrux is the governor.</b></sub>
+
+</div>
+
+<div align="center">
+
+[MIT License](LICENSE)
+
+</div>