teridex 0.1.0__tar.gz

teridex-0.1.0/.editorconfig

@@ -0,0 +1,15 @@
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+indent_style = space
+indent_size = 4
+insert_final_newline = true
+trim_trailing_whitespace = true
+
+[*.{yml,yaml,toml,json}]
+indent_size = 2
+
+[*.md]
+trim_trailing_whitespace = false

teridex-0.1.0/.github/ISSUE_TEMPLATE//342/234/250-feature-request.md

@@ -0,0 +1,23 @@
+---
+name: '✨ Feature Request'
+about: Suggest an idea or a new functionality
+title: '[FEATURE]: '
+labels: enhancement
+assignees: ''
+---
+
+### Is your feature request related to a problem?
+
+A clear and concise description of what the problem is (e.g. I'm always frustrated when...).
+
+### Describe the solution you'd like
+
+A clear and concise description of what you want to happen.
+
+### Describe alternatives you've considered
+
+A clear and concise description of any alternative solutions or features you've considered.
+
+### Additional context
+
+Add any other context or screenshots about the feature request here.

teridex-0.1.0/.github/ISSUE_TEMPLATE//360/237/220/233-bug-report.md

@@ -0,0 +1,30 @@
+---
+name: "\U0001F41B Bug Report"
+about: Report an error or unexpected behavior
+title: '[BUG]: '
+labels: bug
+assignees: ''
+---
+
+### Bug Description
+
+A clear and concise description of what the bug is.
+
+### Steps to Reproduce
+
+1. Go to '...'
+2. Click on '....'
+3. Scroll down to '....'
+4. See error
+
+### Expected Behavior
+
+A clear and concise description of what you expected to happen.
+
+### Screenshots / Logs
+
+If applicable, add screenshots or paste console logs to help explain your problem.
+
+### Environment
+
+- **Version:**

teridex-0.1.0/.github/ISSUE_TEMPLATE//360/237/233/240-task---improvement.md

@@ -0,0 +1,20 @@
+---
+name: "\U0001F6E0 Task / Improvement"
+about: Maintenance, refactoring, or small improvements
+title: '[TASK]: '
+labels: maintenance
+assignees: ''
+---
+
+### Description
+
+A clear and concise description of what needs to be done.
+
+### Motivation
+
+Why is this task necessary or beneficial for the project?
+
+### Checklist
+
+- [ ] Task 1
+- [ ] Task 2

teridex-0.1.0/.github/PULL_REQUEST_TEMPLATE/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,30 @@
+## Description
+
+<!-- Provide a brief summary of the changes and the motivation behind them. -->
+
+## Related Issue
+
+<!-- Link the issue here using the syntax: Fixes #123 or Related to #123 -->
+
+## Type of Change
+
+- [ ] 🐛 Bug fix (non-breaking change which fixes an issue)
+- [ ] ✨ New feature (non-breaking change which adds functionality)
+- [ ] 💥 Breaking change (fix or feature that would cause existing functionality to not work as expected)
+- [ ] 🛠 Maintenance / Refactoring
+
+## How Has This Been Tested?
+
+<!-- Describe the tests that you ran to verify your changes. -->
+
+- [ ] Manual testing (please describe)
+- [ ] Unit tests added/updated
+- [ ] Integration tests added/updated
+
+## Checklist
+
+- [ ] My code follows the style guidelines of this project
+- [ ] I have performed a self-review of my code
+- [ ] I have commented my code, particularly in hard-to-understand areas
+- [ ] I have made corresponding changes to the documentation
+- [ ] My changes generate no new warnings

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

@@ -0,0 +1,56 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v8.1.0
+        with:
+          enable-cache: true
+          python-version: "3.13"
+
+      - name: Sync workspace
+        run: uv sync --all-extras --dev --frozen
+
+      - name: Lint (ruff format + check + mypy)
+        run: ./scripts/lint.sh
+
+  test:
+    runs-on: ${{ matrix.os }}
+    defaults:
+      run:
+        shell: bash
+    strategy:
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+      fail-fast: false
+    steps:
+      - uses: actions/checkout@v5
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v8.1.0
+        with:
+          enable-cache: true
+          python-version: "3.13"
+
+      - name: Sync workspace
+        run: uv sync --all-extras --dev --frozen
+
+      - name: Test (pytest + coverage gate)
+        run: ./scripts/test.sh

teridex-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,87 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*"
+  workflow_dispatch:
+
+permissions:
+  contents: write
+  id-token: write
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    environment: release
+    steps:
+      # ── checkout & toolchain ──────────────────────────────────────────
+      - uses: actions/checkout@v5
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v8.1.0
+        with:
+          enable-cache: true
+          python-version: "3.13"
+
+      # ── test gate ─────────────────────────────────────────────────────
+      - name: Sync workspace
+        run: uv sync --all-extras --dev --frozen
+
+      - name: Lint
+        run: ./scripts/lint.sh
+
+      - name: Test
+        run: ./scripts/test.sh
+
+      # ── Build Packages ────────────────────────────────────────────────
+      - name: Build packages
+        run: uv build --out-dir dist
+
+      - name: Generate Checksums
+        run: |
+          sha256sum dist/* > SHA256SUMS
+
+      - name: Extract Changelog Entry
+        id: extract_changelog
+        env:
+          GITHUB_REF_NAME: ${{ github.ref_name }}
+        run: |
+          uv run python -c '
+          import os, re, uuid
+          version = os.environ["GITHUB_REF_NAME"].lstrip("v")
+          with open("CHANGELOG.md") as f:
+              content = f.read()
+          pattern = rf"(?m)^##\s+\[?{re.escape(version)}\]?(.*?)(?=^##\s+\[?|\Z)"
+          match = re.search(pattern, content, re.DOTALL)
+          notes = ""
+          if match:
+              raw_notes = match.group(1).strip()
+              lines = raw_notes.splitlines()
+              if lines and (re.search(r"\d{4}-\d{1,2}-\d{1,2}", lines[0]) or not lines[0].strip()):
+                  notes = "\n".join(lines[1:]).strip()
+              else:
+                  notes = raw_notes
+          if not notes:
+              notes = "No changelog entry found for this release."
+          github_output = os.environ.get("GITHUB_OUTPUT")
+          if github_output:
+              delimiter = f"EOF_{uuid.uuid4().hex}"
+              with open(github_output, "a") as f:
+                  f.write(f"body<<{delimiter}\n{notes}\n{delimiter}\n")
+          '
+
+      # ── GitHub Release ────────────────────────────────────────────────
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v3
+        with:
+          name: Teridex ${{ github.ref_name }}
+          body: ${{ steps.extract_changelog.outputs.body }}
+          files: |
+            dist/*
+            SHA256SUMS
+          generate_release_notes: false
+
+      # ── PyPI Publish ──────────────────────────────────────────────────
+      - name: Publish package distributions to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

teridex-0.1.0/.gitignore

@@ -0,0 +1,110 @@
+# ── OS / System ──────────────────────────────────────────────────────
+.DS_Store
+.DS_Store?
+._*
+.Spotlight-V100
+.Trashes
+ehthumbs.db
+Thumbs.db
+desktop.ini
+
+# ── IDEs and Editors ────────────────────────────────────────────────
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+*.bak
+*.sublime-project
+*.sublime-workspace
+
+# ── Python bytecode / runtime ───────────────────────────────────────
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+
+# ── Distribution / Packaging ───────────────────────────────────────
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# ── Virtual Environments and uv ────────────────────────────────────
+.venv/
+venv/
+env/
+.uv-cache/
+pip-wheel-metadata/
+
+# ── Linting / Type-checking / Testing ──────────────────────────────
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+.hypothesis/
+.nox/
+.tox/
+.dmypy.json
+dmypy.json
+.pre-commit-cache/
+
+# ── Coverage ────────────────────────────────────────────────────────
+.coverage
+.coverage.*
+htmlcov/
+coverage.xml
+*.cover
+
+# ── Jupyter / Notebooks ────────────────────────────────────────────
+.ipynb_checkpoints/
+
+# ── Environment / Secrets ──────────────────────────────────────────
+.env
+.env.*
+!.env.example
+!.env.template
+config.toml
+!config.example.toml
+
+# ── Docker (local overrides) ───────────────────────────────────────
+docker-compose.override.yml
+
+# ── Teridex (project-specific) ─────────────────────────────────────
+*.db
+*.sqlite
+*.sqlite3
+*.duckdb
+*.log
+teridex.log
+.teridex/
+scratch/
+
+# ── AI Tools ────────────────────────────────────────────────────────
+.openai/
+.chatgpt/
+gpt-config.json
+openai.config.json
+.anthropic/
+.claude/
+claude.config.json
+claude-settings.json
+.prompts/
+.prompt-cache/
+.ai/
+.antigravitycli/
+.gemini/
+CLAUDE.md

teridex-0.1.0/.python-version

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

teridex-0.1.0/CHANGELOG.md

@@ -0,0 +1,12 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2026-06-10
+
+### Added
+
+- First implementation of Teridex.

teridex-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,152 @@
+# Contributing to Teridex 📟
+
+Thank you for your interest in contributing to **Teridex**! We welcome and appreciate contributions of all kinds, whether you are fixing a bug, adding database drivers, improving the TUI/CLI, or updating documentation.
+
+This guide details our local development setup, code standards, test architecture, and submission workflow.
+
+---
+
+## 🚀 Setup & Installation
+
+To develop Teridex locally, you will need:
+- **Python >= 3.13**
+- The [**`uv`**](https://docs.astral.sh/uv/) package manager (`brew install uv` or see [uv installation guide](https://docs.astral.sh/uv/))
+
+Clone the repository and sync the workspace virtual environment and dependencies:
+
+```bash
+git clone https://github.com/salvatorecorvaglia/teridex.git
+cd teridex
+./scripts/dev.sh
+```
+
+> [!NOTE]
+> The `./scripts/dev.sh` script runs `uv sync --all-extras --dev` under the hood.
+
+---
+
+## 🛠️ Day-to-Day Commands
+
+We provide utility scripts inside the `scripts/` directory to run formatting, type checks, and test suites.
+
+| Task | Command | Description |
+| :--- | :--- | :--- |
+| **All Gates** | `./scripts/check.sh` | Runs formatting check, lint check, type check, and unit tests in one command. |
+| **Format & Autofix** | `./scripts/fmt.sh` | Formats Python code and autofixes auto-resolvable lint issues. |
+| **Lint & Type Check** | `./scripts/lint.sh` | Performs formatting checks, Ruff lint checks, and strict Mypy checks. |
+| **Unit Tests** | `./scripts/test.sh` | Runs the offline test suite and outputs terminal coverage. |
+| **Start Docker DBs** | `docker compose -f docker/docker-compose.yml up -d` | Spins up PostgreSQL and MySQL instances for integration tests. |
+| **Integration Tests** | `TERIDEX_PG_DSN=... TERIDEX_MYSQL_DSN=... TERIDEX_TEST_MARKERS=integration ./scripts/test.sh` | Executes integration test suite against the Docker DB instances. |
+
+> [!TIP]
+> The `./scripts/check.sh` script forwards additional arguments directly to `pytest`.
+> For example: `./scripts/check.sh -k schema_tree -v` will run the full lint and type stacks, and then execute only the tests matching `schema_tree` in verbose mode.
+
+---
+
+## 📐 Package Architecture & Layering
+
+Teridex follows a clean, layered architecture with strict dependency boundaries:
+
+```mermaid
+graph TD
+    core["teridex-core (Pure Domain)"]
+    adapters["teridex-adapters (DB Drivers)"]
+    plugins["teridex-plugins (Plugin API)"]
+    engine["teridex-engine (Orchestration)"]
+    tui["teridex-tui (Textual TUI)"]
+    cli["teridex-cli (Typer CLI)"]
+
+    adapters --> core
+    plugins --> core
+    engine --> adapters
+    engine --> plugins
+    tui --> engine
+    cli --> engine
+```
+
+> [!IMPORTANT]
+> **Layering Rule**: Inner packages must never depend on outer packages. Specifically, `teridex_core` must depend on zero internal packages. Outer packages (like `teridex-tui` and `teridex-cli`) may depend on inner packages, but never vice versa. This boundary is strictly enforced by `mypy --strict`.
+
+---
+
+## 🧪 Test Architecture & Coverage
+
+The test suite mirrors our layered package structure:
+
+*   **TUI & UI Component Tests** (`tests/tui/`): Covers screen and widget behavior, rendering states, help modals, schema tree displays, and vim keymap behavior (e.g., `test_app_smoke.py`, `test_schema_tree.py`, `test_results_pane.py`).
+*   **Adapter Conformance Tests** (`tests/adapters/`): Verifies database driver implementations. All adapters must pass the shared conformance scenarios located in `tests/adapters/_conformance.py`.
+*   **Engine Execution & Pool Orchestration** (`tests/engine/`): Tests transaction boundaries, `QueryExecutor` flow, `ConnectionPool` concurrency, and `QueryHistory` persistence.
+*   **Core Logic & Infrastructure** (`tests/core/`): Tests dependency injection (`test_di.py`), JSON/structured logging formatters, custom configuration layers (`test_config.py`), and the event bus (`test_events.py`).
+*   **Plugin Lifecycle** (`tests/plugins/`): Verifies API hooks, plugin load discovery, and context isolation.
+
+### Code Coverage
+
+> [!WARNING]
+> The project enforces a **minimum 70% branch coverage** gate (`fail_under = 70` in `pyproject.toml`).
+> Running `./scripts/test.sh` locally generates a `term-missing` coverage report. Please ensure your contributions include tests that maintain or improve coverage.
+
+---
+
+## 🎨 Coding Standards
+
+To maintain predictability, performance, and robustness, all code submissions must adhere to the following standards:
+
+1.  **Strict Static Typing**: Mypy strict mode is enabled across the codebase. All public and private functions must have complete type signatures.
+2.  **Formatting and Styling**: Standardized via **Ruff** (line length: 100). Run `./scripts/fmt.sh` before staging commits.
+3.  **Async-First Event Loop**: Never execute blocking I/O operations directly within the TUI event loop or database adapters.
+4.  **No Silent Exceptions**: Do not suppress exceptions silently. Every catch block must log, wrap, or re-raise appropriately.
+5.  **Plugin Event Subscriptions**: Always register handlers via `PluginContext.subscribe` (which tracks subscriptions locally) instead of calling the event bus directly. This prevents memory leaks and orphaned tasks when plugins are dynamically unloaded.
+6.  **Adapter Locking Guidelines**: When implementing or editing adapters with blocking interfaces (such as DuckDB), ensure all operations that touch connection handles are synchronized under the adapter's `self._lock` and offloaded using `asyncio.to_thread`.
+7.  **Database Statement Classification**: Inspect prepared statement attributes (e.g., `stmt.get_attributes()` in `asyncpg`) to differentiate query execution types (DQL/DML) instead of parsing raw string prefixes. This ensures robust handling of comments and `RETURNING` clauses.
+8.  **Small, Composed Modules**: Prefer composition over inheritance. Keep modules small and highly focused.
+9.  **EditorConfig**: We ship an `.editorconfig` specifying UTF-8, LF, and 4-space indentation (2-space for configuration formats like YAML, TOML, and JSON). Ensure your editor configuration honors these guidelines.
+
+---
+
+## 🔌 Adding a Database Adapter
+
+If you are implementing support for a new database, follow these steps:
+
+1.  Create a subclass of `AbstractAdapter` in `packages/teridex-adapters/src/teridex_adapters/<name>_adapter.py`.
+2.  Define the class variables `name: ClassVar[str]` and `schemes: ClassVar[tuple[str, ...]]`.
+3.  Implement the required methods: `_do_connect`, `_do_close`, `ping`, `execute`, `stream`, `begin`, and `introspect`.
+4.  Register your new adapter class in `teridex_adapters/registry.py::_build_default`.
+5.  Add a parametrized conformance test under `tests/adapters/` using the shared scenarios in `tests/adapters/_conformance.py`.
+
+---
+
+## 🚀 Pull Request Workflow
+
+1.  **Fork & Branch**: Fork the repository and create a feature branch off of `main` (e.g., `feature/my-db-adapter`).
+2.  **Develop**: Implement your changes and write unit tests to cover them.
+3.  **Lint & Format**: Run `./scripts/fmt.sh` to tidy your code.
+4.  **Validate Locally**: Run `./scripts/check.sh` to ensure formatting, types, and tests all pass locally.
+5.  **Submit PR**: Open a pull request against the `main` branch. Provide a clear description of the problem solved and the implementation details.
+
+---
+
+## 📦 Releasing
+
+Releases are automated via GitHub Actions (`.github/workflows/release.yml`) when a version tag is pushed. To prepare and cut a release:
+
+1.  Update `CHANGELOG.md` (graduate the `[Unreleased]` stanza to the new version).
+2.  Bump `version = "x.y.z"` in the root `pyproject.toml` and `__version__` in `src/teridex_core/__init__.py`.
+3.  Run `uv sync --all-extras --dev` to refresh `uv.lock`.
+4.  Run `./scripts/check.sh` and ensure it exits `0`.
+5.  Commit changes to `main` and push.
+6.  Create and push a version tag:
+    ```bash
+    git tag vx.y.z
+    git push origin vx.y.z
+    ```
+
+---
+
+## 📜 Code of Conduct
+
+Please maintain a respectful, supportive, and professional tone in all communication (issues, PR reviews, commit logs).
+
+---
+
+Happy coding! 📟

teridex-0.1.0/CONTRIBUTORS.md

@@ -0,0 +1,11 @@
+# Contributors 👥
+
+A huge thank you to everyone who has contributed to **Teridez**!
+
+## ✨ Lead Maintainer
+
+- **Salvatore Corvaglia** ([@salvatorecorvaglia](https://github.com/salvatorecorvaglia))
+
+## 🌟 Contributors
+
+_Want to contribute? Check out [CONTRIBUTING.md](./CONTRIBUTING.md) to get started!_

teridex-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 **salvatorecorvaglia** (https://github.com/salvatorecorvaglia)
+
+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.