shirube 0.1.0b1__tar.gz

shirube-0.1.0b1/.gitignore

@@ -0,0 +1,75 @@
+# ---- Python / FastAPI (backend) ----
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# Virtual environments
+.venv/
+venv/
+env/
+ENV/
+
+# Test / coverage
+.pytest_cache/
+.coverage
+.coverage.*
+htmlcov/
+.tox/
+.mypy_cache/
+.ruff_cache/
+
+# ---- Node / Vite (frontend) ----
+node_modules/
+.pnp
+.pnp.js
+# pnpm's content-addressable store, if it lands inside the repo.
+.pnpm-store/
+web/dist/
+dist-ssr/
+*.local
+
+# Bundled SPA (generated into the API package at build time)
+api/src/shirube/static/
+
+# ---- Development database ----
+# pagila SQL fetched by scripts/dev-db.sh; not vendored into the repo.
+dev/pagila/
+
+# Logs
+logs/
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+
+# ---- Secrets / local config ----
+.env
+.env.*
+!.env.example
+
+# ---- Editors / OS ----
+.vscode/*
+!.vscode/settings.json
+!.vscode/extensions.json
+.idea/
+.claude/settings.local.json
+*.swp
+*.swo
+.DS_Store
+Thumbs.db

shirube-0.1.0b1/PKG-INFO

@@ -0,0 +1,119 @@
+Metadata-Version: 2.4
+Name: shirube
+Version: 0.1.0b1
+Summary: Understand your database as a map — built for the AI-coding era.
+License-Expression: AGPL-3.0-or-later
+Requires-Python: >=3.11
+Requires-Dist: fastapi>=0.115
+Requires-Dist: keyring>=25.7.0
+Requires-Dist: platformdirs>=4.2
+Requires-Dist: psycopg[binary]>=3.3.4
+Requires-Dist: pydantic-settings>=2.4
+Requires-Dist: sqlalchemy>=2.0
+Requires-Dist: structlog>=25.1.0
+Requires-Dist: uvicorn[standard]>=0.51.0
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/shou-taro/shirube/main/docs/images/logo.svg" width="88" alt="shirube" />
+</p>
+
+<h1 align="center">shirube</h1>
+
+<p align="center">
+  <strong>AI writes the SQL.<br />You still own the schema.</strong><br />
+  <sub>標べ — a signpost for reading a database as a map.</sub>
+</p>
+
+<p align="center">
+  <a href="https://github.com/shou-taro/shirube/actions/workflows/ci.yml"><img src="https://github.com/shou-taro/shirube/actions/workflows/ci.yml/badge.svg" alt="CI" /></a>
+  <img src="https://img.shields.io/badge/status-beta-a78bfa" alt="Status: beta" />
+  <a href="https://github.com/shou-taro/shirube/blob/main/LICENSE"><img src="https://img.shields.io/badge/licence-AGPL--3.0-blue" alt="Licence: AGPL-3.0" /></a>
+  <img src="https://img.shields.io/badge/PostgreSQL-ready-336791?logo=postgresql&logoColor=white" alt="PostgreSQL" />
+</p>
+
+> 🚧 **Status: Beta.** The explorer core is here and usable today. The AI navigator — the
+> feature shirube is ultimately built around — is the next milestone. shirube is pre-1.0:
+> things may still change.
+
+<p align="center"><em>See the whole database as a map.</em></p>
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/shou-taro/shirube/main/docs/images/home.png" alt="shirube exploring a database: an ER diagram with a table's detail and its rows" width="960" />
+</p>
+
+## 🤖 Why shirube
+
+You write less SQL by hand than you used to — an AI writes much of it for you. But that
+SQL still runs against **your** schema, and someone still has to understand that schema:
+to prompt the AI well, to check what it gave back, to reason about where the data
+actually lives. That understanding used to come for free while you wrote the queries
+yourself. It doesn't any more.
+
+shirube is where that understanding lives — and it's just as useful in the classic case,
+dropping into a project with hundreds of undocumented tables and needing to find your
+footing fast.
+
+> AI changed how we write SQL. shirube changes how we understand databases.
+
+## 🧭 What shirube does
+
+shirube opens on an interactive ER diagram and lets you explore a database like a map:
+search for a table, focus on it, and follow its relationships outward — so you can see
+how everything connects without reading DDL or writing a single query.
+
+It is **not** another SQL IDE or database administration console — there is no query
+editor, and nothing that ever writes. shirube is a tool for *understanding* a database.
+
+## ✨ Features
+
+Everything below works today, in the beta:
+
+- 🗺️ **ER diagram home** — auto-generated and centred on the most-connected table; see a
+  table and its immediate neighbours, and travel outward one hop at a time.
+- 📋 **Table detail** — columns with their types, primary keys and nullability, plus
+  relationships split into *references* and *referenced by*.
+- 🔗 **Relationship navigation** — click a related table to glide the map over to it.
+- 👁️ **Data preview** — read a table or view's actual rows in a drawer, with click-to-sort
+  columns, simple filters and paging.
+- ⚡ **Instant search** — jump straight to any table or column.
+- 🔐 **Saved connections** — passwords kept in your operating system's keychain, never in
+  a config file.
+- 🌗 **Light and dark themes.**
+
+## 🛡️ Safe by design
+
+- 🔒 **Read-only** — every connection is opened read-only with a statement timeout. shirube
+  cannot modify your database — no writes, no schema changes, ever.
+- 💻 **Local-first** — it runs on your machine and binds to `127.0.0.1` only. Your database
+  credentials and data never leave your computer.
+- 📝 **Metadata-only logging** — the local log records errors and request timings, but
+  never the values in your data.
+
+## 🚀 Getting started
+
+You'll need a PostgreSQL database to point shirube at, and a way to run a Python
+application without installing it permanently.
+
+> The beta is tested on **macOS** and **Windows**. Linux support is planned.
+
+```bash
+pipx run shirube   # with pipx
+# or
+uvx shirube        # with uv
+```
+
+Either command starts a small local server and opens shirube in your browser. Add a
+connection with your PostgreSQL details, and shirube inspects the schema and opens the ER
+diagram.
+
+> 💡 shirube connects with whatever credentials you give it. A read-only role with
+> `CONNECT` and `SELECT` is all it needs — and all it should have.
+
+## 📚 Learn more
+
+- **Full README, roadmap and the AI-navigator preview** —
+  <https://github.com/shou-taro/shirube>
+- **Contributing** —
+  <https://github.com/shou-taro/shirube/blob/main/CONTRIBUTING.md>
+- **Licence** — [GNU AGPL-3.0](https://github.com/shou-taro/shirube/blob/main/LICENSE)

shirube-0.1.0b1/README.md

@@ -0,0 +1,103 @@
+<p align="center">
+  <img src="https://raw.githubusercontent.com/shou-taro/shirube/main/docs/images/logo.svg" width="88" alt="shirube" />
+</p>
+
+<h1 align="center">shirube</h1>
+
+<p align="center">
+  <strong>AI writes the SQL.<br />You still own the schema.</strong><br />
+  <sub>標べ — a signpost for reading a database as a map.</sub>
+</p>
+
+<p align="center">
+  <a href="https://github.com/shou-taro/shirube/actions/workflows/ci.yml"><img src="https://github.com/shou-taro/shirube/actions/workflows/ci.yml/badge.svg" alt="CI" /></a>
+  <img src="https://img.shields.io/badge/status-beta-a78bfa" alt="Status: beta" />
+  <a href="https://github.com/shou-taro/shirube/blob/main/LICENSE"><img src="https://img.shields.io/badge/licence-AGPL--3.0-blue" alt="Licence: AGPL-3.0" /></a>
+  <img src="https://img.shields.io/badge/PostgreSQL-ready-336791?logo=postgresql&logoColor=white" alt="PostgreSQL" />
+</p>
+
+> 🚧 **Status: Beta.** The explorer core is here and usable today. The AI navigator — the
+> feature shirube is ultimately built around — is the next milestone. shirube is pre-1.0:
+> things may still change.
+
+<p align="center"><em>See the whole database as a map.</em></p>
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/shou-taro/shirube/main/docs/images/home.png" alt="shirube exploring a database: an ER diagram with a table's detail and its rows" width="960" />
+</p>
+
+## 🤖 Why shirube
+
+You write less SQL by hand than you used to — an AI writes much of it for you. But that
+SQL still runs against **your** schema, and someone still has to understand that schema:
+to prompt the AI well, to check what it gave back, to reason about where the data
+actually lives. That understanding used to come for free while you wrote the queries
+yourself. It doesn't any more.
+
+shirube is where that understanding lives — and it's just as useful in the classic case,
+dropping into a project with hundreds of undocumented tables and needing to find your
+footing fast.
+
+> AI changed how we write SQL. shirube changes how we understand databases.
+
+## 🧭 What shirube does
+
+shirube opens on an interactive ER diagram and lets you explore a database like a map:
+search for a table, focus on it, and follow its relationships outward — so you can see
+how everything connects without reading DDL or writing a single query.
+
+It is **not** another SQL IDE or database administration console — there is no query
+editor, and nothing that ever writes. shirube is a tool for *understanding* a database.
+
+## ✨ Features
+
+Everything below works today, in the beta:
+
+- 🗺️ **ER diagram home** — auto-generated and centred on the most-connected table; see a
+  table and its immediate neighbours, and travel outward one hop at a time.
+- 📋 **Table detail** — columns with their types, primary keys and nullability, plus
+  relationships split into *references* and *referenced by*.
+- 🔗 **Relationship navigation** — click a related table to glide the map over to it.
+- 👁️ **Data preview** — read a table or view's actual rows in a drawer, with click-to-sort
+  columns, simple filters and paging.
+- ⚡ **Instant search** — jump straight to any table or column.
+- 🔐 **Saved connections** — passwords kept in your operating system's keychain, never in
+  a config file.
+- 🌗 **Light and dark themes.**
+
+## 🛡️ Safe by design
+
+- 🔒 **Read-only** — every connection is opened read-only with a statement timeout. shirube
+  cannot modify your database — no writes, no schema changes, ever.
+- 💻 **Local-first** — it runs on your machine and binds to `127.0.0.1` only. Your database
+  credentials and data never leave your computer.
+- 📝 **Metadata-only logging** — the local log records errors and request timings, but
+  never the values in your data.
+
+## 🚀 Getting started
+
+You'll need a PostgreSQL database to point shirube at, and a way to run a Python
+application without installing it permanently.
+
+> The beta is tested on **macOS** and **Windows**. Linux support is planned.
+
+```bash
+pipx run shirube   # with pipx
+# or
+uvx shirube        # with uv
+```
+
+Either command starts a small local server and opens shirube in your browser. Add a
+connection with your PostgreSQL details, and shirube inspects the schema and opens the ER
+diagram.
+
+> 💡 shirube connects with whatever credentials you give it. A read-only role with
+> `CONNECT` and `SELECT` is all it needs — and all it should have.
+
+## 📚 Learn more
+
+- **Full README, roadmap and the AI-navigator preview** —
+  <https://github.com/shou-taro/shirube>
+- **Contributing** —
+  <https://github.com/shou-taro/shirube/blob/main/CONTRIBUTING.md>
+- **Licence** — [GNU AGPL-3.0](https://github.com/shou-taro/shirube/blob/main/LICENSE)

shirube-0.1.0b1/pyproject.toml

@@ -0,0 +1,68 @@
+[project]
+name = "shirube"
+version = "0.1.0b1"
+description = "Understand your database as a map — built for the AI-coding era."
+readme = "README.md"
+requires-python = ">=3.11"
+license = "AGPL-3.0-or-later"
+dependencies = [
+    "fastapi>=0.115",
+    "uvicorn[standard]>=0.51.0",
+    "sqlalchemy>=2.0",
+    "pydantic-settings>=2.4",
+    "platformdirs>=4.2",
+    "keyring>=25.7.0",
+    "psycopg[binary]>=3.3.4",
+    "structlog>=25.1.0",
+]
+
+[project.scripts]
+shirube = "shirube.__main__:main"
+
+[dependency-groups]
+dev = [
+    "ruff>=0.6",
+    "mypy>=1.11",
+    "pytest>=8.3",
+    "httpx>=0.27",
+    "bandit>=1.7",
+    "pip-audit>=2.7",
+    "hypothesis>=6.100",
+    "keyrings-alt>=5.0.2",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/shirube"]
+# Include the built SPA (generated, git-ignored) in the wheel for single-origin serving.
+artifacts = ["src/shirube/static/**/*"]
+
+[tool.hatch.build.targets.sdist]
+# Keep the sdist to the sources needed to build the wheel; exclude test caches,
+# the lockfile and other dev cruft that hatchling would otherwise sweep in.
+include = [
+    "src/shirube",
+    "README.md",
+    "pyproject.toml",
+]
+artifacts = ["src/shirube/static/**/*"]
+
+[tool.ruff]
+line-length = 100
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "N"]
+
+[tool.mypy]
+python_version = "3.11"
+strict = true
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+markers = [
+    "integration: needs a real PostgreSQL; set SHIRUBE_TEST_DATABASE_URL to run (skipped otherwise)",
+]

shirube-0.1.0b1/src/shirube/__init__.py

@@ -0,0 +1,3 @@
+"""shirube — an AI-native database explorer."""
+
+__version__ = "0.1.0b1"

shirube-0.1.0b1/src/shirube/__main__.py

@@ -0,0 +1,64 @@
+"""Entry point for ``shirube`` / ``uvx shirube``.
+
+Starts the local API server (which also serves the bundled single-page app in a
+packaged build) and, unless disabled, opens the browser once the server is up.
+"""
+
+import threading
+import webbrowser
+
+import uvicorn
+
+from shirube import __version__
+from shirube.config import get_settings
+from shirube.logging_config import setup_logging
+
+
+def _is_loopback(host: str) -> bool:
+    """Whether ``host`` refers to the local machine only (not the network)."""
+    return host in {"localhost", "::1", "[::1]"} or host.startswith("127.")
+
+
+def _open_browser(url: str) -> None:
+    """Open ``url`` in the user's default browser (best effort)."""
+    webbrowser.open(url)
+
+
+def main() -> None:
+    """Launch the shirube server and open the browser.
+
+    Binds to the configured host and port (loopback by default) and blocks while
+    uvicorn runs. The browser launch is deferred by a short timer so it fires just
+    after the server starts accepting connections rather than before.
+    """
+    settings = get_settings()
+    logger = setup_logging()
+    logger.info(
+        "starting",
+        version=__version__,
+        host=settings.host,
+        port=settings.port,
+        data_dir=str(settings.data_dir),
+    )
+    if not _is_loopback(settings.host):
+        # shirube is single-user and unauthenticated by design; binding beyond loopback
+        # exposes an unprotected API on the network, so make an accidental one loud.
+        logger.warning(
+            "bound to a non-loopback address — shirube may be reachable from your "
+            "network. It is single-user and unauthenticated; bind to 127.0.0.1 unless "
+            "you intend to expose it.",
+            host=settings.host,
+        )
+    url = f"http://{settings.host}:{settings.port}"
+    if settings.open_browser:
+        # Defer the launch slightly so the server is ready to answer the first request.
+        threading.Timer(1.0, _open_browser, args=[url]).start()
+    uvicorn.run(
+        "shirube.adapters.api.app:app",
+        host=settings.host,
+        port=settings.port,
+    )
+
+
+if __name__ == "__main__":
+    main()

shirube-0.1.0b1/src/shirube/adapters/README.md

@@ -0,0 +1,5 @@
+# adapters
+
+Concrete implementations of the ports and the delivery mechanisms: the FastAPI API
+(driving adapter), SQLAlchemy persistence, the OS keychain, database introspection,
+and AI providers. Only this layer knows about frameworks and external systems.

shirube-0.1.0b1/src/shirube/adapters/__init__.py

@@ -0,0 +1 @@
+"""Adapters — concrete implementations of ports and delivery mechanisms."""

shirube-0.1.0b1/src/shirube/adapters/api/__init__.py

@@ -0,0 +1 @@
+"""HTTP API adapter (FastAPI)."""

shirube-0.1.0b1/src/shirube/adapters/api/app.py

@@ -0,0 +1,162 @@
+"""FastAPI application factory (a driving adapter).
+
+This is the HTTP entry point into the application core. In a packaged build it also
+serves the compiled single-page app, so the whole tool runs from one process on one
+origin; in development the Vite dev server serves the UI and proxies API calls here.
+"""
+
+import time
+from collections.abc import AsyncIterator, Awaitable, Callable
+from contextlib import asynccontextmanager
+from pathlib import Path
+from uuid import uuid4
+
+import structlog
+from fastapi import FastAPI, Request, Response
+from fastapi.staticfiles import StaticFiles
+from starlette.middleware.trustedhost import TrustedHostMiddleware
+
+from shirube import __version__
+from shirube.adapters.api.errors import register_exception_handlers
+from shirube.adapters.api.routes import connections, data, health, profiles, schema
+from shirube.adapters.persistence.bootstrap import bootstrap_database
+from shirube.config import get_settings
+from shirube.logging_config import get_logger
+
+# The built SPA, copied here by scripts/build.sh and bundled into the wheel. It is
+# absent during development (git-ignored), where Vite serves the UI instead — hence the
+# existence check in create_app().
+STATIC_DIR = Path(__file__).resolve().parents[2] / "static"
+
+_logger = get_logger("shirube.request")
+
+# A conservative Content-Security-Policy for the bundled SPA. Everything is same-origin
+# (scripts, styles, the API), so only 'self' is allowed; inline styles are permitted
+# because React Flow sets element style attributes, and data: covers the inline SVG
+# favicon and logo. frame-ancestors 'none' blocks the page being framed (clickjacking).
+_CONTENT_SECURITY_POLICY = (
+    "default-src 'self'; "
+    "script-src 'self'; "
+    "style-src 'self' 'unsafe-inline'; "
+    "img-src 'self' data:; "
+    "font-src 'self' data:; "
+    "connect-src 'self'; "
+    "base-uri 'self'; "
+    "form-action 'self'; "
+    "frame-ancestors 'none'"
+)
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI) -> AsyncIterator[None]:
+    """Run start-up and shutdown work around the application's lifetime.
+
+    On start-up the local app-state database is created if missing. There is nothing to
+    tear down yet, so control simply yields back to the server.
+
+    Args:
+        app: The FastAPI application (unused; required by the lifespan signature).
+
+    Yields:
+        None, once start-up has completed.
+    """
+    bootstrap_database()
+    yield
+
+
+def create_app() -> FastAPI:
+    """Build and configure the FastAPI application.
+
+    Wires up exception handling and the API routes, and — when the SPA has been built
+    and bundled — mounts it at the root so the UI and API share a single origin.
+
+    Returns:
+        The configured application instance.
+    """
+    app = FastAPI(title="shirube", version=__version__, lifespan=lifespan)
+
+    @app.middleware("http")
+    async def _security_headers(
+        request: Request,
+        call_next: Callable[[Request], Awaitable[Response]],
+    ) -> Response:
+        """Add defence-in-depth security headers to every response.
+
+        Cheap hardening for a locally served app: stop MIME sniffing, forbid framing
+        (clickjacking), withhold the referrer, and constrain resource loading to the
+        same origin via a Content-Security-Policy.
+        """
+        response = await call_next(request)
+        response.headers["X-Content-Type-Options"] = "nosniff"
+        response.headers["X-Frame-Options"] = "DENY"
+        response.headers["Referrer-Policy"] = "no-referrer"
+        response.headers["Content-Security-Policy"] = _CONTENT_SECURITY_POLICY
+        return response
+
+    @app.middleware("http")
+    async def _log_requests(
+        request: Request,
+        call_next: Callable[[Request], Awaitable[Response]],
+    ) -> Response:
+        """Log each request's outcome — method, path, status and duration.
+
+        A short ``request_id`` is bound for the lifetime of the request and attached to
+        every event logged while it runs (here and in the error handler), so the lines
+        belonging to one request can be tied together; it is also returned to the caller
+        in the ``X-Request-ID`` header. Only metadata is recorded: never the query string,
+        request body or response content, so filter values and row data stay out of the
+        log. An exception that escapes the handlers (a genuine bug) is logged with its
+        traceback and re-raised for FastAPI's default 500.
+        """
+        request_id = uuid4().hex[:12]
+        structlog.contextvars.bind_contextvars(request_id=request_id)
+        start = time.perf_counter()
+        try:
+            response = await call_next(request)
+            elapsed_ms = (time.perf_counter() - start) * 1000
+            _logger.info(
+                "request",
+                method=request.method,
+                path=request.url.path,
+                status=response.status_code,
+                duration_ms=round(elapsed_ms),
+            )
+            response.headers["X-Request-ID"] = request_id
+            return response
+        except Exception:
+            elapsed_ms = (time.perf_counter() - start) * 1000
+            _logger.exception(
+                "request_failed",
+                method=request.method,
+                path=request.url.path,
+                duration_ms=round(elapsed_ms),
+            )
+            raise
+        finally:
+            # Always clear the request-scoped context so it never bleeds into the next
+            # request handled on this task.
+            structlog.contextvars.unbind_contextvars("request_id")
+
+    # Reject requests whose Host header is not a name we serve, added last so it runs
+    # outermost — a bad host is refused before any handler or logging runs. This is the
+    # core DNS-rebinding defence: it stops a page on another origin from reaching this
+    # local API by pointing its own hostname at 127.0.0.1. The bind host is always
+    # allowed alongside the configured names.
+    settings = get_settings()
+    allowed_hosts = list(dict.fromkeys([*settings.allowed_hosts, settings.host]))
+    app.add_middleware(TrustedHostMiddleware, allowed_hosts=allowed_hosts)
+
+    register_exception_handlers(app)
+    app.include_router(health.router, prefix="/api")
+    app.include_router(profiles.router, prefix="/api")
+    app.include_router(connections.router, prefix="/api")
+    app.include_router(schema.router, prefix="/api")
+    app.include_router(data.router, prefix="/api")
+    if STATIC_DIR.is_dir():
+        # Mounted after the API router so "/api/*" matches first; this then catches
+        # every remaining path and serves index.html for "/".
+        app.mount("/", StaticFiles(directory=STATIC_DIR, html=True), name="spa")
+    return app
+
+
+app = create_app()