codevoight 0.1.0__py3-none-any.whl

codevoight/git/runner.py

@@ -0,0 +1,57 @@
+from __future__ import annotations
+
+import subprocess
+from pathlib import Path
+from typing import List, Optional, Tuple
+
+from codevoight.core.diff import normalize_text
+
+
+class GitRunner:
+    def __init__(self, repo_path: Optional[Path] = None):
+        self.repo_path = repo_path or Path.cwd()
+
+    def _run(self, args: List[str]) -> Tuple[int, str, str]:
+        cmd = ["git"] + args
+        proc = subprocess.run(
+            cmd,
+            cwd=str(self.repo_path),
+            capture_output=True,
+            text=True,
+            encoding="utf-8",
+            errors="replace",
+        )
+        return proc.returncode, proc.stdout, proc.stderr
+
+    def is_git_repo(self) -> bool:
+        code, stdout, _ = self._run(["rev-parse", "--is-inside-work-tree"])
+        return code == 0 and "true" in stdout.strip().lower()
+
+    def get_repo_root(self) -> Optional[Path]:
+        code, stdout, _ = self._run(["rev-parse", "--show-toplevel"])
+        if code == 0 and stdout.strip():
+            return Path(stdout.strip()).resolve()
+        return None
+
+    def get_staged_diff(self) -> str:
+        """Get git diff of cached/staged files normalized."""
+        code, stdout, _ = self._run(["diff", "--cached"])
+        if code == 0:
+            return normalize_text(stdout)
+        return ""
+
+    def get_working_diff(self) -> str:
+        """Get git diff against HEAD."""
+        code, stdout, _ = self._run(["diff", "HEAD"])
+        if code == 0:
+            return normalize_text(stdout)
+        return ""
+
+    def stage_files(self, paths: List[str]) -> bool:
+        code, _, _ = self._run(["add"] + paths)
+        return code == 0
+
+    def commit(self, message: str) -> Tuple[bool, str]:
+        code, stdout, stderr = self._run(["commit", "-m", message])
+        output = stdout if code == 0 else f"{stderr}\n{stdout}".strip()
+        return code == 0, output

codevoight/server.py

@@ -0,0 +1,209 @@
+from __future__ import annotations
+
+import json
+import os
+import time
+import uuid
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+try:
+    from mcp.server.mcpserver import MCPServer
+except ImportError:
+    from mcp.server.fastmcp import FastMCP as MCPServer  # type: ignore
+
+from codevoight.core.diff import compute_diff_hash, normalize_text
+from codevoight.core.models import CapabilityToken, SessionStatus, StagedSession
+from codevoight.core.security import get_or_create_secret, verify_token
+from codevoight.db.repository import StateRepository
+from codevoight.generators.deterministic import DeterministicQuizGenerator
+from codevoight.git.runner import GitRunner
+
+
+def create_server(workspace_root: Optional[Path] = None) -> MCPServer:
+    ws_env = (
+        os.getenv("CODEVOIGHT_WORKSPACE")
+        or os.getenv("QUIZGATE_WORKSPACE")
+        or os.getenv("CODEGATE_WORKSPACE")
+        or os.getenv("WORKSPACE")
+    )
+    if ws_env:
+        root = Path(ws_env).resolve()
+    else:
+        root = (workspace_root or GitRunner().get_repo_root() or Path.cwd()).resolve()
+
+    codevoight_dir = root / ".codevoight"
+    if not codevoight_dir.exists():
+        if (root / ".quizgate").exists():
+            codevoight_dir = root / ".quizgate"
+        elif (root / ".codegate").exists():
+            codevoight_dir = root / ".codegate"
+
+    db_path = codevoight_dir / "state.db"
+
+    repo = StateRepository(db_path)
+    git_runner = GitRunner(root)
+    generator = DeterministicQuizGenerator()
+
+    server = MCPServer(
+        name="codevoight",
+        instructions="CodeVoight: Voight-Kampff human comprehension gate for AI code changes before Git commits.",
+    )
+
+    @server.tool()
+    def stage_code_change(files: List[Dict[str, str]], description: str = "") -> str:
+        """Stage one or more file changes into the workspace and register a human comprehension quiz.
+
+        Args:
+            files: List of file dictionaries with keys 'file_path' and 'content'.
+            description: Short summary of what this change accomplishes.
+        """
+        if not files:
+            return "[ERROR] No files provided to stage."
+
+        staged_paths = []
+        for f in files:
+            rel_path = f.get("file_path")
+            content = f.get("content")
+            if not rel_path or content is None:
+                continue
+
+            target_file = root / rel_path
+            target_file.parent.mkdir(parents=True, exist_ok=True)
+            target_file.write_text(content, encoding="utf-8")
+            staged_paths.append(rel_path)
+
+        if not staged_paths:
+            return "[ERROR] No valid file paths provided."
+
+        git_runner.stage_files(staged_paths)
+        staged_diff = git_runner.get_staged_diff()
+        if not staged_diff.strip():
+            return "[WARNING] Changes were written to disk, but no git diff was produced."
+
+        diff_hash = compute_diff_hash(staged_diff)
+        session_id = str(uuid.uuid4())[:8]
+
+        questions = generator.generate_quiz(staged_diff, description)
+
+        now = time.time()
+        session = StagedSession(
+            session_id=session_id,
+            diff_text=staged_diff,
+            diff_hash=diff_hash,
+            description=description,
+            status=SessionStatus.PENDING_QUIZ,
+            created_at=now,
+            expires_at=now + 1800.0,
+        )
+
+        repo.create_session(session, questions)
+
+        return (
+            f"[CODEVOIGHT: CHANGES STAGED]\n"
+            f"Session ID : {session_id}\n"
+            f"Diff Hash  : {diff_hash[:16]}...\n"
+            f"Files      : {', '.join(staged_paths)}\n"
+            f"Questions  : {len(questions)} generated\n\n"
+            f"ACTION REQUIRED:\n"
+            f"Tell the developer: 'Please run \"codevoight quiz {session_id}\" in your terminal "
+            f"to verify your understanding and unlock the commit gate.'"
+        )
+
+    @server.tool()
+    def get_gate_status(session_id: str = "") -> str:
+        """Check the authorization status of a CodeVoight staging session.
+
+        Args:
+            session_id: Optional session identifier. If omitted, checks latest pending or current staged diff.
+        """
+        if session_id:
+            session = repo.get_session(session_id)
+        else:
+            session = repo.get_latest_pending_session()
+            if not session:
+                staged_diff = git_runner.get_staged_diff()
+                if staged_diff:
+                    d_hash = compute_diff_hash(staged_diff)
+                    session = repo.find_valid_approved_session(d_hash)
+
+        if not session:
+            return json.dumps({
+                "status": "NOT_FOUND",
+                "can_commit": False,
+                "message": "No active or pending staging session found."
+            }, indent=2)
+
+        now = time.time()
+        is_expired = now > session.expires_at
+        status_val = "EXPIRED" if is_expired else session.status.value
+        can_commit = (status_val == SessionStatus.APPROVED.value) and not is_expired
+
+        return json.dumps({
+            "session_id": session.session_id,
+            "status": status_val,
+            "diff_hash": session.diff_hash,
+            "can_commit": can_commit,
+            "expires_in_seconds": max(0, int(session.expires_at - now)),
+        }, indent=2)
+
+    @server.tool()
+    def commit_staged(session_id: str, commit_message: str) -> str:
+        """Commit staged changes to Git if and only if the human developer has passed the comprehension quiz.
+
+        Args:
+            session_id: The session ID of the approved staging session.
+            commit_message: The commit message for git commit.
+        """
+        session = repo.get_session(session_id)
+        if not session:
+            return f"[ACCESS DENIED] Staging session '{session_id}' not found."
+
+        if session.status != SessionStatus.APPROVED:
+            return (
+                f"[ACCESS DENIED] Session '{session_id}' status is '{session.status.value}'. "
+                f"The human developer must run 'codevoight quiz {session_id}' to pass verification before committing."
+            )
+
+        if not session.capability_token:
+            return "[ACCESS DENIED] No capability token found for this session."
+
+        secret_key = get_or_create_secret(codevoight_dir)
+        try:
+            token = CapabilityToken.parse(session.capability_token)
+        except Exception as e:
+            return f"[ACCESS DENIED] Corrupted capability token: {e}"
+
+        current_staged_diff = git_runner.get_staged_diff()
+        if not current_staged_diff:
+            return "[ACCESS DENIED] Working tree has no staged git changes to commit."
+
+        current_diff_hash = compute_diff_hash(current_staged_diff)
+
+        # Constant time cryptographic verification
+        if not verify_token(token, current_diff_hash, secret_key):
+            return (
+                "[ACCESS DENIED] Capability token invalid, expired, or staged git diff modified after quiz! "
+                "You must re-stage and pass a new quiz."
+            )
+
+        # Execute commit
+        success, output = git_runner.commit(commit_message)
+        if not success:
+            return f"[COMMIT FAILED] Git error:\n{output}"
+
+        # Consume token to prevent replay
+        repo.consume_session_token(session_id)
+
+        return f"[COMMIT SUCCESSFUL] CodeVoight gate passed!\n{output}"
+
+    return server
+
+
+def main() -> None:
+    server = create_server()
+    server.run(transport="stdio")
+
+
+if __name__ == "__main__":
+    main()

codevoight-0.1.0.dist-info/METADATA

@@ -0,0 +1,191 @@
+Metadata-Version: 2.4
+Name: codevoight
+Version: 0.1.0
+Summary: Voight-Kampff Human Comprehension Gate for AI Coding Agents and Git Commits
+Author: CodeVoight Contributors
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/bibinwithab/codevoight
+Project-URL: Repository, https://github.com/bibinwithab/codevoight
+Project-URL: Issues, https://github.com/bibinwithab/codevoight/issues
+Keywords: mcp,git,ai,commit-gate,voight-kampff,comprehension,cursor,antigravity
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Version Control :: Git
+Classifier: Topic :: Security
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: mcp>=1.2.0
+Requires-Dist: pydantic>=2.6.0
+Requires-Dist: click>=8.1.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23.0; extra == "dev"
+Requires-Dist: build>=1.0.0; extra == "dev"
+Requires-Dist: twine>=5.0.0; extra == "dev"
+Dynamic: license-file
+
+# CodeVoight
+
+> Voight-Kampff Human Comprehension Gate for AI Coding Agents and Git Commits
+
+**CodeVoight** (inspired by the Blade Runner Voight-Kampff interrogation test that distinguishes humans from synthetic AI) guarantees human comprehension before AI coding agents commit code. It intercepts changes into a staged verification buffer and physically blocks Git commits until the developer reviews the diff and passes an interactive comprehension quiz via the terminal.
+
+---
+
+## 1. Why CodeVoight?
+
+Autonomous AI coding agents in modern IDEs (Cursor, Windsurf, Cline, Antigravity) write code directly to disk and create Git commits without verifying whether the human developer understands what changed.
+
+CodeVoight enforces a **strict, fail-closed comprehension gate**:
+1. **Agent Stages Changes**: The AI agent calls CodeVoight's MCP tool `stage_code_change`.
+2. **Deterministic Quiz Generated**: CodeVoight analyzes the staged diff (AST changes, modified functions, error handling, touched files) and generates comprehension questions.
+3. **Out-of-Band Human Verification**: To prevent the AI agent from answering its own quiz, the quiz must be completed by the developer via the terminal (`codevoight quiz`).
+4. **Cryptographic Capability Token**: Upon passing the quiz with 100% score, an HMAC-SHA256 capability token is generated and bound to the exact SHA-256 hash of the staged diff.
+5. **Physical Enforcement**: Git commits are gated both at the MCP tool level (`commit_staged`) and at the Git repository level via a `.git/hooks/pre-commit` hook. If the staged diff changes or lacks an approved token, Git aborts the commit.
+
+---
+
+## 2. Architecture
+
+```mermaid
+flowchart TD
+    subgraph Agent["1. AI Agent (Cursor / Antigravity / Cline)"]
+        A["Calls MCP Tool: stage_code_change()"]
+        AC["Calls MCP Tool: commit_staged()"]
+    end
+
+    subgraph Storage["2. Shared State (.codevoight/state.db - SQLite WAL)"]
+        DB[("Session & Quiz Store\n- Session ID & Diff Hash\n- Status: PENDING / APPROVED\n- HMAC Capability Token")]
+    end
+
+    subgraph Human["3. Human Developer (Terminal CLI)"]
+        H["Runs: codevoight quiz [session_id]"]
+        Q["Reviews Diff & Answers Quiz"]
+        T["100% Score: Generates Capability Token"]
+    end
+
+    subgraph Gate["4. Dual Enforcement Gate"]
+        P1["Path A: MCP commit_staged()"]
+        P2["Path B: Git Hook (.git/hooks/pre-commit)"]
+        GIT[("Git Repository Commit")]
+    end
+
+    A -->|"1. Writes staged diff & quiz"| DB
+    DB -->|"2. Fetches questions"| H
+    H --> Q --> T
+    T -->|"3. Stores APPROVED token"| DB
+
+    AC -->|"Verify session token"| P1
+    DB -.->|"Validate token"| P1
+    P1 -->|"Pass"| GIT
+
+    H -.->|"Direct git commit"| P2
+    DB -.->|"Validate diff hash"| P2
+    P2 -->|"Pass"| GIT
+```
+
+---
+
+## 3. Installation & Setup
+
+### Prerequisites
+* Python 3.10+
+* Git 2.20+
+
+### Install CodeVoight
+```powershell
+# Clone or navigate to the repository
+cd C:\Users\jbibingraceson\projects\codegate
+
+# Create virtual environment and install in editable mode
+python -m venv .venv
+.\.venv\Scripts\pip.exe install -e .[dev]
+```
+
+### Install Git Pre-Commit Hook
+In your project repository, install the physical commit verification hook:
+```powershell
+.\.venv\Scripts\codevoight.exe hook install
+```
+This writes `.git/hooks/pre-commit`, ensuring that any `git commit` requires a valid quiz approval token.
+
+---
+
+## 4. IDE MCP Configuration
+
+### Cursor
+Add to `.cursor/mcp.json` or your Cursor user settings:
+```json
+{
+  "mcpServers": {
+    "codevoight": {
+      "command": "python",
+      "args": ["-m", "codevoight.server"]
+    }
+  }
+}
+```
+
+### VS Code (Cline / Roo Code)
+Add to your Cline MCP settings:
+```json
+{
+  "mcpServers": {
+    "codevoight": {
+      "command": "python",
+      "args": ["-m", "codevoight.server"],
+      "disabled": false,
+      "autoApprove": []
+    }
+  }
+}
+```
+
+### Google Antigravity
+Add to your Antigravity MCP settings:
+```json
+{
+  "mcpServers": {
+    "codevoight": {
+      "command": "python",
+      "args": ["-m", "codevoight.server"]
+    }
+  }
+}
+```
+
+---
+
+## 5. CLI Commands
+
+| Command | Description |
+| :--- | :--- |
+| `codevoight quiz [session_id]` | Interactive terminal quiz to review diff and unlock commit |
+| `codevoight status` | View active and pending staging sessions |
+| `codevoight stage <files...>` | Manually stage files and generate a comprehension quiz |
+| `codevoight hook install` | Install the `.git/hooks/pre-commit` verification gate |
+| `codevoight hook verify` | Test current staged Git changes against CodeVoight state |
+
+---
+
+## 6. Verification & Test Suite
+
+Run the full automated test suite:
+```powershell
+.\.venv\Scripts\pytest.exe -v
+```
+
+The test suite covers:
+* HMAC capability token generation, tampering detection, and TTL expiry.
+* Cross-platform diff normalization and SHA-256 hash consistency.
+* SQLite WAL concurrency and transaction rollback.
+* Deterministic AST diff question generation and grading.
+* End-to-end Git pre-commit hook enforcement.
+* MCP stdio tool execution, blocking unapproved commits and passing approved commits.

codevoight-0.1.0.dist-info/RECORD

@@ -0,0 +1,20 @@
+codevoight/__init__.py,sha256=nxhB6FI9nhxgWX4TTFgBGqT5gMSBtfw446xX5twfS4Y,206
+codevoight/cli.py,sha256=0Szw6c15vU1UJS4hIKnQmOCqMTqxNzCSdeXjSa0539M,8016
+codevoight/server.py,sha256=guhCvawxuV1fkxobjU_y_8Cqlxh0iylYSGr0TtDb3S0,7564
+codevoight/core/config.py,sha256=C6Upas5OV8NGmb6Dk99CcaeB0-Rp5Jdqd2pigv1GF3s,1525
+codevoight/core/diff.py,sha256=5PUY_aPQZhavBdLvWt0q7c3dgFat839TD84UUyc8QXg,1594
+codevoight/core/models.py,sha256=S_dM8iGSULXFiSfBNk-yKV825iuoqDJfrl0xAsZbMt0,1862
+codevoight/core/security.py,sha256=lEqgwbumy8wmw97TYO_2x9jE3NHOJw3YWbdDILLnQGo,2197
+codevoight/db/repository.py,sha256=QMiOMikRQzJJAB14qq4ns6NbI94-bF-3MtS-a_p-4AY,8071
+codevoight/db/schema.py,sha256=FZPbOJ_qNejfwBOtSCBOtMSTxoMPoj5ujypUWRgm59g,1133
+codevoight/generators/base.py,sha256=x5Bkov8u3s1OsIs_AIhNZ3AJgVHnviX3gB3IpsYMOzw,661
+codevoight/generators/deterministic.py,sha256=rAfTi4XO-HsKDGN8jJ66y2v2YqxPkOrn4gcK-GBLl-A,9026
+codevoight/generators/llm.py,sha256=9vxqkruV2H_wLpEr3oGUTeXpbYs9eV96OnDdB0bXw6I,1606
+codevoight/git/hook.py,sha256=I_bGPUk3RZKTQShCd6Ifb3DNmvwyp9TqxignwwLlkEY,3699
+codevoight/git/runner.py,sha256=aamIDtVcP03s1L7Hbay2Imz0q2-E9zS-ubjzpIyer0U,1872
+codevoight-0.1.0.dist-info/licenses/LICENSE,sha256=xu7qH6sbLy1Jk7HqTSZqDOZa3ppuTq55C56eAbR_vlA,1071
+codevoight-0.1.0.dist-info/METADATA,sha256=FE_jMFjK3v9klfHkhECSb0DYybUsgDVzVi5NzXkD8uI,6460
+codevoight-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+codevoight-0.1.0.dist-info/entry_points.txt,sha256=FsOcm7my2mymEnNOlN_RY3dVE50FHQG4EnYuEAU0nds,51
+codevoight-0.1.0.dist-info/top_level.txt,sha256=SWALPlQFRcU_ypGQXBGmlGiQPrnRpfBg7oOsnVtSXzQ,11
+codevoight-0.1.0.dist-info/RECORD,,

codevoight-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

codevoight-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+codevoight = codevoight.cli:main

codevoight-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Bibin Graceson
+
+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.

codevoight-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+codevoight