sqlide 0.1.0__tar.gz

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

@@ -0,0 +1,37 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-java@v4
+        with:
+          distribution: temurin
+          java-version: "21"
+      - uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+      - run: uv sync --locked
+      - run: uv run ruff check
+      - run: uv run ruff format --check
+      - run: uv run pyright
+      - name: Tests
+        shell: bash
+        run: uv run pytest -q --tb=short -p no:cacheprovider 2>&1 | tee pytest.log; exit "${PIPESTATUS[0]}"
+      - name: Show failures as annotations
+        if: failure()
+        shell: bash
+        run: |
+          grep -E "^(FAILED|ERROR)|Error|assert " pytest.log | head -30 | while IFS= read -r line; do
+            echo "::error::${line:0:400}"
+          done

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

@@ -0,0 +1,17 @@
+name: Release
+
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  pypi:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write # PyPI trusted publishing, no token stored
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - run: uv build
+      - run: uv publish

sqlide-0.1.0/.gitignore

@@ -0,0 +1,7 @@
+.venv/
+__pycache__/
+*.pyc
+.pytest_cache/
+.ruff_cache/
+dist/
+tests/.cache/

sqlide-0.1.0/.python-version

@@ -0,0 +1 @@
+3.12

sqlide-0.1.0/LICENSE

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

sqlide-0.1.0/PKG-INFO

@@ -0,0 +1,151 @@
+Metadata-Version: 2.5
+Name: sqlide
+Version: 0.1.0
+Summary: Terminal SQL IDE (DataGrip-like) over JDBC
+Project-URL: Homepage, https://github.com/XFaIT/sqlide
+Project-URL: Repository, https://github.com/XFaIT/sqlide
+Project-URL: Issues, https://github.com/XFaIT/sqlide/issues
+Author: XFaIT
+License: MIT
+License-File: LICENSE
+Keywords: database,datagrip,jdbc,sql,terminal,tui
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Database :: Front-Ends
+Requires-Python: >=3.12
+Requires-Dist: httpx>=0.27
+Requires-Dist: jpype1>=1.5
+Requires-Dist: openpyxl>=3.1
+Requires-Dist: platformdirs>=4
+Requires-Dist: sqlglot>=25
+Requires-Dist: textual[syntax]>=0.80
+Requires-Dist: tomli-w>=1.0
+Description-Content-Type: text/markdown
+
+# sqlide
+
+A DataGrip-style SQL IDE that runs in your terminal. Connect to any database over JDBC,
+write SQL in an editor that outlines the statement about to run, and browse results in
+sortable, copyable tables that export to CSV, XLSX and more.
+
+Works on Linux, macOS and WSL.
+
+## Features
+
+- **Any JDBC database.** PostgreSQL and ClickHouse work out of the box; MySQL, MariaDB,
+  Oracle, SQL Server, H2, SQLite and DuckDB are one keypress away. Add your own driver from
+  jar files or Maven coordinates, as in DataGrip. Drivers are downloaded from Maven Central
+  (checksum verified) and each one gets its own class loader.
+- **Framed statement.** The statement under the cursor is outlined in the gutter; `F5`
+  runs it, a selection runs the selection, `Shift+F5` runs the whole file. Dialect-aware
+  splitting: `$$` quotes, nested comments, Oracle `/`, SQL Server `GO`, procedural blocks.
+- **Result grid.** Sort by several columns, filter, select a rectangle, view long values,
+  load more rows on demand. Copy as TSV, CSV, Markdown, JSON or `INSERT` statements.
+- **Export.** CSV, TSV, JSON, JSON Lines, Markdown, SQL inserts, HTML, XLSX. Export the loaded
+  rows or re-run the query and stream the full result to disk, with progress and cancel.
+- **Schema tree and autocomplete.** Lazy metadata, `SELECT *` on Enter, alias-aware column
+  completion, keywords and functions per dialect.
+- **Consoles and files.** Tabs with their own connection; consoles autosave and come back
+  after a restart; open and save `.sql` files (`sqlide a.sql b.sql`).
+- **History, formatting, transactions.** Searchable query history, SQL formatting,
+  Auto/Manual commit with Commit/Rollback.
+- **Rebindable keys, themes, command palette** (`Ctrl+P`). No AI features.
+
+## Install
+
+Requirements: Python 3.12+ and a Java 11+ runtime (`brew install openjdk`,
+`apt install openjdk-21-jre`, ...). Check with `sqlide doctor`.
+
+```sh
+uv tool install sqlide        # or: pipx install sqlide
+sqlide
+```
+
+Homebrew formula: see [packaging/homebrew](packaging/homebrew/README.md).
+
+## Quick start
+
+```sh
+sqlide driver install postgres   # or just connect: sqlide offers to download it
+sqlide                           # Ctrl+N: new connection, Enter on it: connect
+```
+
+Passwords are never written to disk. sqlide asks when you connect and keeps the password
+in memory until you quit. A connection can instead read it from an environment variable
+(`password_ref = "${env:PGPASSWORD}"`) or from a command such as a keychain CLI
+(`password_cmd = "security find-generic-password -s mydb -w"`).
+
+## Keys
+
+`sqlide keys` prints every rebindable action with its default key. Override in
+`~/.config/sqlide/keymap.toml`:
+
+```toml
+[keys]
+"editor.run" = "f4"
+```
+
+| Action | Keys |
+|---|---|
+| Run statement / selection | `F5`, `Ctrl+J`, `Ctrl+Enter`\* |
+| Run all | `Shift+F5` |
+| Cancel query | `Ctrl+F2` |
+| Autocomplete | `Ctrl+Space` (opens by itself after a dot) |
+| Format / comment | `F7` or `Ctrl+Alt+L` / `Ctrl+/` or `Alt+/` |
+| New connection / console / close tab | `Ctrl+N` / `Ctrl+T` / `Alt+W` |
+| Open / save file | `Ctrl+O` / `Ctrl+S` |
+| History | `Alt+E` |
+| Switch tab | `Alt+←` `Alt+→` |
+| Focus connections / schema / editor / results | `Alt+C` / `Alt+D` / `Alt+Q` / `Alt+R` (or `F6` / `Shift+F6` to cycle) |
+| Tx: toggle / commit / rollback | `F8` / `F9` / `F10` |
+| Grid: sort / copy / copy as / filter / export | `s` / `Ctrl+C` / `y` / `/` / `e` |
+| Command palette | `Ctrl+P` |
+| Quit | `Ctrl+Q` |
+
+\* Most terminals send `Ctrl+Enter` as plain `Enter`; it only works where the terminal
+speaks the kitty keyboard protocol. `Alt+Enter` is not used on purpose: it toggles
+full screen in Windows Terminal.
+
+## Files
+
+| What | Where (Linux and WSL; macOS uses the platform equivalents) |
+|---|---|
+| Settings, connections, custom drivers, keymap | `~/.config/sqlide/` |
+| Downloaded drivers, history, consoles | `~/.local/share/sqlide/` |
+
+Override with `SQLIDE_CONFIG_DIR` and `SQLIDE_DATA_DIR`.
+
+## Notes
+
+- Schema reads (tree, autocomplete) use a second connection, so they work while a query runs.
+  For in-memory databases (H2 `mem:`, SQLite `:memory:`, DuckDB) a second connection would see
+  a different database, so the query connection is shared and reads wait for a running query.
+- Autocomplete reads cached metadata. DDL you run in the editor refreshes it; changes made by
+  other clients need `F5` in the schema tree. In manual-commit mode new objects appear after
+  Commit.
+- MySQL `DELIMITER x` lines are understood (they are not sent to the server). On SQL Server,
+  `CREATE PROCEDURE/FUNCTION/TRIGGER` without `BEGIN..END` runs up to the next `GO`, as T-SQL does.
+- `Alt+1`..`Alt+4` only work in terminals with the kitty keyboard protocol; most terminals
+  deliver them as Mac characters, so use the letter keys or `F6`.
+- Tested on Linux and WSL against PostgreSQL, MySQL, MariaDB, ClickHouse, SQL Server, Oracle and
+  H2. macOS is covered by CI. On Windows, run it inside WSL (native Windows is not supported).
+
+## Development
+
+```sh
+uv sync
+uv run pytest                 # unit, H2 integration, Textual pilot tests
+uv run pytest -m docker       # also PostgreSQL in Docker
+uv run ruff check && uv run pyright
+```
+
+The code is split into blocks that depend only downwards: `ui → db, sql, grid, export,
+history, config → jvm, drivers`. The core never imports the UI.
+
+## License
+
+MIT

sqlide-0.1.0/README.md

@@ -0,0 +1,123 @@
+# sqlide
+
+A DataGrip-style SQL IDE that runs in your terminal. Connect to any database over JDBC,
+write SQL in an editor that outlines the statement about to run, and browse results in
+sortable, copyable tables that export to CSV, XLSX and more.
+
+Works on Linux, macOS and WSL.
+
+## Features
+
+- **Any JDBC database.** PostgreSQL and ClickHouse work out of the box; MySQL, MariaDB,
+  Oracle, SQL Server, H2, SQLite and DuckDB are one keypress away. Add your own driver from
+  jar files or Maven coordinates, as in DataGrip. Drivers are downloaded from Maven Central
+  (checksum verified) and each one gets its own class loader.
+- **Framed statement.** The statement under the cursor is outlined in the gutter; `F5`
+  runs it, a selection runs the selection, `Shift+F5` runs the whole file. Dialect-aware
+  splitting: `$$` quotes, nested comments, Oracle `/`, SQL Server `GO`, procedural blocks.
+- **Result grid.** Sort by several columns, filter, select a rectangle, view long values,
+  load more rows on demand. Copy as TSV, CSV, Markdown, JSON or `INSERT` statements.
+- **Export.** CSV, TSV, JSON, JSON Lines, Markdown, SQL inserts, HTML, XLSX. Export the loaded
+  rows or re-run the query and stream the full result to disk, with progress and cancel.
+- **Schema tree and autocomplete.** Lazy metadata, `SELECT *` on Enter, alias-aware column
+  completion, keywords and functions per dialect.
+- **Consoles and files.** Tabs with their own connection; consoles autosave and come back
+  after a restart; open and save `.sql` files (`sqlide a.sql b.sql`).
+- **History, formatting, transactions.** Searchable query history, SQL formatting,
+  Auto/Manual commit with Commit/Rollback.
+- **Rebindable keys, themes, command palette** (`Ctrl+P`). No AI features.
+
+## Install
+
+Requirements: Python 3.12+ and a Java 11+ runtime (`brew install openjdk`,
+`apt install openjdk-21-jre`, ...). Check with `sqlide doctor`.
+
+```sh
+uv tool install sqlide        # or: pipx install sqlide
+sqlide
+```
+
+Homebrew formula: see [packaging/homebrew](packaging/homebrew/README.md).
+
+## Quick start
+
+```sh
+sqlide driver install postgres   # or just connect: sqlide offers to download it
+sqlide                           # Ctrl+N: new connection, Enter on it: connect
+```
+
+Passwords are never written to disk. sqlide asks when you connect and keeps the password
+in memory until you quit. A connection can instead read it from an environment variable
+(`password_ref = "${env:PGPASSWORD}"`) or from a command such as a keychain CLI
+(`password_cmd = "security find-generic-password -s mydb -w"`).
+
+## Keys
+
+`sqlide keys` prints every rebindable action with its default key. Override in
+`~/.config/sqlide/keymap.toml`:
+
+```toml
+[keys]
+"editor.run" = "f4"
+```
+
+| Action | Keys |
+|---|---|
+| Run statement / selection | `F5`, `Ctrl+J`, `Ctrl+Enter`\* |
+| Run all | `Shift+F5` |
+| Cancel query | `Ctrl+F2` |
+| Autocomplete | `Ctrl+Space` (opens by itself after a dot) |
+| Format / comment | `F7` or `Ctrl+Alt+L` / `Ctrl+/` or `Alt+/` |
+| New connection / console / close tab | `Ctrl+N` / `Ctrl+T` / `Alt+W` |
+| Open / save file | `Ctrl+O` / `Ctrl+S` |
+| History | `Alt+E` |
+| Switch tab | `Alt+←` `Alt+→` |
+| Focus connections / schema / editor / results | `Alt+C` / `Alt+D` / `Alt+Q` / `Alt+R` (or `F6` / `Shift+F6` to cycle) |
+| Tx: toggle / commit / rollback | `F8` / `F9` / `F10` |
+| Grid: sort / copy / copy as / filter / export | `s` / `Ctrl+C` / `y` / `/` / `e` |
+| Command palette | `Ctrl+P` |
+| Quit | `Ctrl+Q` |
+
+\* Most terminals send `Ctrl+Enter` as plain `Enter`; it only works where the terminal
+speaks the kitty keyboard protocol. `Alt+Enter` is not used on purpose: it toggles
+full screen in Windows Terminal.
+
+## Files
+
+| What | Where (Linux and WSL; macOS uses the platform equivalents) |
+|---|---|
+| Settings, connections, custom drivers, keymap | `~/.config/sqlide/` |
+| Downloaded drivers, history, consoles | `~/.local/share/sqlide/` |
+
+Override with `SQLIDE_CONFIG_DIR` and `SQLIDE_DATA_DIR`.
+
+## Notes
+
+- Schema reads (tree, autocomplete) use a second connection, so they work while a query runs.
+  For in-memory databases (H2 `mem:`, SQLite `:memory:`, DuckDB) a second connection would see
+  a different database, so the query connection is shared and reads wait for a running query.
+- Autocomplete reads cached metadata. DDL you run in the editor refreshes it; changes made by
+  other clients need `F5` in the schema tree. In manual-commit mode new objects appear after
+  Commit.
+- MySQL `DELIMITER x` lines are understood (they are not sent to the server). On SQL Server,
+  `CREATE PROCEDURE/FUNCTION/TRIGGER` without `BEGIN..END` runs up to the next `GO`, as T-SQL does.
+- `Alt+1`..`Alt+4` only work in terminals with the kitty keyboard protocol; most terminals
+  deliver them as Mac characters, so use the letter keys or `F6`.
+- Tested on Linux and WSL against PostgreSQL, MySQL, MariaDB, ClickHouse, SQL Server, Oracle and
+  H2. macOS is covered by CI. On Windows, run it inside WSL (native Windows is not supported).
+
+## Development
+
+```sh
+uv sync
+uv run pytest                 # unit, H2 integration, Textual pilot tests
+uv run pytest -m docker       # also PostgreSQL in Docker
+uv run ruff check && uv run pyright
+```
+
+The code is split into blocks that depend only downwards: `ui → db, sql, grid, export,
+history, config → jvm, drivers`. The core never imports the UI.
+
+## License
+
+MIT

sqlide-0.1.0/packaging/homebrew/README.md

@@ -0,0 +1,11 @@
+# Homebrew
+
+`sqlide.rb` is a template for a tap (`brew tap XFaIT/sqlide`).
+
+1. Release to PyPI (push a `v*` tag; `.github/workflows/release.yml` publishes).
+2. Create the repository `homebrew-sqlide` and put the formula in `Formula/sqlide.rb`.
+3. Set `url` and `sha256` from the PyPI sdist, then run
+   `brew update-python-resources sqlide` to add the dependency resources.
+4. `brew install --build-from-source XFaIT/sqlide/sqlide && brew test sqlide`.
+
+Users then run `brew install XFaIT/sqlide/sqlide`.

sqlide-0.1.0/packaging/homebrew/sqlide.rb

@@ -0,0 +1,36 @@
+# Homebrew formula template. Copy to your tap (homebrew-sqlide/Formula/sqlide.rb) after the
+# first PyPI release, then fill url/sha256 and the resource blocks:
+#
+#   brew update-python-resources sqlide
+#
+class Sqlide < Formula
+  include Language::Python::Virtualenv
+
+  desc "Terminal SQL IDE (DataGrip-like) over JDBC"
+  homepage "https://github.com/XFaIT/sqlide"
+  url "https://files.pythonhosted.org/packages/source/s/sqlide/sqlide-0.1.0.tar.gz"
+  sha256 "REPLACE_WITH_SDIST_SHA256"
+  license "MIT"
+
+  depends_on "openjdk"
+  depends_on "python@3.12"
+
+  # resource blocks (textual, jpype1, openpyxl, httpx, sqlglot, ...) are generated by
+  # `brew update-python-resources`
+
+  def install
+    virtualenv_install_with_resources
+    # keg-only openjdk is not on PATH: point sqlide at it
+    java_home = if OS.mac?
+      Formula["openjdk"].opt_libexec/"openjdk.jdk/Contents/Home"
+    else
+      Formula["openjdk"].opt_prefix
+    end
+    rm bin/"sqlide"
+    (bin/"sqlide").write_env_script libexec/"bin/sqlide", JAVA_HOME: java_home
+  end
+
+  test do
+    assert_match "sqlide", shell_output("#{bin}/sqlide --version")
+  end
+end

sqlide-0.1.0/pyproject.toml

@@ -0,0 +1,69 @@
+[project]
+name = "sqlide"
+version = "0.1.0"
+description = "Terminal SQL IDE (DataGrip-like) over JDBC"
+readme = "README.md"
+license = { text = "MIT" }
+authors = [{ name = "XFaIT" }]
+keywords = ["sql", "jdbc", "tui", "terminal", "database", "datagrip"]
+classifiers = [
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: POSIX :: Linux",
+    "Operating System :: MacOS",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Database :: Front-Ends",
+]
+requires-python = ">=3.12"
+dependencies = [
+    "textual[syntax]>=0.80",
+    "jpype1>=1.5",
+    "openpyxl>=3.1",
+    "platformdirs>=4",
+    "tomli-w>=1.0",
+    "httpx>=0.27",
+    "sqlglot>=25",
+]
+
+[project.urls]
+Homepage = "https://github.com/XFaIT/sqlide"
+Repository = "https://github.com/XFaIT/sqlide"
+Issues = "https://github.com/XFaIT/sqlide/issues"
+
+[project.scripts]
+sqlide = "sqlide.cli:main"
+
+[dependency-groups]
+dev = [
+    "pytest>=8",
+    "pytest-asyncio>=0.23",
+    "pytest-textual-snapshot>=1",
+    "ruff>=0.6",
+    "pyright>=1.1.380",
+    "textual-dev>=1.8.0",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/sqlide"]
+
+[tool.ruff]
+line-length = 100
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-m 'not docker'"
+asyncio_mode = "auto"
+markers = ["docker: needs Docker (postgres, clickhouse)"]
+
+[tool.pyright]
+include = ["src"]
+pythonVersion = "3.12"

sqlide-0.1.0/src/sqlide/__init__.py

@@ -0,0 +1,3 @@
+"""sqlide: terminal SQL IDE over JDBC."""
+
+__version__ = "0.1.0"

sqlide-0.1.0/src/sqlide/__main__.py

@@ -0,0 +1,5 @@
+import sys
+
+from sqlide.cli import main
+
+sys.exit(main())

sqlide-0.1.0/src/sqlide/app.py

@@ -0,0 +1,46 @@
+"""Textual application: only wires the workspace to the main screen."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from textual.app import App
+from textual.binding import Binding
+
+from sqlide.config.keymap import load_keymap
+from sqlide.config.settings import save_settings
+from sqlide.ui.commands import commands
+from sqlide.ui.screens.main import MainScreen
+from sqlide.workspace import Workspace
+
+
+class SqlideApp(App):
+    CSS_PATH = str(Path(__file__).parent / "ui" / "app.tcss")
+    BINDINGS = [Binding("ctrl+q", "quit", "Quit", priority=True, id="app.quit")]
+
+    def __init__(self, workspace: Workspace | None = None, files: list[Path] | None = None) -> None:
+        super().__init__()
+        self.workspace = workspace or Workspace()
+        self._files = files or []
+
+    def on_mount(self) -> None:
+        self.set_keymap(load_keymap())  # user overrides from keymap.toml
+        if self.workspace.settings.theme in self.available_themes:
+            self.theme = self.workspace.settings.theme
+        self.theme_changed_signal.subscribe(self, self._remember_theme)
+        self.main = MainScreen(self.workspace, self._files)
+        self.push_screen(self.main)
+
+    def _remember_theme(self, theme) -> None:
+        settings = self.workspace.settings
+        if theme.name != settings.theme:
+            settings.theme = theme.name
+            save_settings(settings)
+
+    def get_system_commands(self, screen):
+        yield from super().get_system_commands(screen)
+        yield from commands(self)
+
+    async def action_quit(self) -> None:
+        await self.main.tabs.shutdown()  # save consoles, cancel queries, close connections
+        self.exit()

sqlide-0.1.0/src/sqlide/cli.py

@@ -0,0 +1,64 @@
+"""Command line entry point. Thin: dispatch only, no logic."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+from sqlide import __version__
+from sqlide.drivers import cli as driver_cli
+
+
+def build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(prog="sqlide", description="Terminal SQL IDE over JDBC")
+    p.add_argument("--version", action="version", version=f"sqlide {__version__}")
+    sub = p.add_subparsers(dest="command")
+    d = sub.add_parser("doctor", help="check environment (JVM, drivers, config dirs)")
+    d.set_defaults(handler=lambda _: _doctor())
+    k = sub.add_parser("keys", help="list rebindable keys (override in keymap.toml)")
+    k.set_defaults(handler=lambda _: _keys())
+    driver_cli.register(sub)
+    return p
+
+
+def _doctor() -> int:
+    from sqlide import doctor
+
+    return doctor.run()
+
+
+def _keys() -> int:
+    from sqlide.config import paths
+    from sqlide.ui.keymap import catalogue
+
+    print(f'Override in {paths.keymap_file()}  ([keys] id = "key,key")\n')
+    infos = catalogue()
+    width = max(len(i.id) for i in infos)
+    for i in infos:
+        print(f"{i.id:<{width}}  {i.keys:<40}  {i.description}")
+    return 0
+
+
+COMMANDS = {"doctor", "driver", "keys"}
+
+
+def main(argv: list[str] | None = None) -> int:
+    argv = sys.argv[1:] if argv is None else argv
+    if argv and argv[0] not in COMMANDS and not argv[0].startswith("-"):
+        return _run_tui([Path(a) for a in argv])  # `sqlide query.sql other.sql`
+    args = build_parser().parse_args(argv)
+    if getattr(args, "handler", None):
+        return args.handler(args)
+    return _run_tui([])
+
+
+def _run_tui(files: list[Path]) -> int:
+    from sqlide.app import SqlideApp
+
+    SqlideApp(files=files).run()
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

sqlide-0.1.0/src/sqlide/clipboard.py

@@ -0,0 +1,65 @@
+"""System clipboard across macOS, Linux (X11/Wayland), WSL; OSC52 as the last resort."""
+
+from __future__ import annotations
+
+import os
+import shutil
+import subprocess
+from collections.abc import Callable
+from pathlib import Path
+
+Backend = tuple[str, list[str], Callable[[str], bytes]]
+
+
+def _utf8(s: str) -> bytes:
+    return s.encode("utf-8")
+
+
+def _utf16(s: str) -> bytes:  # clip.exe reads UTF-16LE when a BOM is present
+    return b"\xff\xfe" + s.encode("utf-16-le")
+
+
+def is_wsl() -> bool:
+    try:
+        return "microsoft" in Path("/proc/version").read_text().lower()
+    except OSError:
+        return False
+
+
+def backends(platform: str | None = None, wsl: bool | None = None) -> list[Backend]:
+    """Installed native clipboard tools in preference order."""
+    import sys
+
+    platform = platform or sys.platform
+    wsl = is_wsl() if wsl is None else wsl
+    candidates: list[Backend] = []
+    if platform == "darwin":
+        candidates.append(("pbcopy", ["pbcopy"], _utf8))
+    elif platform == "win32":
+        candidates.append(("clip", ["clip"], _utf16))
+    else:
+        if os.environ.get("WAYLAND_DISPLAY"):
+            candidates.append(("wl-copy", ["wl-copy"], _utf8))
+        if os.environ.get("DISPLAY"):
+            candidates.append(("xclip", ["xclip", "-selection", "clipboard", "-i"], _utf8))
+            candidates.append(("xsel", ["xsel", "--clipboard", "--input"], _utf8))
+        if wsl:
+            candidates.append(("clip.exe", ["clip.exe"], _utf16))
+    return [c for c in candidates if shutil.which(c[1][0])]
+
+
+def copy_native(text: str) -> str | None:
+    """Copy via the first working tool. Returns its name, or None if none worked."""
+    for name, cmd, encode in backends():
+        try:
+            subprocess.run(cmd, input=encode(text), check=True, timeout=5, capture_output=True)
+            return name
+        except (OSError, subprocess.SubprocessError):
+            continue
+    return None
+
+
+def available() -> str:
+    """Human-readable description for `sqlide doctor`."""
+    found = backends()
+    return found[0][0] if found else "none (falls back to OSC52 terminal escape)"

sqlide-0.1.0/src/sqlide/config/__init__.py

@@ -0,0 +1 @@
+"""Configuration block: paths, settings, saved connections, password resolution."""