registro-db 1.0.0__tar.gz

registro_db-1.0.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

registro_db-1.0.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.

registro_db-1.0.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:**

registro_db-1.0.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

registro_db-1.0.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

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

@@ -0,0 +1,77 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+    paths-ignore:
+      - '**.md'
+      - 'docs/**'
+  pull_request:
+    paths-ignore:
+      - '**.md'
+      - 'docs/**'
+  workflow_dispatch:
+  workflow_call:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+permissions:
+  contents: read
+
+jobs:
+  lint:
+    runs-on: ubuntu-24.04
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v8.1.0
+        with:
+          enable-cache: true
+          cache-suffix: "lint"
+          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-24.04, macos-15]
+      fail-fast: false
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v8.1.0
+        with:
+          enable-cache: true
+          cache-suffix: "test"
+          python-version: "3.13"
+
+      - name: Sync workspace
+        run: uv sync --all-extras --dev --frozen
+
+      - name: Test (pytest + coverage gate)
+        run: ./tests/scripts/test.sh
+        env:
+          REGISTRO_TEST_MARKERS: ${{ matrix.os == 'ubuntu-24.04' && 'integration or not integration' || 'not integration' }}
+
+  dependency-review:
+    name: Dependency Review
+    runs-on: ubuntu-24.04
+    if: github.event_name == 'pull_request'
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v6
+      - name: Dependency Review
+        uses: actions/dependency-review-action@v4

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

@@ -0,0 +1,104 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  validate:
+    runs-on: ubuntu-24.04
+    steps:
+      - uses: actions/checkout@v6
+      - name: Install uv
+        uses: astral-sh/setup-uv@v8.1.0
+        with:
+          enable-cache: true
+          python-version: "3.13"
+      - name: Validate tag version against pyproject.toml
+        run: |
+          if [[ "$GITHUB_REF" == refs/tags/v* ]]; then
+            TAG_VERSION="${GITHUB_REF#refs/tags/v}"
+            PY_VERSION=$(uv run python -c 'import tomllib; print(tomllib.load(open("pyproject.toml", "rb"))["project"]["version"])')
+            echo "Tag version: $TAG_VERSION | pyproject.toml version: $PY_VERSION"
+            if [[ "$TAG_VERSION" != "$PY_VERSION" ]]; then
+              echo "::error::Tag version ($TAG_VERSION) does not match pyproject.toml version ($PY_VERSION)"
+              exit 1
+            fi
+          fi
+
+  checks:
+    uses: ./.github/workflows/ci.yml
+
+  release:
+    needs: [validate, checks]
+    runs-on: ubuntu-24.04
+    environment: release
+    permissions:
+      contents: write
+      id-token: write
+    steps:
+      - uses: actions/checkout@v6
+
+      - 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: Build packages
+        run: uv build --out-dir dist
+
+      - name: Generate Checksums
+        run: |
+          (cd dist && sha256sum *.tar.gz *.whl) > 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")
+          '
+
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v3
+        with:
+          name: Registro ${{ github.ref_name }}
+          body: ${{ steps.extract_changelog.outputs.body }}
+          files: |
+            dist/*.tar.gz
+            dist/*.whl
+            SHA256SUMS
+          generate_release_notes: false
+
+      - name: Publish package distributions to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

registro_db-1.0.0/.gitignore

@@ -0,0 +1,119 @@
+# 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/
+.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
+
+# Registro (project-specific runtime & storage)
+*.db
+*.sqlite
+*.sqlite3
+*.duckdb
+*.log
+registro.log
+.registro/
+scratch/
+
+# IDEs and Editors
+.vscode/
+.idea/
+.zed/
+*.swp
+*.swo
+*~
+*.bak
+*.sublime-project
+*.sublime-workspace
+
+# OS / System
+.DS_Store
+.DS_Store?
+._*
+.Spotlight-V100
+.Trashes
+ehthumbs.db
+Thumbs.db
+desktop.ini
+
+# AI Tools & Agents
+.openai/
+.chatgpt/
+gpt-config.json
+openai.config.json
+.anthropic/
+.claude/
+claude.config.json
+claude-settings.json
+.prompts/
+.prompt-cache/
+.ai/
+.gemini/
+.antigravity/
+.antigravitycli/
+.copilot/
+.codex/
+.cagent/
+.cursor/
+.windsurf/
+.cline/
+CLAUDE.md

registro_db-1.0.0/.python-version

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

registro_db-1.0.0/CHANGELOG.md

@@ -0,0 +1,14 @@
+# 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).
+
+## [Unreleased]
+
+## [1.0.0] - 2026-09-23
+
+### Added
+
+- First implementation of Registro.

registro_db-1.0.0/CONTRIBUTING.md

@@ -0,0 +1,252 @@
+# Contributing to Registro 📟
+
+Thank you for your interest in contributing to **Registro**! We welcome contributions, bug reports, feature requests, and security improvements from the community.
+
+---
+
+## 🛠️ Development Setup
+
+Registro uses [uv](https://github.com/astral-sh/uv) for fast, modern Python package management and workflow orchestration.
+
+### Prerequisites
+
+- **Python 3.13 or newer**
+- **uv** (Install via `curl -LsSf https://astral.sh/uv/install.sh | sh` or your package manager)
+
+### Quick Start
+
+1. **Fork and Clone the Repository**
+   ```bash
+   git clone https://github.com/YOUR_USERNAME/registro.git
+   cd registro
+   ```
+
+2. **Synchronize Dependencies**
+   Initialize the virtual environment and install all packages (including development packages and all database extras):
+   ```bash
+   uv sync --all-extras --dev
+   ```
+   *Alternatively, run `./scripts/dev.sh` to initialize the environment.*
+
+3. **Activate the Environment**
+   ```bash
+   source .venv/bin/activate
+   ```
+
+---
+
+## ⚙️ Coding Standards & Tools
+
+We use strict quality gates to maintain codebase health. All of these run automatically on CI, but you should run them locally before submitting changes.
+
+### Developer Scripts
+
+We provide dedicated helper scripts under `scripts/` to streamline local workflows:
+
+| Script | Purpose |
+| :--- | :--- |
+| `./scripts/dev.sh` | Synchronizes virtual environment with all extras and dev dependencies |
+| `./scripts/fmt.sh` | Formats code with Ruff and applies safe linter autofixes |
+| `./scripts/lint.sh` | Runs Ruff format check, Ruff lint check, and MyPy strict type check |
+| `./scripts/test.sh` | Runs the offline test suite with coverage reporting |
+| `./scripts/check.sh` | The pre-PR quality gate (runs `./scripts/lint.sh` and `./scripts/test.sh`) |
+
+### Manual Linting & Formatting
+
+We use **Ruff** for formatting and linting, and **MyPy** for strict static type checking:
+
+- **Check formatting:**
+  ```bash
+  uv run ruff format --check .
+  ```
+- **Format code:**
+  ```bash
+  uv run ruff format .
+  # Or run ./scripts/fmt.sh
+  ```
+- **Lint code:**
+  ```bash
+  uv run ruff check .
+  ```
+- **Strict type checking:**
+  ```bash
+  uv run mypy --config-file=mypy.ini src
+  ```
+
+---
+
+## 🧪 Testing
+
+We use **Pytest** for running our test suite with strict coverage requirements.
+
+- **Run unit tests (offline suite):**
+  ```bash
+  uv run pytest -m "not integration" --cov=src
+  # Or simply:
+  ./scripts/test.sh
+  ```
+- **Run integration tests (requires Docker daemon for PostgreSQL and MySQL):**
+  ```bash
+  ./tests/scripts/test-integration.sh
+  ```
+
+### Coverage Quality Gate
+
+Our test suite enforces an **84% minimum test coverage gate** (`fail_under = 84` in `pyproject.toml`). The offline suite run must satisfy this gate on its own without relying on server-backed integration tests.
+
+### The Ultimate Quality Gate
+
+Before submitting any Pull Request, ensure that formatting, linting, type-checking, and test coverage all pass cleanly by running:
+```bash
+./scripts/check.sh
+```
+
+---
+
+## 🔌 Writing Plugins
+
+Registro features an extensible, plugin-first architecture. You can contribute new plugins or create external plugins to add dockable panels, custom commands, and event listeners.
+
+### Plugin Protocol
+
+A Registro plugin implements the structural `Plugin` protocol (`registro_core.protocols.plugin.Plugin`):
+
+```python
+from registro_core.protocols.plugin import PluginManifest
+from registro_plugins.context import PluginContext
+
+
+class MyPlugin:
+    manifest = PluginManifest(
+        id="my_plugin",
+        name="My Plugin",
+        version="1.0.0",
+        description="A custom Registro plugin",
+    )
+
+    def on_load(self, ctx: PluginContext) -> None:
+        """Called when the plugin is loaded."""
+        ...
+
+    def on_unload(self, ctx: PluginContext) -> None:
+        """Called when the plugin is unloaded or during app shutdown."""
+        ...
+```
+
+### Packaging & Discovery
+
+Plugins are discovered dynamically via Python entry points in the `registro.plugins` group. Add the following to your `pyproject.toml`:
+
+```toml
+[project.entry-points."registro.plugins"]
+my_plugin = "my_package.plugin:MyPlugin"
+```
+
+You can verify that Registro discovers your plugin by running:
+```bash
+registro plugins list
+```
+
+### Subscribing to Event Bus Hooks
+
+Plugins can subscribe to asynchronous lifecycle events on the `EventBus`. Key events defined in [events.py](src/registro_core/events.py) include:
+
+- `ConnectionOpened` / `ConnectionClosed`
+- `QueryStarted` / `QueryProgress` / `QueryCompleted` / `QueryFailed` / `QueryCancelled`
+- `SchemaRefreshed`
+- `PluginLoaded` / `PluginUnloaded`
+
+The `@hook` decorator tags a method with the target event name. In `on_load`, subscribe your handler to the event class via `ctx.subscribe`:
+
+```python
+from registro_core.events import QueryStarted
+from registro_plugins.api import hook, hook_event, is_hook
+from registro_plugins.context import PluginContext
+
+
+class QueryLoggerPlugin:
+    manifest = PluginManifest(id="query_logger", name="Query Logger")
+
+    @hook("query.started")
+    async def handle_query_started(self, ev: QueryStarted) -> None:
+        # Asynchronously handle query start
+        pass
+
+    def on_load(self, ctx: PluginContext) -> None:
+        for name in dir(self):
+            fn = getattr(self, name)
+            if is_hook(fn) and hook_event(fn) == "query.started":
+                ctx.subscribe(QueryStarted, fn)
+
+    def on_unload(self, ctx: PluginContext) -> None:
+        pass
+```
+
+### Registering Commands and Panels
+
+Plugins can contribute actions to the fuzzy command palette (`Ctrl+P`) and dockable panels to the main UI:
+
+```python
+from textual.widgets import Static
+from registro_plugins.api import Command, Panel
+from registro_plugins.context import PluginContext
+
+
+class AnalyticsPlugin:
+    manifest = PluginManifest(id="analytics", name="Analytics")
+
+    def on_load(self, ctx: PluginContext) -> None:
+        # Register a command for the command palette (Ctrl+P)
+        async def run_diagnostics(context: PluginContext) -> None:
+            context.logger.info("Diagnostics started")
+
+        ctx.register_command(
+            Command(
+                id="analytics.diagnostics",
+                title="Run Database Diagnostics",
+                handler=run_diagnostics,
+                category="Analytics",
+            )
+        )
+
+        # Register a dockable panel ("left", "right", or "bottom")
+        def create_panel(_context: PluginContext) -> Static:
+            return Static("★ Analytics Rail Content", id="analytics-panel-content")
+
+        ctx.register_panel(
+            Panel(
+                id="analytics.sidebar",
+                title="Analytics",
+                placement="right",
+                factory=create_panel,
+                initial_size=30,
+            )
+        )
+
+    def on_unload(self, ctx: PluginContext) -> None:
+        pass
+```
+
+### Context & Host Services
+
+Each plugin receives an isolated `PluginContext` providing:
+- `ctx.subscribe(event_class, handler)`: Register an async event handler.
+- `ctx.publish(event)`: Publish custom events across the event bus.
+- `ctx.register_command(command)`: Add an action to the fuzzy command palette.
+- `ctx.register_panel(panel)`: Mount a sidebar or bottom panel into the TUI grid.
+- `ctx.get_service(name)`: Access host services (such as `"introspector"`, `"history"`, or `"config"`).
+- `ctx.logger`: Context-bound structured logger (`logger.bind(plugin_id=...)`).
+
+---
+
+## 📥 Submitting a Pull Request
+
+1. Create a logical feature branch: `git checkout -b feature/my-cool-feature`.
+2. Write tests covering your implementation.
+3. Verify that `./scripts/check.sh` passes successfully (formatting, linting, type checks, and 84% coverage gate).
+4. Commit your changes with clear, descriptive commit messages.
+5. Push to your fork and open a Pull Request.
+
+---
+
+Happy coding! 📟

registro_db-1.0.0/CONTRIBUTORS.md

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