sql-harness 0.1.0__py3-none-any.whl

sql_harness/cli.py

@@ -0,0 +1,869 @@
+"""sql-harness CLI — argparse subparsers + cmd_* dispatch.
+
+Subcommands:
+    list                     Show all configured connections.
+    add [--name N --driver D --url U ...]   Add a connection (interactive if missing flags).
+    edit <name>              Open connections.toml in $EDITOR.
+    remove <name>            Remove a connection.
+    show <name>              Print details (password masked).
+    test <name>              Open engine, SELECT 1, close; report latency.
+    workspace list           List open workspaces in this process (usually empty for CLI).
+    workspace use <name>     Print the masked connection details; signals intent.
+    workspace close <name>   Close + dispose an engine (no-op if not open).
+    workspace show <name>    Same as `show`.
+    skill list               List available agent-workspace skills.
+    skill show <name>        Print the skill markdown.
+    save <name>              Persist stdin (a heredoc) as agent-workspace/scripts/<name>.py.
+    run <name>               Execute a saved script (scripts/<name>.py) in the helpers namespace.
+    scripts                  List saved scripts.
+    init                     Write a starter connections.toml if none exists.
+    version                  Print sql-harness version + driver versions.
+    doctor                   Sanity-check config + try SELECT 1 on each connection.
+
+Mirrors `lab/subprocess/cli.py` style.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import shutil
+import subprocess
+import sys
+import time
+from importlib import resources as importlib_resources
+from pathlib import Path
+from typing import Callable
+
+from sqlalchemy import text
+
+from . import __version__
+from .config import (
+    ConnectionConfig,
+    PoolConfig,
+    load as load_config,
+    save as save_config,
+)
+from .manager import SqlHarness
+from .paths import (
+    config_file,
+    ensure_private_dir,
+    home_dir,
+    scripts_dir,
+    workspace_dir,
+    zone_dir,
+    zone_scripts_dir,
+    zone_skills_dir,
+)
+
+
+# --- Output helpers --------------------------------------------------------
+
+def _emit(data) -> None:
+    """Print structured data as JSON; plain text otherwise."""
+    if isinstance(data, (dict, list)):
+        print(json.dumps(data, indent=2, ensure_ascii=False, default=str))
+    else:
+        print(data)
+
+
+# --- Subcommand implementations --------------------------------------------
+
+def cmd_list(_args, harness: SqlHarness) -> int:
+    cfg = harness.config
+    if not cfg.connections:
+        _emit({"connections": [], "hint": "run `sql-harness init` to scaffold one"})
+        return 0
+    rows = []
+    for c in cfg.connections:
+        rows.append({
+            "name": c.name,
+            "driver": c.driver,
+            "url": c.masked_url(),
+            "description": c.description,
+            "pool_size": c.pool.size,
+        })
+    _emit({"default_workspace": cfg.default_workspace, "connections": rows})
+    return 0
+
+
+def cmd_add(args, harness: SqlHarness) -> int:
+    cfg = harness.config
+    # Pull from flags or prompt.
+    name = args.name or input("connection name: ").strip()
+    if not name:
+        print("error: name required", file=sys.stderr)
+        return 2
+    if any(c.name == name for c in cfg.connections):
+        print(f"error: connection {name!r} already exists", file=sys.stderr)
+        return 2
+
+    driver = args.driver or input("driver (postgres|mysql|redis|sqlite|ssh): ").strip()
+    if driver not in ("postgres", "mysql", "redis", "sqlite", "ssh", "ssh+password", "ssh+key"):
+        print(f"error: unknown driver {driver!r}", file=sys.stderr)
+        return 2
+
+    url = args.url or input("URL: ").strip()
+    if not url:
+        print("error: url required", file=sys.stderr)
+        return 2
+
+    description = args.description or ""
+    pool = PoolConfig(size=args.pool_size or cfg.pool_defaults.size)
+
+    cfg.connections.append(
+        ConnectionConfig(
+            name=name,
+            driver=driver,
+            url=url,
+            description=description,
+            pool=pool,
+        )
+    )
+    save_config(cfg, config_file())
+    _emit({"added": name, "driver": driver, "url": _mask(url)})
+    return 0
+
+
+def cmd_edit(args, _harness: SqlHarness) -> int:
+    path = config_file()
+    if not path.exists():
+        print(f"error: {path} does not exist; run `sql-harness init` first", file=sys.stderr)
+        return 2
+    editor = os.environ.get("EDITOR") or ("notepad" if sys.platform == "win32" else "vi")
+    if _harness_contains(_harness_name_filter(args.name), load_config(path)):
+        pass
+    return subprocess.call([editor, str(path)])
+
+
+def _harness_contains(name: str, cfg) -> bool:
+    return any(c.name == name for c in cfg.connections)
+
+
+def _harness_name_filter(_name: str | None) -> str:
+    return _name or ""
+
+
+def cmd_remove(args, harness: SqlHarness) -> int:
+    cfg = harness.config
+    before = len(cfg.connections)
+    cfg.connections = [c for c in cfg.connections if c.name != args.name]
+    if len(cfg.connections) == before:
+        print(f"error: no connection named {args.name!r}", file=sys.stderr)
+        return 2
+    if cfg.default_workspace == args.name:
+        cfg.default_workspace = ""
+    save_config(cfg, config_file())
+    _emit({"removed": args.name})
+    return 0
+
+
+def cmd_show(args, harness: SqlHarness) -> int:
+    try:
+        c = harness.config.get(args.name)
+    except KeyError:
+        print(f"error: no connection named {args.name!r}", file=sys.stderr)
+        return 2
+    _emit({
+        "name": c.name,
+        "driver": c.driver,
+        "url": c.masked_url(),
+        "description": c.description,
+        "pool": {
+            "size": c.pool.size,
+            "recycle": c.pool.recycle,
+            "pre_ping": c.pool.pre_ping,
+            "echo": c.pool.echo,
+        },
+        "application_name": c.application_name,
+    })
+    return 0
+
+
+def cmd_test(args, harness: SqlHarness) -> int:
+    name = args.name
+    try:
+        ws = harness.workspace(name)
+    except KeyError:
+        print(f"error: no connection named {name!r}", file=sys.stderr)
+        return 2
+    except Exception as e:
+        _emit({"name": name, "ok": False, "error": str(e)})
+        return 1
+
+    t0 = time.monotonic()
+    try:
+        with ws.engine.connect() as conn:
+            row = conn.execute(text("SELECT 1")).scalar()
+        dt = (time.monotonic() - t0) * 1000
+        _emit({"name": name, "ok": True, "select_1": row, "latency_ms": round(dt, 2)})
+        return 0
+    except Exception as e:
+        _emit({"name": name, "ok": False, "error": str(e)})
+        return 1
+
+
+def cmd_workspace(args, harness: SqlHarness) -> int:
+    sub = args.workspace_cmd
+    if sub == "list":
+        _emit({"open": harness.list_workspaces()})
+        return 0
+    if sub == "use":
+        try:
+            ws = harness.workspace(args.name)
+        except KeyError:
+            print(f"error: no connection named {args.name!r}", file=sys.stderr)
+            return 2
+        _emit({"name": ws.config.connection.name, "driver": ws.driver.name, "ok": True})
+        return 0
+    if sub == "close":
+        if not harness.has_workspace(args.name):
+            print(f"info: workspace {args.name!r} was not open", file=sys.stderr)
+            return 0
+        harness.close_workspace(args.name)
+        _emit({"closed": args.name})
+        return 0
+    if sub == "show":
+        return cmd_show(argparse.Namespace(name=args.name), harness)
+    print(f"unknown workspace subcommand: {sub}", file=sys.stderr)
+    return 2
+
+
+def _resolve_connection(args) -> str | None:
+    """Resolve the active DSN zone for a zone-scoped CLI command.
+
+    Order: explicit `--connection` flag > $BH_SQL_ACTIVE_CONNECTION env >
+    None (caller errors with guidance).
+    """
+    conn = getattr(args, "connection", None)
+    if conn:
+        return conn
+    return os.environ.get("BH_SQL_ACTIVE_CONNECTION")
+
+
+def _require_connection_or_fail(args) -> tuple[str | None, int]:
+    """Return (connection, exit_code). If exit_code is set, connection is None."""
+    conn = _resolve_connection(args)
+    if not conn:
+        print(
+            "error: no active connection. Pass --connection NAME, set "
+            "BH_SQL_ACTIVE_CONNECTION, or call use_workspace(name) first.",
+            file=sys.stderr,
+        )
+        return None, 2
+    return conn, 0
+
+
+def cmd_skill(args, _harness: SqlHarness) -> int:
+    sub = args.skill_cmd
+    # Bare `sql-harness skill` (no subcommand) emits the packaged SKILL.md
+    # to stdout — mirrors `browser-harness skill`. Used for agent registration:
+    #   sql-harness skill > ~/.codex/skills/sql-harness/SKILL.md
+    if sub is None:
+        body = _packaged_skill_body()
+        if body is None:
+            print(
+                "error: packaged SKILL.md not found (expected at "
+                "skills/sql-harness/SKILL.md relative to the package)",
+                file=sys.stderr,
+            )
+            return 2
+        # Force UTF-8 on stdout so non-ASCII skill bodies emit cleanly on Windows
+        # (default GBK/CP936 codepage can't encode symbols like ⇄).
+        out = sys.stdout
+        try:
+            out.reconfigure(encoding="utf-8", errors="replace")
+        except (AttributeError, OSError):
+            pass
+        out.write(body)
+        if not body.endswith("\n"):
+            out.write("\n")
+        return 0
+    # `skill list` / `skill show` are zone-scoped (per-DSN, like domain-skills).
+    conn, code = _require_connection_or_fail(args)
+    if code:
+        return code
+    if sub == "list":
+        d = zone_skills_dir(conn)
+        zone = d.glob("*.md") if d.is_dir() else []
+        # Also include global skills (shipped examples) as fallback.
+        global_d = workspace_dir() / "skills"
+        global_ = global_d.glob("*.md") if global_d.is_dir() else []
+        seen = set()
+        names = []
+        for p in sorted(zone) + sorted(global_):
+            if p.stem not in seen:
+                seen.add(p.stem)
+                names.append(p.stem)
+        _emit({"connection": conn, "skills": names})
+        return 0
+    if sub == "show":
+        zone_path = zone_skills_dir(conn) / f"{args.name}.md"
+        global_path = workspace_dir() / "skills" / f"{args.name}.md"
+        if zone_path.is_file():
+            print(zone_path.read_text(encoding="utf-8"))
+        elif global_path.is_file():
+            print(global_path.read_text(encoding="utf-8"))
+        else:
+            print(
+                f"error: no skill named {args.name!r} in zone {conn!r} or global",
+                file=sys.stderr,
+            )
+            return 2
+        return 0
+    print(f"unknown skill subcommand: {sub}", file=sys.stderr)
+    return 2
+
+
+def _package_root_dir() -> Path:
+    """The sql-harness container dir (lab/sql_harness/), 3 levels above cli.py.
+
+    cli.py lives at <root>/src/sql_harness/cli.py, so parents[2] = <root>.
+    Holds repo-level content (agent-workspace/, skills/, interaction-skills/)
+    that ships with the source checkout but is not inside the importable package.
+    """
+    return Path(__file__).resolve().parents[2]
+
+
+def _shipped_skills_dir() -> Path:
+    """Shipped preset skills: <root>/agent-workspace/skills/."""
+    return _package_root_dir() / "agent-workspace" / "skills"
+
+
+def _packaged_skill_body() -> str | None:
+    """Return the in-package SKILL.md body, or None if not found.
+
+    Mirrors browser-harness's run.py:_print_skill, which reads the packaged
+    SKILL.md via importlib.resources so it works from both a source checkout
+    and a built wheel. Falls back to the repo-level skills/sql-harness/SKILL.md.
+    """
+    # 1. in-package: src/sql_harness/SKILL.md (force-included in the wheel)
+    try:
+        ref = importlib_resources.files("sql_harness").joinpath("SKILL.md")
+        if ref.is_file():
+            return ref.read_text(encoding="utf-8")
+    except (ModuleNotFoundError, FileNotFoundError):
+        pass
+    # 2. repo-level fallback (source checkout)
+    repo = _package_root_dir() / "skills" / "sql-harness" / "SKILL.md"
+    if repo.is_file():
+        return repo.read_text(encoding="utf-8")
+    return None
+
+
+def _copy_shipped_skills(target_dir: Path) -> list[str]:
+    """Copy every shipped preset skill (.md) into target_dir if not present.
+
+    Returns the list of skill names (stems) now present in target_dir.
+    """
+    src = _shipped_skills_dir()
+    if not src.is_dir():
+        return []
+    present: list[str] = []
+    for f in sorted(src.glob("*.md")):
+        dst = target_dir / f.name
+        if not dst.exists():
+            shutil.copy2(str(f), str(dst))
+        present.append(f.stem)
+    return present
+
+
+def cmd_init(_args, _harness: SqlHarness) -> int:
+    """Scaffold a starter connections.toml if none exists.
+
+    Also copies shipped preset skills into the runtime workspace so they're
+    reachable via `apply_skill()` from any zone — mirrors browser-harness's
+    skill-registration pattern.
+    """
+    path = config_file()
+    ensure_private_dir(home_dir())
+    if not path.exists():
+        from .config import example_config
+
+        save_config(example_config(), path)
+        _emit({"path": str(path), "existed": False, "wrote": "example_config"})
+    else:
+        _emit({"path": str(path), "existed": True})
+
+    target_skills = workspace_dir() / "skills"
+    ensure_private_dir(target_skills)
+    copied = _copy_shipped_skills(target_skills)
+    if copied:
+        print(
+            f"installed {len(copied)} preset skills: {', '.join(copied)}",
+            file=sys.stderr,
+        )
+    return 0
+
+
+def cmd_version(_args, _harness: SqlHarness) -> int:
+    import importlib.metadata
+
+    info = {"sql-harness": __version__}
+    for pkg in ("psycopg", "pymysql", "sqlalchemy"):
+        try:
+            info[pkg] = importlib.metadata.version(pkg)
+        except importlib.metadata.PackageNotFoundError:
+            info[pkg] = "(not installed)"
+    _emit(info)
+    return 0
+
+
+def cmd_doctor(_args, harness: SqlHarness) -> int:
+    """Sanity-check: list connections + try SELECT 1 on each."""
+    rows = []
+    for c in harness.config.connections:
+        try:
+            ws = harness.workspace(c.name)
+            t0 = time.monotonic()
+            with ws.engine.connect() as conn:
+                conn.execute(text("SELECT 1")).scalar()
+            dt = (time.monotonic() - t0) * 1000
+            rows.append({"name": c.name, "ok": True, "latency_ms": round(dt, 2)})
+        except Exception as e:
+            rows.append({"name": c.name, "ok": False, "error": str(e)})
+    _emit({"results": rows})
+    return 0 if all(r["ok"] for r in rows) else 1
+
+
+def _validate_script_name(name: str) -> None:
+    """Reject path-traversal / weird names for saved scripts."""
+    if not name or "/" in name or "\\" in name or name.startswith("."):
+        raise ValueError(f"invalid script name: {name!r}")
+    if not name.replace("_", "").replace("-", "").isalnum():
+        raise ValueError(f"invalid script name: {name!r} (letters/digits/_/- only)")
+
+
+def cmd_save(args, _harness: SqlHarness) -> int:
+    """Persist stdin (a heredoc body) as zones/<connection>/scripts/<name>.py.
+
+    This is the essence of the harness: executed code is saved as reusable
+    Python, scoped to the DSN it was written for (mirrors browser-harness's
+    per-domain domain-skills). Next session, `sql-harness run <name>` (with
+    the same --connection) re-executes it.
+    """
+    try:
+        _validate_script_name(args.name)
+    except ValueError as e:
+        print(f"error: {e}", file=sys.stderr)
+        return 2
+    conn, code = _require_connection_or_fail(args)
+    if code:
+        return code
+    body = sys.stdin.read()
+    if not body.strip():
+        print("error: stdin is empty; nothing to save", file=sys.stderr)
+        return 2
+    target_dir = zone_scripts_dir(conn)
+    ensure_private_dir(target_dir)
+    target = target_dir / f"{args.name}.py"
+    existed = target.exists()
+    # Prepend a provenance header so the file is self-describing.
+    header = (
+        '"""Saved by `sql-harness save ' + args.name + '` (connection: ' + conn + ').\n'
+        "Re-run with: sql-harness run " + args.name + " --connection " + conn + "\n"
+        "Helpers (use_workspace, query, execute, ...) are pre-imported.\n"
+        '"""\n'
+    )
+    target.write_text(header + body, encoding="utf-8")
+    _emit({
+        "saved": args.name,
+        "connection": conn,
+        "path": str(target),
+        "existed": existed,
+        "bytes": len(body),
+    })
+    return 0
+
+
+def cmd_run(args, harness: SqlHarness) -> int:
+    """Execute a saved script (zones/<connection>/scripts/<name>.py).
+
+    The script runs with all helpers pre-imported, exactly like heredoc mode.
+    """
+    try:
+        _validate_script_name(args.name)
+    except ValueError as e:
+        print(f"error: {e}", file=sys.stderr)
+        return 2
+    conn, code = _require_connection_or_fail(args)
+    if code:
+        return code
+    path = zone_scripts_dir(conn) / f"{args.name}.py"
+    if not path.is_file():
+        print(
+            f"error: no saved script named {args.name!r} in zone {conn!r} "
+            f"({zone_scripts_dir(conn)})",
+            file=sys.stderr,
+        )
+        return 2
+    # Build the same exec namespace run.py uses for heredocs.
+    from . import helpers
+    from .helpers import set_active, use_workspace
+
+    set_active(harness)
+    # Activate the connection's zone so zone helpers + skills resolve.
+    use_workspace(conn)
+    namespace: dict = {}
+    for n, v in vars(helpers).items():
+        if not n.startswith("_"):
+            namespace[n] = v
+    code_text = path.read_text(encoding="utf-8")
+    try:
+        exec(compile(code_text, str(path), "exec"), namespace)
+        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
+
+
+def cmd_scripts(args, _harness: SqlHarness) -> int:
+    """List saved scripts in a connection's zone."""
+    conn, code = _require_connection_or_fail(args)
+    if code:
+        return code
+    d = zone_scripts_dir(conn)
+    names = sorted(p.stem for p in d.glob("*.py")) if d.is_dir() else []
+    _emit({"connection": conn, "scripts": names, "dir": str(d)})
+    return 0
+
+
+def _path_record(name: str, path: Path) -> dict:
+    """Build a {name, path, exists} record for the paths listing."""
+    return {"name": name, "path": str(path), "exists": path.exists()}
+
+
+def cmd_paths(args, harness: SqlHarness) -> int:
+    """Print every folder/file the CLI involves, so you can open them.
+
+    Global paths always shown; pass `-c CONN` to also show that DSN's zone
+    (scripts / skills / per-connection helpers). Mirrors the "where does my
+    stuff live" ergonomics browser-harness gives via its state-dir layout.
+    """
+    from . import paths as P
+    from importlib import resources as importlib_resources
+
+    pkg_src = Path(str(importlib_resources.files("sql_harness"))).resolve()
+    records: list[dict] = [
+        _path_record("home", P.home_dir()),
+        _path_record("config_dir", P.config_dir()),
+        _path_record("config_file", P.config_file()),
+        _path_record("agent_workspace", P.workspace_dir()),
+        _path_record("global_skills", P.workspace_dir() / "skills"),
+        _path_record("runtime_dir", P.runtime_dir()),
+        _path_record("tmp_dir", P.tmp_dir()),
+        _path_record("package_root", _package_root_dir()),
+        _path_record("package_source", pkg_src),
+    ]
+    out: dict = {
+        "global": records,
+        "env": {
+            "BH_SQL_HOME": os.environ.get("BH_SQL_HOME", ""),
+            "BH_SQL_CONFIG_FILE": os.environ.get("BH_SQL_CONFIG_FILE", ""),
+            "BH_SQL_AGENT_WORKSPACE": os.environ.get("BH_SQL_AGENT_WORKSPACE", ""),
+        },
+        "connections": harness.config.names(),
+        "default_workspace": harness.config.default_workspace,
+    }
+    conn = _resolve_connection(args)
+    if conn:
+        out["zone"] = {
+            "connection": conn,
+            "dirs": [
+                _path_record("zone_dir", P.zone_dir(conn)),
+                _path_record("zone_scripts", zone_scripts_dir(conn)),
+                _path_record("zone_skills", zone_skills_dir(conn)),
+                _path_record("zone_helpers", P.zone_helpers_file(conn)),
+            ],
+        }
+    _emit(out)
+    return 0
+
+
+_OPEN_TARGETS = ("home", "config", "workspace", "scripts", "skills", "runtime", "tmp", "package", "source", "zone")
+
+
+def _resolve_open_path(target: str, conn: str | None) -> Path:
+    """Map an open-target name to a concrete directory."""
+    from . import paths as P
+
+    table = {
+        "home": P.home_dir(),
+        "config": P.config_dir(),
+        "workspace": P.workspace_dir(),
+        "skills": P.workspace_dir() / "skills",
+        "runtime": P.runtime_dir(),
+        "tmp": P.tmp_dir(),
+        "package": _package_root_dir(),
+        "source": Path(str(importlib_resources.files("sql_harness"))).resolve(),
+    }
+    if target in table:
+        return table[target]
+    if target == "scripts":
+        if not conn:
+            raise ValueError("scripts is zone-scoped; pass --connection NAME")
+        return zone_scripts_dir(conn)
+    if target == "zone":
+        if not conn:
+            raise ValueError("zone is connection-scoped; pass --connection NAME")
+        return P.zone_dir(conn)
+    raise ValueError(f"unknown target {target!r}; one of: {', '.join(_OPEN_TARGETS)}")
+
+
+def _reveal(path: Path) -> None:
+    """Open `path` in the OS file manager (create it first if missing)."""
+    path.mkdir(parents=True, exist_ok=True)
+    if sys.platform == "win32":
+        os.startfile(str(path))  # type: ignore[attr-defined]
+    elif sys.platform == "darwin":
+        subprocess.Popen(["open", str(path)])
+    else:
+        subprocess.Popen(["xdg-open", str(path)])
+
+
+def cmd_open(args, _harness: SqlHarness) -> int:
+    """Open a folder in your OS file manager.
+
+    `sql-harness open workspace`          → agent-workspace
+    `sql-harness open scripts -c test_pg` → that zone's saved scripts
+    `sql-harness open config`             → connections.toml folder
+    """
+    from importlib import resources as importlib_resources  # noqa: F401
+
+    target = args.target or "workspace"
+    conn = _resolve_connection(args)
+    try:
+        path = _resolve_open_path(target, conn)
+    except ValueError as e:
+        print(f"error: {e}", file=sys.stderr)
+        return 2
+    _reveal(path)
+    _emit({"opened": target, "path": str(path), "connection": conn})
+    return 0
+
+
+# --- Helpers ---------------------------------------------------------------
+
+def _mask(url: str) -> str:
+    if "@" not in url:
+        return url
+    head, tail = url.split("@", 1)
+    if "://" not in head:
+        return url
+    scheme, creds = head.split("://", 1)
+    if ":" in creds:
+        user, _ = creds.split(":", 1)
+        return f"{scheme}://{user}:***@{tail}"
+    return url
+
+
+def _activate_ssh_zone(harness: SqlHarness, conn_name: str | None) -> None:
+    """Activate the SSH workspace (sets helpers._active_connection + opens workspace)."""
+    from . import helpers as _h
+    from .helpers import set_active, use_workspace
+
+    set_active(harness)
+    name = conn_name or harness.config.default_workspace
+    if not name:
+        raise RuntimeError(
+            "no SSH connection specified. Pass --connection NAME or set "
+            "default_workspace in connections.toml."
+        )
+    if name not in harness.config.names():
+        raise RuntimeError(f"no connection named {name!r}")
+    use_workspace(name)
+
+
+def cmd_ssh(args, harness: SqlHarness) -> int:
+    """Dispatch `sql-harness ssh {exec,upload,download,run-script,info}`."""
+    from . import helpers as _h
+
+    sub = getattr(args, "ssh_cmd", None)
+    if sub is None:
+        print("error: `ssh` needs a subcommand: exec / upload / download / run-script / info",
+              file=sys.stderr)
+        return 2
+
+    conn, code = _require_connection_or_fail(args)
+    if code:
+        return code
+    try:
+        _activate_ssh_zone(harness, conn)
+    except Exception as e:
+        print(f"error: {e}", file=sys.stderr)
+        return 2
+
+    if sub == "exec":
+        result = _h.ssh_exec(args.command, timeout=args.timeout)
+        sys.stdout.write(result["stdout"])
+        if result["stderr"]:
+            sys.stderr.write(result["stderr"])
+        return 0 if result["ok"] else result["exit_code"]
+
+    if sub == "upload":
+        _h.ssh_upload(args.local, args.remote)
+        _emit({"uploaded": args.local, "to": args.remote})
+        return 0
+
+    if sub == "download":
+        _h.ssh_download(args.remote, args.local)
+        _emit({"downloaded": args.remote, "to": args.local})
+        return 0
+
+    if sub == "run-script":
+        result = _h.ssh_run_script(args.local, args.remote_dir, args.interpreter)
+        sys.stdout.write(result["stdout"])
+        if result["stderr"]:
+            sys.stderr.write(result["stderr"])
+        return 0 if result["ok"] else result["exit_code"]
+
+    if sub == "info":
+        _emit(_h.ssh_info())
+        return 0
+
+    print(f"error: unknown ssh subcommand: {sub}", file=sys.stderr)
+    return 2
+
+
+# --- Parser & dispatch -----------------------------------------------------
+
+def _build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(
+        prog="sql-harness",
+        description="Single-process SQL CLI for LLM agents (postgres, mysql, redis-soon).",
+    )
+    sub = p.add_subparsers(dest="cmd")
+
+    sub.add_parser("list", help="show all configured connections")
+
+    p_add = sub.add_parser("add", help="add a connection")
+    p_add.add_argument("--name")
+    p_add.add_argument("--driver", choices=["postgres", "mysql", "redis", "sqlite", "ssh"])
+    p_add.add_argument("--url")
+    p_add.add_argument("--description")
+    p_add.add_argument("--pool-size", type=int)
+
+    p_edit = sub.add_parser("edit", help="edit connections.toml in $EDITOR")
+    p_edit.add_argument("name", nargs="?")
+
+    p_remove = sub.add_parser("remove", help="remove a connection")
+    p_remove.add_argument("name")
+
+    p_show = sub.add_parser("show", help="show connection details (password masked)")
+    p_show.add_argument("name")
+
+    p_test = sub.add_parser("test", help="connect + SELECT 1")
+    p_test.add_argument("name")
+
+    p_ws = sub.add_parser("workspace", help="manage workspaces")
+    ws_sub = p_ws.add_subparsers(dest="workspace_cmd")
+    ws_sub.add_parser("list", help="list open workspaces")
+    p_ws_use = ws_sub.add_parser("use", help="open a workspace")
+    p_ws_use.add_argument("name")
+    p_ws_close = ws_sub.add_parser("close", help="close a workspace")
+    p_ws_close.add_argument("name")
+    ws_sub.add_parser("show", help="alias for `show`")
+
+    p_skill = sub.add_parser(
+        "skill",
+        help="emit packaged SKILL.md (bare) or manage per-DSN zone skills",
+    )
+    p_skill.add_argument("-c", "--connection", help="DSN zone (for list/show)")
+    skill_sub = p_skill.add_subparsers(dest="skill_cmd")
+    skill_sub.add_parser("list", help="list skills in the zone")
+    p_skill_show = skill_sub.add_parser("show", help="show a skill in the zone")
+    p_skill_show.add_argument("name")
+
+    p_save = sub.add_parser("save", help="persist stdin as zones/<conn>/scripts/<name>.py")
+    p_save.add_argument("name")
+    p_save.add_argument("-c", "--connection", help="DSN zone to save into")
+
+    p_run = sub.add_parser("run", help="execute a saved script in the helpers namespace")
+    p_run.add_argument("name")
+    p_run.add_argument("-c", "--connection", help="DSN zone to run from")
+
+    p_scripts = sub.add_parser("scripts", help="list saved scripts in a zone")
+    p_scripts.add_argument("-c", "--connection", help="DSN zone to list")
+
+    p_paths = sub.add_parser("paths", help="show every folder/file the CLI involves")
+    p_paths.add_argument("-c", "--connection", help="also show this DSN's zone dirs")
+
+    p_open = sub.add_parser("open", help="open a folder in your file manager")
+    p_open.add_argument(
+        "target", nargs="?", default="workspace", choices=_OPEN_TARGETS,
+        help="which folder (default: workspace)",
+    )
+    p_open.add_argument("-c", "--connection", help="DSN zone (for scripts/zone targets)")
+
+    sub.add_parser("init", help="write a starter connections.toml")
+    sub.add_parser("version", help="print versions")
+    sub.add_parser("doctor", help="test every configured connection")
+
+    # --- ssh subcommand group -----------------------------------------------
+    p_ssh = sub.add_parser("ssh", help="run shell commands / file ops on an SSH workspace")
+    p_ssh.add_argument("-c", "--connection", help="which SSH connection to use")
+    ssh_sub = p_ssh.add_subparsers(dest="ssh_cmd")
+
+    p_ssh_exec = ssh_sub.add_parser("exec", help="run a shell command and print stdout/stderr")
+    p_ssh_exec.add_argument("command", help="shell command (quoted)")
+    p_ssh_exec.add_argument("--timeout", type=float, default=30.0, help="seconds")
+
+    p_ssh_up = ssh_sub.add_parser("upload", help="upload a local file to the remote")
+    p_ssh_up.add_argument("local", help="local file path")
+    p_ssh_up.add_argument("remote", help="remote file path")
+
+    p_ssh_dl = ssh_sub.add_parser("download", help="download a remote file to local")
+    p_ssh_dl.add_argument("remote", help="remote file path")
+    p_ssh_dl.add_argument("local", help="local file path")
+
+    p_ssh_rs = ssh_sub.add_parser(
+        "run-script",
+        help="upload a local script to a remote dir and execute it",
+    )
+    p_ssh_rs.add_argument("local", help="local script path")
+    p_ssh_rs.add_argument("--remote-dir", default="/tmp", help="where to upload (default /tmp)")
+    p_ssh_rs.add_argument("--interpreter", default="bash", help="interpreter to invoke (default bash)")
+
+    p_ssh_info = ssh_sub.add_parser("info", help="show active SSH connection info")
+    return p
+
+
+def main(argv: list[str]) -> int:
+    parser = _build_parser()
+    args = parser.parse_args(argv)
+    if not args.cmd:
+        parser.print_help()
+        return 0
+
+    cfg = load_config(config_file())
+    harness = SqlHarness(cfg)
+
+    commands: dict[str, Callable[[argparse.Namespace, SqlHarness], int]] = {
+        "list": cmd_list,
+        "add": cmd_add,
+        "edit": cmd_edit,
+        "remove": cmd_remove,
+        "show": cmd_show,
+        "test": cmd_test,
+        "workspace": cmd_workspace,
+        "skill": cmd_skill,
+        "save": cmd_save,
+        "run": cmd_run,
+        "scripts": cmd_scripts,
+        "paths": cmd_paths,
+        "open": cmd_open,
+        "ssh": cmd_ssh,
+        "init": cmd_init,
+        "version": cmd_version,
+        "doctor": cmd_doctor,
+    }
+    handler = commands[args.cmd]
+    try:
+        return handler(args, harness)
+    finally:
+        harness.close_all()