sql-harness 0.3.1__tar.gz → 0.3.3__tar.gz

sql_harness-0.3.3/AGENTS.md

@@ -0,0 +1,19 @@
+# AGENTS.md — pointer
+
+> All contributor documentation lives in `docs/AGENTS.md` (single docs directory).
+> This pointer file exists only because agent frameworks auto-load `AGENTS.md`
+> by filename at the repo root — read the real content at `docs/AGENTS.md`.
+
+# Code priorities
+
+- Clarity
+- Precision
+- Low verbosity
+- Versatility
+
+# One-line summary
+
+sql-harness is a single-process SQL + SSH CLI for agents: plaintext
+connections in one TOML file, heredoc mode with auto-injected helpers.
+Core code in `src/sql_harness/`, agent-editable workspace under
+`agent-workspace/`. Full module list + contributing rules: `docs/AGENTS.md`.

{sql_harness-0.3.1 → sql_harness-0.3.3}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: sql-harness
-Version: 0.3.1
+Version: 0.3.3
 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
@@ -25,7 +25,7 @@ Description-Content-Type: text/markdown
 
 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).
 
-Connection file format, env vars, and driver list: see `install.md`.
+Connection file format, env vars, and driver list: see `docs/install.md`.
 
 ## Quickstart
 
@@ -53,7 +53,7 @@ PY
 
 ## Architecture (~1k lines across 8 core files)
 
-- `install.md` — first-time install + first connection
+- `docs/install.md` — first-time install + first connection
 - `SKILL.md` — day-to-day usage
 - `lab/sql_harness/src/sql_harness/` — protected core package
 - `${XDG_CONFIG_HOME:-~/.config}/sql-harness/connections.toml` — plaintext credentials in ONE place
@@ -77,7 +77,7 @@ PY
 
 ## Contributing
 
-PRs and improvements welcome. See `AGENTS.md` for code priorities.
+PRs and improvements welcome. See `docs/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/zones/<conn>/skills/<name>.md` for that DSN, or `agent-workspace/zones/meta/skills/<name>.md` if it generalizes. Future sessions will read it before re-discovering it.
 - Bug fixes, new drivers, helper additions all welcome.

sql_harness-0.3.3/SKILL.md

@@ -0,0 +1,195 @@
+---
+name: sql-harness
+description: "Always use sql-harness for SQL, SSH, and database operations — querying any DSN (Postgres/MySQL/SQLite/Redis), inspecting schemas, running EXPLAIN plans, indexing analysis, schema migrations, shell exec over SSH, SFTP upload/download, and any cross-DSN workflow. Reach for it whenever the task touches a database, a remote host, or schema work — not just for `query()` calls."
+---
+
+# sql-harness
+
+A single-process SQL + SSH CLI for agents. 5 drivers (`postgres`, `mysql`, `sqlite`, `redis`, `ssh`) share one heredoc namespace. Connections live in plaintext in one TOML file.
+
+For setup, read `install.md`. For stuck-point mechanics, see `interaction-skills/` (cross-DB) and `interaction-skills/postgres/` (PG depth).
+
+## Reach for sql-harness when...
+
+- Any DB task: query, schema, migration, EXPLAIN, indexing, slow-query, stats
+- "Run this on the prod box": SSH workspace (`ssh_exec` / `ssh_upload` / `ssh_run_script`)
+- "Deploy this compose stack to remote": SSH + `interaction-skills/ssh/docker-via-ssh.md`
+- "The DB is behind a bastion / can't reach directly": SSH port-forward / tunnel
+- "Why is this query slow?": `explain_analyze` + `slow_queries` + `index_usage_stats`
+- "Which indexes are dead?": `unused_indexes` + `seq_scan_heavy`
+- "Compare row counts prod vs staging": `use_workspace("prod")` → `query()` → `use_workspace("staging")` → `query()`
+- "Save this heredoc as a reusable script": `sql-harness save <name> -c <conn>`
+- Anything where you would otherwise reach for `psql`, `mysql`, `pgcli`, or hand-rolled `subprocess` over SSH
+
+## Usage
+
+```bash
+sql-harness --help
+sql-harness list
+sql-harness add <name> --driver postgres --url 'postgresql://user:pw@host/db'
+sql-harness add <name> --driver mysql   --url 'mysql+pymysql://user:pw@host/db'
+sql-harness add <name> --driver ssh     --url 'ssh://user@host:22?key=/path/id_ed25519'
+sql-harness test <name>
+
+sql-harness <<'PY'
+use_workspace("local_pg")
+print(query("SELECT version()"))
+print(list_tables())
+PY
+```
+
+- Helpers are pre-imported; call by name in heredoc mode.
+- **First call requires `use_workspace(name)`** — no implicit default.
+- Set `BH_SQL_ZONE_SKILLS=1` once so `use_workspace()` auto-surfaces that zone's per-DSN skill docs (see `interaction-skills/zone-skill-auto-surface.md`).
+- For task-specific helpers, drop them into `agent-workspace/zones/<conn>/helpers.py` and they merge into the heredoc namespace (per-zone, overriding the shared base).
+- Other subcommands: `init` (scaffold connections.toml + install preset zone skills), `doctor` (SELECT 1 on every connection), `edit`/`remove`/`show`, `workspace {list,use,close,show}`, `save`/`run`/`scripts`, `skill` (bare: emit packaged SKILL.md; `install`/`list`/`show`), `paths`, `open`, `stats`, `version`, `ssh {exec,upload,download,run-script,info}`.
+- Zone-scoped subcommands (`save`, `run`, `scripts`, `skill list/show`, `ssh`) need `-c <conn>` or `$BH_SQL_ACTIVE_CONNECTION`.
+- **Analytics (ON by default)**: every CLI call and every doc read (`apply_skill`, `skill`, `skill show`) is counted into `$BH_SQL_HOME/analytics.json`; view with `sql-harness stats`. Every executed command (CLI argv or heredoc body) plus failures is appended to `$BH_SQL_HOME/sql-harness.log` (NDJSON, one record per line). Disable both with `BH_SQL_ANALYTICS=0|off|false|no`. Extension point: `from sql_harness.analytics import on, CLI_INVOKED, DOC_READ, COMMAND_EXECUTED` to attach custom listeners (observer pattern).
+
+## Drivers & capabilities
+
+Five drivers, one heredoc namespace. URL scheme must match the backend: MySQL requires `mysql+pymysql://`; PostgreSQL accepts `postgres://` / `postgresql://` (normalized to `postgresql+psycopg://`); SSH accepts `ssh://`, `ssh+password://`, `ssh+key://`. SSH password auth may come from the connection's standalone `password` key instead of the URL (precedence: URL > `password` > `$BH_SSH_PASSWORD`); a connection that sets a password uses password auth exclusively, ignoring local `~/.ssh` keys.
+
+### Postgres (`postgres://`)
+
+Full SQLAlchemy + psycopg3 + 8 PG-only introspection helpers. Reach for these whenever the task is "PG + performance" or "PG + schema":
+
+- `explain(sql)` — `EXPLAIN` plan (estimated)
+- `explain_analyze(sql, buffers=True)` — `EXPLAIN (ANALYZE, BUFFERS)` (real times)
+- `table_stats(name, schema=None)` — `pg_stat_user_tables` (seq vs idx scan counts, dead tuples)
+- `index_usage_stats(table=None, schema=None)` — `pg_stat_user_indexes` (idx scan counts per index)
+- `unused_indexes(...)` — indexes with zero idx scans (candidates for DROP)
+- `seq_scan_heavy(...)` — tables routinely full-scanned (candidates for new indexes)
+- `slow_queries(limit=10)` — top by `pg_stat_statements.mean_exec_time`
+- `missing_indexes_hint(...)` — heuristic: many seq scans + table size > threshold
+
+See `interaction-skills/postgres/` for the 8 depth docs (plan-reading, B-Tree, specialized indexes, table optimization, slow-queries-joins, jsonb, migrations, indexes-and-explain).
+
+### MySQL (`mysql+pymysql://`)
+
+Standard SQLAlchemy + PyMySQL. JSON syntax differs from PG — see `interaction-skills/mysql/json-columns.md`.
+
+### SQLite (`sqlite:///path.db`)
+
+Local dev / tests. All standard helpers work. Use `sql-harness add --driver sqlite --url 'sqlite:///<absolute-path>'` (SQLite needs absolute path).
+
+### Redis (`redis://host:port`)
+
+Stub driver — wired up but minimal helpers. Prefer `query()` won't work (Redis is not SQL). Skip if your task needs Redis; flag in your reply.
+
+### SSH (`ssh://user@host:port?key=...`)
+
+**Not a database** — a remote shell workspace. Reach for ssh whenever the task says "on the box", "the prod host", "deploy this", "upload that file", "run that command remotely":
+
+```python
+use_workspace("prod-app")
+r = ssh_exec("systemctl status myapp")           # exit_code + stdout/stderr
+ssh_upload("./deploy.sh", "/tmp/deploy.sh")       # SFTP
+ssh_download("/var/log/app.log", "./app.log")     # SFTP
+ssh_run_script("./scripts/deploy.sh")             # upload + execute
+print(ssh_info())                                 # user/host/port/SFTP available
+```
+
+CLI equivalent: `sql-harness ssh -c <conn> {exec|upload|download|run-script|info} <args>`.
+
+See `interaction-skills/ssh/` for: `ssh.md` (helpers + CLI + gotchas), `docker-via-ssh.md` (docker-compose deploy loop over SSH), `auth-and-tunnels.md` (auth scheme 选型 + 堡垒机 + 端口转发).
+
+## Generic SQL helpers (all DB drivers)
+
+| Helper | Returns | Use |
+|---|---|---|
+| `query(sql, params=None)` | `list[dict]` | SELECTs only |
+| `execute(sql, params=None)` | `dict` (`lastrowid`, `rowcount`) | INSERT/UPDATE/DELETE/DDL |
+| `list_tables(schema=None)` | `list[str]` | Schema recon — always start here |
+| `describe(table, schema=None)` | `list[dict]` | Columns + types — before writing SQL |
+| `table(name, schema=None, limit=None)` | `list[dict]` | Quick peek: `SELECT * FROM x LIMIT n` |
+| `with_transaction()` | context manager yielding `Connection` | ≥ 2 statements / DDL / atomicity |
+| `run_sql_file(path)` | `list[dict]` | Multi-statement `.sql`, one transaction |
+| `server_version()` | `str` | Round-trip liveness check |
+| `connection_info()` | `dict` | Current workspace metadata |
+| `use_workspace_info(name)` | `dict` | Zone info + skills + scripts (always surfaces) |
+
+## Interaction Skills
+
+Stuck-point mechanics — read on demand by filename. Top-level (cross-DB):
+
+- `interaction-skills/aggregations.md` (+ `aggregations-advanced.md`)
+- `interaction-skills/encoding-and-charset.md`
+- `interaction-skills/joins.md` (+ `joins-advanced.md`)
+- `interaction-skills/large-result-sets.md`
+- `interaction-skills/migrations.md`
+- `interaction-skills/pooling.md`
+- `interaction-skills/recursive-ctes.md` (+ `recursive-ctes-advanced.md`)
+- `interaction-skills/save-run-cycle.md`
+- `interaction-skills/schema-introspection.md`
+- `interaction-skills/timeouts-and-cancellation.md`
+- `interaction-skills/transactions.md`
+- `interaction-skills/window-functions.md` (+ `window-functions-advanced.md`)
+- `interaction-skills/zone-skill-auto-surface.md`
+
+PG-specific depth — `interaction-skills/postgres/`:
+
+- `interaction-skills/postgres/btree-indexes.md`
+- `interaction-skills/postgres/indexes-and-explain.md`
+- `interaction-skills/postgres/json-columns.md`
+- `interaction-skills/postgres/migrations.md`
+- `interaction-skills/postgres/plan-reading.md`
+- `interaction-skills/postgres/slow-queries-joins.md`
+- `interaction-skills/postgres/specialized-indexes.md`
+- `interaction-skills/postgres/table-optimization.md`
+
+MySQL-specific — `interaction-skills/mysql/`:
+
+- `interaction-skills/mysql/json-columns.md`
+
+SSH-specific — `interaction-skills/ssh/`:
+
+- `interaction-skills/ssh/auth-and-tunnels.md`
+- `interaction-skills/ssh/docker-via-ssh.md`
+- `interaction-skills/ssh/ssh.md`
+
+## Cross-DSN strategy skills
+
+Reached via `apply_skill("pool")` etc. from any active zone — `zones/meta/skills/` is the passive fallback layer.
+
+- `agent-workspace/zones/meta/skills/pool.md` — pool sizing, `pre_ping`, idle reuse.
+- `agent-workspace/zones/meta/skills/workspace.md` — workspace isolation, multi-DSN workflows.
+
+## What actually works (field-tested)
+
+- **Start with `list_tables` + `describe`, not `query`.** Before writing SQL on an unknown DB, run `list_tables(schema=None)` then `describe("table", schema=None)` to learn the columns. Skips the trial-and-error SELECT cycle.
+- **Set `BH_SQL_ZONE_SKILLS=1` once** so every `use_workspace()` surfaces that zone's per-DSN skill docs as a hint list (10 filenames max). Then `apply_skill(name)` reads the body when relevant.
+- **Default to `with_transaction()`** for any write with ≥ 2 statements (insert + update, drop + create, …). Atomic + automatic rollback on exception.
+- **For PG performance tasks, reach for the 8 PG-only helpers first** (`explain_analyze`, `slow_queries`, `unused_indexes`, `seq_scan_heavy`, `table_stats`, `index_usage_stats`, `missing_indexes_hint`). Don't hand-parse `pg_stat_*` SQL.
+- **For remote tasks, reach for SSH workspace first.** Don't reach for raw `subprocess` + ssh-key files in agent code — `ssh_exec("systemctl restart myapp")` is one line.
+- **For "insert returning the new id"**: psycopg supports `INSERT … RETURNING id`; MySQL has no `RETURNING` — use `execute(...)` and read `result.lastrowid`.
+- **Streaming large result sets**: `query()` loads every row into memory. For >10k rows, use `ws.engine.connect().execution_options(stream_results=True)` and iterate manually.
+- **Read-only "is this alive?" check**: `print(server_version())` — single round-trip, works on every DSN, no per-driver fudging.
+- **Auth wall**: redirected to login → stop and ask the user. Don't type credentials from `connection_info`/`describe`.
+- **Credentials in TOML**: use `${env:VAR}` indirection for prod secrets. The connections.toml loader expands these at load time.
+- **Cross-DB SQL**: prefer ANSI syntax (`'string'`, `LIMIT n OFFSET m`, `COALESCE`, `CURRENT_TIMESTAMP`). PG-specific: `::TYPE`, `JSONB`, `RETURNING`. MySQL-specific: `AUTO_INCREMENT`, backticks, `?` placeholders (sqlalchemy normalizes to `:name`).
+- **Save the workflow**: every working block → `sql-harness save <name> -c <conn>`. Tomorrow's session re-runs with one command. See `interaction-skills/save-run-cycle.md`.
+
+## Design Constraints
+
+- One connection = one workspace; never share engines across workspaces.
+- Connection pool defaults: `size=5, recycle=3600, pre_ping=True` (per-connection overrides win).
+- `with_transaction()` yields a `Connection`; use `conn.execute(text(...))` for raw control.
+- `query()` returns `list[dict]`; use `execute()` for INSERT/UPDATE/DELETE.
+- `list_tables()` and `describe()` are read-only schema introspection helpers.
+- SSH workspaces expose `ssh_exec` / `ssh_upload` / etc. Calling them on a non-SSH workspace raises `RuntimeError`.
+- PG-only helpers (`explain_analyze`, `table_stats`, ...) raise `NotImplementedError` on non-PG workspaces. Detect with `ws.driver.name == "postgres"`.
+- All engines live in `SqlHarness`'s in-memory registry. Single-process, no daemon, no remote backend.
+
+## Gotchas
+
+- Driver label in TOML must match the URL scheme (`postgres` ⇄ `postgresql://`, `mysql` ⇄ `mysql+pymysql://`, `ssh` ⇄ `ssh://` / `ssh+password://` / `ssh+key://`).
+- Passwords in TOML are plaintext; use `${env:VAR}` indirection for prod secrets. SSH accepts a standalone `password` key (keeps the URL clean); when one is set, local `~/.ssh` keys are ignored.
+- `query()` is for SELECTs only. For INSERTs, use `execute()`.
+- For tables > 10k rows, use `engine.connect().execution_options(stream_results=True)` and iterate manually — `query()` loads everything into memory.
+- SSH SFTP subsystem may be disabled on the remote host. `ssh_upload/ssh_download` raise `RuntimeError("SFTP subsystem not available")`; fall back to `tar -czf - | ssh host tar -xzf -` via `ssh_exec`.
+- Default `ssh_exec` timeout is 30 s. Long-running commands (e.g. `pg_dump`, `tar czf`) need explicit `timeout=`.
+
+## Domain / table skills
+
+Per-table or per-schema skills: drop a markdown file into `agent-workspace/zones/<conn>/skills/<name>.md`, read with `apply_skill(name)`. Cross-DSN strategy goes to `zones/meta/skills/` instead. PG optimization depth (plan reading, indexes, `table_stats`, `slow_queries`, …) lives in `interaction-skills/postgres/`.

{sql_harness-0.3.1 → sql_harness-0.3.3/docs}/AGENTS.md

@@ -15,11 +15,12 @@ Core code lives in `lab/sql_harness/src/sql_harness/`:
 - `manager.py` — SqlHarness class: holds engines, workspaces, skills registry
 - `helpers.py` — heredoc helpers (auto-imported)
 - `agent_loader.py` — loads `$BH_SQL_AGENT_WORKSPACE/agent_helpers.py`
+- `analytics.py` — event bus (observer) + JSON stats + NDJSON execution log: CLI call counts, doc-read tracking, command/error history; `BH_SQL_ANALYTICS` (default ON), view with `sql-harness stats`
 - `run.py` — heredoc entry; delegates to CLI otherwise
-- `cli.py` — argparse subparser CLI (~10 subcommands)
+- `cli.py` — argparse subparser CLI (18 subcommands)
 
 `SKILL.md` tells agents how to use the harness.
-`install.md` tells agents how to install and configure it.
+`docs/install.md` tells agents how to install and configure it.
 
 An agent operating the harness only edits inside `agent-workspace/`:
 - `agent_helpers.py` — task-specific query helpers the agent adds
@@ -28,4 +29,4 @@ An agent operating the harness only edits inside `agent-workspace/`:
 # Contributing
 Consider what is really needed. Prefer the smallest diff that fixes the bug.
 
-To add a backend: implement `drivers/<name>.py` against the Driver protocol, register in `drivers/__init__.py:get_driver()`, add `tests/unit/test_<name>.py` (see install.md §Drivers).
+To add a backend: implement `drivers/<name>.py` against the Driver protocol, register in `drivers/__init__.py:get_driver()`, add `tests/unit/test_<name>.py` (see `docs/install.md` §Drivers).

{sql_harness-0.3.1 → sql_harness-0.3.3/docs}/README.md

@@ -2,7 +2,7 @@
 
 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).
 
-Connection file format, env vars, and driver list: see `install.md`.
+Connection file format, env vars, and driver list: see `docs/install.md`.
 
 ## Quickstart
 
@@ -30,7 +30,7 @@ PY
 
 ## Architecture (~1k lines across 8 core files)
 
-- `install.md` — first-time install + first connection
+- `docs/install.md` — first-time install + first connection
 - `SKILL.md` — day-to-day usage
 - `lab/sql_harness/src/sql_harness/` — protected core package
 - `${XDG_CONFIG_HOME:-~/.config}/sql-harness/connections.toml` — plaintext credentials in ONE place
@@ -54,7 +54,7 @@ PY
 
 ## Contributing
 
-PRs and improvements welcome. See `AGENTS.md` for code priorities.
+PRs and improvements welcome. See `docs/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/zones/<conn>/skills/<name>.md` for that DSN, or `agent-workspace/zones/meta/skills/<name>.md` if it generalizes. Future sessions will read it before re-discovering it.
 - Bug fixes, new drivers, helper additions all welcome.

{sql_harness-0.3.1 → sql_harness-0.3.3}/docs/connections-toml-example.toml

@@ -18,7 +18,9 @@ echo = false
 # Connections
 # ---------------------------------------------------------------------------
 # Each [[connections]] block defines a named profile. Drivers: postgres, mysql,
-# redis (stub), sqlite. URL must match the driver.
+# redis (stub), sqlite, ssh / ssh+password / ssh+key. URL must match the driver.
+# Optional keys: description, password, pool_size, pool_recycle, pre_ping, echo,
+# application_name. `${env:VAR}` is expanded in both `url` and `password`.
 
 [[connections]]
 name = "local_pg"
@@ -51,11 +53,24 @@ driver = "ssh"
 url = "ssh://app@10.0.0.5:2222"
 description = "Production application host (key auth via $BH_SSH_KEY or ~/.ssh/id_ed25519)"
 
+# Password auth, credentials kept out of the URL (recommended). Each connection
+# carries its own password, so switching workspaces needs no env fiddling.
+# Precedence: URL-embedded password > this field > $BH_SSH_PASSWORD.
+# Note: a connection with a password uses password auth exclusively — local
+# ~/.ssh keys are not consulted.
+[[connections]]
+name = "iot_server"
+driver = "ssh"
+url = "ssh://113.44.193.72:22"
+password = "${env:IOT_SSH_PASSWORD}"
+description = "IoT host (password auth)"
+
+# URL-embedded password also works (driver label may be ssh or ssh+password).
 [[connections]]
 name = "lab-server"
 driver = "ssh+password"
 url = "ssh+password://lab:lab@192.168.1.10:22"
-description = "Lab box (password auth)"
+description = "Lab box (password auth, password in URL)"
 
 # ---------------------------------------------------------------------------
 # Optional per-connection pool overrides (alternative syntax)

{sql_harness-0.3.1 → sql_harness-0.3.3/docs}/install.md

@@ -79,19 +79,33 @@ name = "prod_pg"
 driver = "postgres"
 url = "${env:PROD_PG_URL}"            # env-var indirection
 pool_size = 10
+
+[[connections]]
+name = "iot_server"
+driver = "ssh"
+url = "ssh://113.44.193.72:22"
+password = "${env:IOT_SSH_PASSWORD}"  # standalone secret — keeps the URL clean
 ```
 
-`${env:VAR}` placeholders inside `url` are expanded at load time from the process environment — keep prod secrets out of the file.
+`${env:VAR}` placeholders inside `url` and `password` are expanded at load time from the process environment — keep prod secrets out of the file.
+
+Optional per-connection keys: `description`, `password`, `pool_size`, `pool_recycle`, `pre_ping`, `echo`, `application_name`.
+
+SSH password precedence (highest first): password embedded in `url` > the `password` key > `$BH_SSH_PASSWORD`. A connection that sets a password uses password auth exclusively — local `~/.ssh` keys are not consulted (see `interaction-skills/ssh/auth-and-tunnels.md`).
 
 ## Configuration env vars
 
 | Var | Purpose |
 |---|---|
 | `BH_SQL_HOME` | Override state root (`~/.config/sql-harness` by default) |
+| `BH_SQL_CONFIG_DIR` | Override config dir (defaults to `BH_SQL_HOME`) |
 | `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_SQL_ACTIVE_CONNECTION` | Active DSN zone for zone-scoped CLI (`save`/`run`/`scripts`/`skill list/show`) when no `-c` flag |
+| `BH_SQL_ZONE_SKILLS=1` | `use_workspace()` auto-surfaces the zone's skills/scripts |
+| `BH_SQL_ANALYTICS` | Analysis mode (CLI call counts + doc-read tracking + execution log). **Default ON**; set `0`/`off`/`false`/`no` to disable. Data: `$BH_SQL_HOME/analytics.json` (view with `sql-harness stats`) + `$BH_SQL_HOME/sql-harness.log` (append-only NDJSON: every executed command and its outcome) |
 | `BH_PG_URL` | Used by integration tests (skipped if unset) |
 | `BH_MYSQL_URL` | Used by integration tests (skipped if unset) |
 
@@ -106,7 +120,7 @@ pool_size = 10
 | `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.
+To add another SSH host: append a `[[connections]]` block with `driver = "ssh"` and an `ssh://...` URL. Use the `password` key for password auth, or `?key=/abs/path` for a key outside the default locations. `sql-harness test <name>` probes SSH with a remote `echo` instead of `SELECT 1`.
 
 ## Troubleshooting
 
@@ -115,7 +129,7 @@ To add another SSH host: append a `[[connections]]` block with `driver = "ssh"`
 | `ModuleNotFoundError: No module named 'psycopg'` | Run `uv sync`                                                         |
 | `sql-harness: command not found`                 | Use `uv run sql-harness ...` or activate `.venv`                      |
 | `password authentication failed`                 | Check URL; use `${env:VAR}` for prod secrets                          |
-| `unknown driver: 'X'`                            | Only `postgres`, `mysql`, `redis`, `sqlite` are built-in             |
+| `unknown driver: 'X'`                            | Only `postgres`, `mysql`, `redis`, `sqlite`, `ssh`/`ssh+password`/`ssh+key` are built-in             |
 | Heredoc mode complains `no workspace is active`   | You forgot `use_workspace(name)`                                      |
 | Heredoc mode complains `name 'X' is not defined`  | You forgot the import — all helpers are pre-imported, just call them  |
 

sql_harness-0.3.3/docs/maintainer.md

@@ -0,0 +1,58 @@
+# sql-harness standalone project
+
+## Quick reference for the maintainer
+
+| Task | Command |
+|---|---|
+| Install (editable dev mode) | `uv tool install --python 3.12 -e .` |
+| Build wheel + sdist | `uv build` |
+| Publish to TestPyPI | `uv publish --repository testpypi --token $TEST_PYPI_TOKEN` |
+| Publish to PyPI | `uv publish --token $PYPI_TOKEN` |
+| Refresh an agent's registered skill copy | `uv run sql-harness skill install` (or `skill > ~/.claude/skills/sql-harness/SKILL.md`) |
+
+## Why the SKILL.md sync step exists
+
+The in-package skill docs are **generated at build time**, not kept as
+hand-synced copies. `pyproject.toml` `[tool.hatch.build.targets.wheel.force-include]`
+maps the repo docs into the wheel:
+
+- `SKILL.md` → `sql_harness/_skills/SKILL.md`
+- `interaction-skills` → `sql_harness/_skills/interaction-skills`
+- `agent-workspace/zones/meta/skills` → `sql_harness/_skills/zones-meta-skills`
+
+The root `SKILL.md` is the **single source of truth** (v0.3.0 consolidation —
+the old `skills/sql-harness/SKILL.md` and `src/sql_harness/SKILL.md` copies
+were removed). After editing it, just `uv build` again. `sql-harness skill`
+reads `sql_harness/_skills/SKILL.md` from the installed package and falls
+back to the repo-root `SKILL.md` in a source checkout.
+
+## Build outputs
+
+```bash
+$ uv build
+Building source distribution...
+Building wheel from source distribution...
+Successfully built dist\sql_harness-0.3.0.tar.gz
+Successfully built dist\sql_harness-0.3.0-py3-none-any.whl
+```
+
+The wheel contains the package modules + the `_skills/` doc bundle
+(SKILL.md + interaction-skills tree + zones-meta-skills).
+
+## Test before publish
+
+```bash
+# standalone venv
+uv sync
+uv run pytest tests/unit -q    # 80 tests must pass
+uv run sql-harness --help      # CLI works
+uv run sql-harness skill       # SKILL.md emit works
+```
+
+## Local PyPI dry-run (no upload)
+
+```bash
+uv publish --dry-run
+# → checks both dist files against upload.pypi.org/legacy/
+# → errors with "no OIDC token" (expected; pass --token to actually publish)
+```

{sql_harness-0.3.1 → sql_harness-0.3.3}/docs/standalone-install.md

@@ -162,6 +162,6 @@ monorepo access to `from sql_harness import ...` for testing — no breakage.
 
 ## See also
 
-- `lab/sql_harness/install.md` — first-time install + troubleshooting
-- `lab/sql_harness/AGENTS.md` — code priorities + extension recipe
-- `lab/sql_harness/README.md` — user-facing quickstart
+- `lab/sql_harness/docs/install.md` — first-time install + troubleshooting
+- `lab/sql_harness/docs/AGENTS.md` — code priorities + extension recipe
+- `lab/sql_harness/docs/README.md` — user-facing quickstart

{sql_harness-0.3.1 → sql_harness-0.3.3}/interaction-skills/ssh/auth-and-tunnels.md

@@ -16,15 +16,29 @@
 
 ### 1.1 三种 scheme 对照
 
-`drivers/ssh.py:_parse_url` 支持的三种 URL 形式：
+`drivers/ssh.py` 认这三种 URL 形式：
 
-| URL 形式 | 何时用 | 取 key 顺序 |
+| URL 形式 | 何时用 | 认证方式 |
 |---|---|---|
-| `ssh://user@host:port` | 默认 key auth | `?key=...` → `$BH_SSH_KEY` → `~/.ssh/id_ed25519` → `id_rsa` → `id_ecdsa`（`KEY_FALLBACK`） |
-| `ssh+key://user@host:port?key=/abs/path` | key 不在默认路径 | URL 里的 `?key=` 单独覆盖 |
-| `ssh+password://user:pw@host:port` | 跳板 / 临时主机，没配 key | URL 嵌入密码；也可用 `$BH_SSH_PASSWORD` |
+| `ssh://user@host:port` | 默认 | 显式 key（`?key=`/`$BH_SSH_KEY`）→ key；否则配了密码 → 纯密码；都没有 → 自动找 `~/.ssh` key |
+| `ssh+key://user@host:port?key=/abs/path` | key 不在默认路径 | key 认证，密码作后备 |
+| `ssh+password://user[:pw]@host:port` | 跳板 / 临时主机 | 纯密码认证；密码可嵌 URL，也可放字段/env |
 
-**注意**：`ssh+password` 要求密码嵌入 URL。不想明文落 TOML，把密码放 `$BH_SSH_PASSWORD` 并用 `ssh://user@host`，但驱动**不会**自动回退到 env 密码（仅 key 走 env fallback）。这是常见混淆点。
+**密码来源优先级**（高 → 低）：URL 内嵌 > 连接里的 `password` 字段 > `$BH_SSH_PASSWORD`。
+
+**`password` 字段**（推荐——密码按连接存，切 workspace 不用动环境变量）：
+
+```toml
+[[connections]]
+name = "iot_server"
+driver = "ssh"
+url = "ssh://113.44.193.72:22"
+password = "${env:IOT_SSH_PASSWORD}"   # 也可直接写明文
+```
+
+**认证策略**（`_open_client`）：显式给 key（`?key=`/`$BH_SSH_KEY`）→ key 优先、密码兜底；没给 key 但配了密码 → **纯密码**，不翻 `~/.ssh`；都没有 → 自动发现 `~/.ssh/id_{ed25519,rsa,ecdsa}`。
+
+> 第三条很关键：paramiko 开着 `look_for_keys` 会逐个试 `~/.ssh` 里的 key，只要里面有一把解析不了的（旧 DSA key 是常见雷），认证线程直接抛异常、**在密码之前**就中断握手。所以配了密码就不会被本地散装 key 劫持。
 
 ### 1.2 用哪个连接串
 
@@ -32,7 +46,7 @@
 有 ed25519 key 在 ~/.ssh/ 且 authorized_keys 已加？
   ├─ 是 → ssh://user@host                                (默认 key path)
   └─ 否：
-      有密码但没 key？ → ssh+password://user:pw@host
+      有密码？ → 连接里加 password = "..."（driver 用 ssh 即可）
       key 在非默认路径？ → ssh://user@host?key=/path/to/k
       key 在 ssh-agent？ → §1.3
 ```
@@ -131,7 +145,8 @@ sql-harness 不内置 SSH SOCKS 代理；本机 `psql`/`TablePlus` 直连躲在
 ## Gotchas
 
 - **paramiko 不会自动用 ssh-agent**——见 §1.3。
-- **`ssh+password://` 必须嵌入密码**——`BH_SSH_PASSWORD` env 不会回退（仅 key 走 env fallback）。
+- **密码优先级**：URL 内嵌 > `password` 字段 > `$BH_SSH_PASSWORD`。配了密码即纯密码认证，本地 key 不再参与（见 §1.1）。
+- **服务端禁密码登录**：报 `Authentication failed` 时先确认服务端开了 `PasswordAuthentication`，别急着改本地配置。
 - **堡垒机转发时 `ssh -fN` 在某些堡垒机受限**——`AllowTcpForwarding no`。失败就 §2.2 走 paramiko `request_port_forward`。
 - **`request_port_forward` 返回的对象必须在 finally 里 cancel**，否则下次 `use_workspace` 复用 transport 报端口占用。
 - **workspace disconnect 不自动清 tunnel**——硬规矩：tunnel 用 try/finally 包起来。

{sql_harness-0.3.1 → sql_harness-0.3.3}/pyproject.toml

@@ -1,8 +1,8 @@
 [project]
 name = "sql-harness"
-version = "0.3.1"
+version = "0.3.3"
 description = "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."
-readme = "README.md"
+readme = "docs/README.md"
 license = { text = "MIT" }
 authors = [
     { name = "much-bigpy" },

sql_harness-0.3.3/skills/sql-harness/README.txt

@@ -0,0 +1,8 @@
+# sql-harness — skills bundle (mirrors browser-harness/skills/browser-harness/)
+
+v0.3.0 起 SKILL.md 副本已移除：分发版由 pyproject force-include 在 build 时
+从根 SKILL.md 自动生成到 wheel 的 sql_harness/_skills/（本目录不再放 SKILL.md）。
+
+Contents:
+- `references/install.md` — one-time install + first-connection guide
+  (synced copy of the repo-root install.md)