sql-harness 0.1.0__py3-none-any.whl

sql_harness/manager.py

@@ -0,0 +1,122 @@
+"""SqlHarness — single-process manager holding open workspaces.
+
+A workspace = a named connection + its SQLAlchemy Engine. Engines are opened
+lazily and kept alive until `close_workspace()` or process exit.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from sqlalchemy import Engine
+
+from .config import ConnectionsConfig
+from .drivers import Driver, get_driver
+from .paths import workspace_dir
+
+
+class Workspace:
+    """One connection = one workspace."""
+
+    def __init__(self, config: "WorkspaceConfig", engine: Engine, driver):
+        self.config = config
+        self.engine = engine
+        self.driver = driver
+
+    def __repr__(self) -> str:
+        return f"Workspace(name={self.config.connection.name!r}, driver={self.driver.name})"
+
+
+class WorkspaceConfig:
+    """Lightweight wrapper used at runtime; created from ConnectionConfig."""
+
+    __slots__ = ("connection",)
+
+    def __init__(self, connection):
+        self.connection = connection
+
+
+class SqlHarness:
+    """Owns the open workspace registry."""
+
+    def __init__(self, config: ConnectionsConfig):
+        self.config = config
+        self._workspaces: dict[str, Workspace] = {}
+
+    # --- workspace lifecycle -----------------------------------------------
+
+    def workspace(self, name: str) -> Workspace:
+        """Open (or return cached) workspace for `name`."""
+        if name in self._workspaces:
+            return self._workspaces[name]
+        conn = self.config.get(name)
+        driver = get_driver(conn.driver)
+        engine = driver.make_engine(conn.url, conn.pool)
+        ws = Workspace(WorkspaceConfig(conn), engine, driver)
+        self._workspaces[name] = ws
+        return ws
+
+    def close_workspace(self, name: str) -> None:
+        ws = self._workspaces.pop(name, None)
+        if ws is not None:
+            # SQLAlchemy engines use .dispose(); SSH handles use .close().
+            closer = getattr(ws.engine, "close", None)
+            if callable(closer):
+                closer()
+            else:
+                ws.engine.dispose()
+
+    def list_workspaces(self) -> list[str]:
+        return sorted(self._workspaces.keys())
+
+    def has_workspace(self, name: str) -> bool:
+        return name in self._workspaces
+
+    def get_workspace(self, name: str) -> Workspace | None:
+        return self._workspaces.get(name)
+
+    # --- default workspace (from connections.toml) -----------------------
+
+    @property
+    def default_workspace_name(self) -> str:
+        return self.config.default_workspace
+
+    def default_workspace(self) -> Workspace | None:
+        name = self.config.default_workspace
+        if not name:
+            return None
+        if name not in self.config.names():
+            return None
+        return self.workspace(name)
+
+    # --- skills ------------------------------------------------------------
+
+    def apply_skill(self, name: str) -> str:
+        """Read an agent-workspace skill markdown file."""
+        path = self._skill_path(name)
+        if not path.is_file():
+            raise FileNotFoundError(
+                f"no skill named {name!r} in {self._skills_dir()}"
+            )
+        return path.read_text(encoding="utf-8")
+
+    def list_skills(self) -> list[str]:
+        d = self._skills_dir()
+        if not d.is_dir():
+            return []
+        return sorted(p.stem for p in d.glob("*.md") if p.is_file())
+
+    def _skill_path(self, name: str) -> Path:
+        # Defensive: prevent path traversal.
+        if "/" in name or "\\" in name or name.startswith("."):
+            raise ValueError(f"invalid skill name: {name!r}")
+        return self._skills_dir() / f"{name}.md"
+
+    def _skills_dir(self) -> Path:
+        return workspace_dir() / "skills"
+
+    # --- teardown ----------------------------------------------------------
+
+    def close_all(self) -> None:
+        for name in list(self._workspaces.keys()):
+            self.close_workspace(name)

sql_harness/paths.py

@@ -0,0 +1,112 @@
+"""Path resolution for sql-harness state directory."""
+
+from __future__ import annotations
+
+import os
+import sys
+from pathlib import Path
+
+IS_WINDOWS = sys.platform == "win32"
+
+
+def home_dir() -> Path:
+    """Return the sql-harness state root.
+
+    Resolved in order:
+      1. $BH_SQL_HOME (matches browser-harness env-var style)
+      2. $XDG_CONFIG_HOME/sql-harness
+      3. ~/.config/sql-harness (POSIX / fallback)
+    """
+    override = os.environ.get("BH_SQL_HOME")
+    if override:
+        return Path(override).expanduser()
+    xdg = os.environ.get("XDG_CONFIG_HOME")
+    if xdg:
+        return Path(xdg).expanduser() / "sql-harness"
+    return Path.home() / ".config" / "sql-harness"
+
+
+def config_dir() -> Path:
+    """Directory holding connections.toml and other static config."""
+    override = os.environ.get("BH_SQL_CONFIG_DIR")
+    return Path(override).expanduser() if override else home_dir()
+
+
+def config_file() -> Path:
+    """Path to the plaintext connections.toml."""
+    override = os.environ.get("BH_SQL_CONFIG_FILE")
+    return Path(override).expanduser() if override else config_dir() / "connections.toml"
+
+
+def workspace_dir() -> Path:
+    """Agent-editable workspace (mirrors browser-harness agent-workspace/).
+
+    Layout:
+      - agent_helpers.py        shared base helpers (auto-imported every run)
+      - zones/<connection>/     per-DSN isolated zone (mirrors domain-skills/<host>/)
+          - helpers.py          per-connection helpers (merged over the shared base)
+          - scripts/<name>.py   saved heredocs for this connection
+          - skills/<name>.md    per-connection skill knowledge
+      - scripts/                (legacy global scripts, pre-zone)
+      - skills/                 (legacy global skills, pre-zone)
+    """
+    override = os.environ.get("BH_SQL_AGENT_WORKSPACE")
+    return Path(override).expanduser() if override else home_dir() / "agent-workspace"
+
+
+def scripts_dir() -> Path:
+    """Legacy global scripts dir (pre-zone). Prefer zone_scripts_dir()."""
+    return workspace_dir() / "scripts"
+
+
+def zone_dir(connection: str) -> Path:
+    """Per-connection isolated zone root: agent-workspace/zones/<connection>/.
+
+    Mirrors browser-harness's domain-skills/<host>/ — one isolated area per
+    DSN. `connection` is validated to be a simple identifier (no path parts).
+    """
+    _validate_zone_name(connection)
+    return workspace_dir() / "zones" / connection
+
+
+def zone_scripts_dir(connection: str) -> Path:
+    return zone_dir(connection) / "scripts"
+
+
+def zone_skills_dir(connection: str) -> Path:
+    return zone_dir(connection) / "skills"
+
+
+def zone_helpers_file(connection: str) -> Path:
+    """Per-connection helpers.py, merged over the shared base on use_workspace."""
+    return zone_dir(connection) / "helpers.py"
+
+
+def _validate_zone_name(name: str) -> None:
+    """A zone name is a connection name; reject path traversal / odd chars."""
+    if not name or "/" in name or "\\" in name or name.startswith("."):
+        raise ValueError(f"invalid zone/connection name: {name!r}")
+
+
+def runtime_dir() -> Path:
+    """Runtime state: logs, lock files."""
+    override = os.environ.get("BH_SQL_RUNTIME_DIR")
+    return Path(override).expanduser() if override else home_dir() / "runtime"
+
+
+def tmp_dir() -> Path:
+    """Per-session scratch files (query logs, dumps)."""
+    override = os.environ.get("BH_SQL_TMP_DIR")
+    return Path(override).expanduser() if override else home_dir() / "tmp"
+
+
+def ensure_private_dir(p: Path) -> Path:
+    """Create directory (parents=True) and tighten perms on POSIX."""
+    p.mkdir(parents=True, exist_ok=True)
+    if not IS_WINDOWS:
+        # Best-effort: only tighten on creation
+        try:
+            p.chmod(0o700)
+        except (PermissionError, OSError):
+            pass
+    return p

sql_harness/run.py

@@ -0,0 +1,85 @@
+"""sql-harness CLI / heredoc entry point.
+
+Mirrors browser-harness's run.py:
+
+- Without args + non-TTY stdin: read heredoc body, exec in helpers' globals.
+- Otherwise: dispatch to cli.main().
+
+The console script `sql-harness` resolves to this module's `main()`.
+"""
+
+from __future__ import annotations
+
+import sys
+
+from . import cli, helpers
+from .agent_loader import load_agent_helpers
+from .config import load as load_config
+from .helpers import set_active
+from .manager import SqlHarness
+from .paths import config_file, ensure_private_dir, home_dir
+
+
+# Merge every helper into this module's globals so `exec(code, globals())`
+# in heredoc mode sees them as bare names. Mirrors browser-harness's
+# `from .helpers import *` pattern.
+for _name, _value in vars(helpers).items():
+    if _name.startswith("_"):
+        continue
+    globals()[_name] = _value
+
+# Mirror the same names for `from .run import *` users.
+__all__ = [n for n in globals().keys() if not n.startswith("_")]
+
+
+def _build_harness() -> SqlHarness:
+    """Build a SqlHarness from the user's config file."""
+    cfg_path = config_file()
+    if not cfg_path.exists():
+        # First run: create a fresh state dir + empty config file.
+        ensure_private_dir(home_dir())
+        cfg = load_config(cfg_path)
+    else:
+        cfg = load_config(cfg_path)
+    return SqlHarness(cfg)
+
+
+def main() -> int:
+    """Entry point: branch on TTY vs heredoc."""
+    harness = _build_harness()
+    set_active(harness)
+
+    # Merge agent_helpers.py into our globals so user-defined helpers
+    # are also visible in heredoc mode.
+    load_agent_helpers(globals())
+
+    # Heredoc mode: no args + piped stdin.
+    if len(sys.argv) == 1 and not sys.stdin.isatty():
+        # Read stdin as UTF-8 on Windows (default locale is GBK/CP936, which
+        # mangles non-ASCII bytes into surrogates that exec() rejects).
+        # Mirrors browser-harness's Windows stdin handling.
+        try:
+            sys.stdin.reconfigure(encoding="utf-8", errors="replace")
+        except (AttributeError, OSError):
+            pass
+        code = sys.stdin.read()
+        try:
+            exec(code, globals())
+            return 0
+        except SystemExit as e:
+            return int(e.code) if e.code is not None else 0
+        except Exception:
+            import traceback
+
+            traceback.print_exc()
+            return 1
+
+    # Otherwise: dispatch to the CLI.
+    try:
+        return cli.main(sys.argv[1:])
+    finally:
+        harness.close_all()
+
+
+if __name__ == "__main__":
+    sys.exit(main())

sql_harness-0.1.0.dist-info/METADATA

@@ -0,0 +1,137 @@
+Metadata-Version: 2.4
+Name: sql-harness
+Version: 0.1.0
+Summary: Single-process SQL + SSH CLI for LLM agents. PostgreSQL/MySQL/SSH via SQLAlchemy + paramiko. Plaintext credentials in one TOML file. Helpers auto-injected into the heredoc namespace.
+Project-URL: Source, https://github.com/zhaoliuxue/much_bigpy/tree/master/lab/sql_harness
+Project-URL: Issues, https://github.com/zhaoliuxue/much_bigpy/issues
+Author: much-bigpy
+License: MIT
+Keywords: agent,cli,database,heredoc,mysql,postgres,sql,ssh
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Database
+Classifier: Topic :: System :: Shells
+Requires-Python: >=3.12
+Requires-Dist: paramiko<4,>=3.4
+Requires-Dist: psycopg[binary]<4,>=3.2
+Requires-Dist: pymysql<2,>=1.1
+Requires-Dist: sqlalchemy<3,>=2.0
+Description-Content-Type: text/markdown
+
+# sql-harness
+
+A thin, single-process SQL CLI for LLM agents. Mirrors [browser-harness](https://github.com/browser-use/browser-harness)'s structure but targets relational databases (Postgres, MySQL, Redis-soon).
+
+## Quickstart
+
+```bash
+# 1. Install deps (one-time)
+uv sync
+
+# 2. Scaffold a starter connections.toml
+uv run sql-harness init
+
+# 3. Add a connection
+uv run sql-harness add local_pg --driver postgres --url 'postgresql://postgres:postgres@localhost:5432/postgres'
+
+# 4. Test it
+uv run sql-harness test local_pg
+
+# 5. Use it
+uv run sql-harness <<'PY'
+use_workspace("local_pg")
+print(query("SELECT version()"))
+print(list_tables())
+print(describe("pg_class"))
+PY
+```
+
+## Architecture (~1k lines across 8 core files)
+
+- `install.md` — first-time install + first connection
+- `SKILL.md` — day-to-day usage
+- `lab/sql_harness/src/sql_harness/` — protected core package (src-layout, mirrors browser-harness)
+- `${XDG_CONFIG_HOME:-~/.config}/sql-harness/connections.toml` — plaintext credentials in ONE place
+- `${XDG_CONFIG_HOME:-~/.config}/sql-harness/agent-workspace/agent_helpers.py` — task-specific helpers
+- `${XDG_CONFIG_HOME:-~/.config}/sql-harness/agent-workspace/skills/` — per-task/per-table skills
+
+## Why mirror browser-harness?
+
+- Same operational ergonomics for agents: heredoc CLI with auto-imported helpers.
+- Same agent-workspace pattern (helpers + skills stay editable per-project).
+- Same path/state layout (XDG-style state directory).
+- Same doc layering: `SKILL.md` body + `interaction-skills/*.md` for stuck points.
+
+## What this is NOT
+
+- Not a database migration framework.
+- Not an ORM.
+- Not a connection-string parser (`pgcli`/`mycli` already exist for interactive REPL use; this is for *agents*).
+- Not a long-running daemon. SQL connections don't need one.
+
+## Connection file format
+
+Default: `${XDG_CONFIG_HOME:-~/.config}/sql-harness/connections.toml`.
+
+```toml
+default_workspace = "local_pg"
+
+[pool_defaults]
+size = 5
+recycle = 3600
+pre_ping = true
+echo = false
+
+[[connections]]
+name = "local_pg"
+driver = "postgres"
+url = "postgresql+psycopg://postgres:postgres@localhost:5432/postgres"
+description = "Local PostgreSQL for dev"
+
+[[connections]]
+name = "prod_pg"
+driver = "postgres"
+url = "${env:PROD_PG_URL}"            # env-var indirection
+pool_size = 10
+```
+
+Use `${env:VAR}` placeholders inside `url` for prod secrets — they're expanded at load time from the process environment.
+
+## Configuration env vars
+
+| Var | Purpose |
+|---|---|
+| `BH_SQL_HOME` | Override state root (`~/.config/sql-harness` by default) |
+| `BH_SQL_CONFIG_FILE` | Override connections.toml path |
+| `BH_SQL_AGENT_WORKSPACE` | Override agent-workspace directory |
+| `BH_SQL_RUNTIME_DIR` | Override runtime state dir |
+| `BH_SQL_TMP_DIR` | Override temp dir |
+| `BH_PG_URL` | Used by integration tests (skipped if unset) |
+| `BH_MYSQL_URL` | Used by integration tests (skipped if unset) |
+
+## Drivers
+
+| Driver | Backend | Package | Status |
+|---|---|---|---|
+| `postgres` | PostgreSQL | `psycopg[binary]>=3.2` | ✅ |
+| `mysql` | MySQL | `pymysql>=1.1` | ✅ |
+| `redis` | Redis | `redis>=5.0` (not yet added) | 🚧 stub |
+| `sqlite` | SQLite | stdlib (`sqlite3`) | ✅ (test-only) |
+| `ssh` / `ssh+password` / `ssh+key` | remote shell + SFTP (paramiko) | `paramiko>=3.4` | ✅ |
+
+To enable Redis: `uv add "redis>=5.0,<6"` then implement `drivers/redis.py`.
+To add another SSH host: append a `[[connections]]` block with `driver = "ssh"` and an `ssh://...` URL.
+
+## Contributing
+
+PRs and improvements welcome. See `AGENTS.md` for code priorities.
+
+- **Skills are written by the harness, not by you.** When you figure out a non-obvious SQL flow (a weird schema, a slow query, a JSON column trick), file a skill in `agent-workspace/skills/<name>.md`. Future sessions will read it before re-discovering it.
+- Bug fixes, new drivers, helper additions all welcome.
+
+## License
+
+MIT.

sql_harness-0.1.0.dist-info/RECORD

@@ -0,0 +1,19 @@
+sql_harness/SKILL.md,sha256=O7xnojcL_Q_c8Hnf1TXwUEvbCpEkbD52rfwFDDxA_gM,3258
+sql_harness/__init__.py,sha256=nT5ZKMOTeza9K1inWRHsR3h8ikvK1icekBbkOfX4U_U,669
+sql_harness/agent_loader.py,sha256=CO0MahpXR1jzwQWSrrPGGo_AJ40ogunASP5gZFmjsu0,1821
+sql_harness/cli.py,sha256=OBoB0icCi8dUrqo8RI4aE9bvxwxzwg7euGJWvEbNJSs,30859
+sql_harness/config.py,sha256=CcOTASoyoqhRlTN-a8zY6D1QiK-XJlJ1dv6INWDiwfI,8141
+sql_harness/helpers.py,sha256=bv3rUWeVBcIDdtrn6ZLcubKvkU9MtJjQtuboACkxrNQ,29484
+sql_harness/manager.py,sha256=56iTMTUcqfi_Cktv8qbIU_7W70OP-6T5u_U66RntUaY,3929
+sql_harness/paths.py,sha256=V05o-OPKkxU8kERgrWY3RuIre6xP-AM8CT3EPbY-3Ag,3798
+sql_harness/run.py,sha256=xoAsPEXT-5l0eZwVXMlufCRxl1woD0sZSgBZgzWlzIc,2545
+sql_harness/drivers/__init__.py,sha256=WdxI10lF_gkhFib6CPe2KA6to4jxr_Rmio3-jFsrW3g,1686
+sql_harness/drivers/mysql.py,sha256=W2GH20JZE6mnPGwEIF5zykp31WaNoKx96c4e92LD5kM,1497
+sql_harness/drivers/postgres.py,sha256=dEMBOTFprjYWYY2OreMzi0P8nosk6cFfuSKQhOqT2iY,2190
+sql_harness/drivers/redis.py,sha256=Oywm-sVBFnrXEybMFxkFy4jKL9S2k3kITgGeI1T_RX8,1093
+sql_harness/drivers/sqlite.py,sha256=AzlnccquIJ7XfyLBB6jTFtFMpij_rbHR4e_rr7oxhX8,1358
+sql_harness/drivers/ssh.py,sha256=S5-lEJGihDvqu3BTqUGg6rUoDPOw0h23krtCgBMUlGE,10076
+sql_harness-0.1.0.dist-info/METADATA,sha256=b3tN1nb6tTqNcQzO2macw8HTSztXht02mdTsPNQa3Qg,4895
+sql_harness-0.1.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+sql_harness-0.1.0.dist-info/entry_points.txt,sha256=mY6NkQIlefGk1xDAIHcFdPc5jTY-Vi_iUuCBY_2NVTk,53
+sql_harness-0.1.0.dist-info/RECORD,,

sql_harness-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.31.0
+Root-Is-Purelib: true
+Tag: py3-none-any

sql_harness-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+sql-harness = sql_harness.run:main