Add db-query relocate cuse add db-query tool

[zJeremiah]

Quality check

• Documentation included
• Test coverage

Summary

Organizes CLI applications under cmd/ and adds a new database query tool.

• Relocate cuse: Move cuse to cmd/cuse as an independent Go module and update the release workflow paths accordingly.
• Add db-query: New CLI for read-only queries against Oracle, Postgres, MySQL, SQLite, BigQuery, and MongoDB, with JSON/table output and a companion MCP server (db-query-mcp).
• Tests and docs: Includes cmd/db-query/README.md, config/SQL/Mongo unit tests, and an example TOML config.

[qodo-code-review]

PR Summary by Qodo

Organize cmd/ CLIs: move cuse module and add db-query (plus MCP server)

✨ Enhancement ⚙️ Configuration changes 📝 Documentation 🧪 Tests 🕐 40+ Minutes

AI Description

• Relocate cuse to cmd/cuse as an independent Go module and fix release paths.
• Add db-query CLI for read-only queries across SQL/BigQuery/Mongo with JSON/CSV/table output.
• Provide MCP stdio server wrapper, example TOML config, and unit tests for config/query safety.

Diagram

graph TD
  Client(["Client / Agent"]) --> MCP["db-query-mcp"] --> CLI["db-query CLI"]
  Client --> CLI
  CLI --> Cfg[("config.toml")]
  CLI --> SQL[("SQL DBs")]
  CLI --> BQ[("BigQuery")]
  CLI --> Mongo[("MongoDB")]
  subgraph Legend
    direction LR
    _actor(["Client"]) ~~~ _svc["Service"] ~~~ _db[("Database")]
  end

Loading

High-Level Assessment

The following are alternative approaches to this PR:

1. Parse SQL AST for read-only enforcement

• ➕ More robust than keyword regex (fewer false positives/negatives)
• ➕ Can detect dialect-specific write patterns (e.g., SELECT INTO, CALL/EXEC wrappers)
• ➖ Adds complexity and dependencies; SQL dialect support is tricky
• ➖ Still won’t cover non-SQL backends (Mongo) and may require per-driver nuance

2. Implement MCP server in-process (share packages) instead of exec wrapper

• ➕ Avoids spawning a subprocess per tool call
• ➕ Single code path for validation/connect/output reduces drift
• ➖ Requires refactoring CLI into reusable packages and defining stable APIs
• ➖ Harder to keep stdout/stderr discipline and CLI behavior identical

3. Use a CLI/config framework (cobra/viper)

• ➕ Standardized flag UX, subcommands, config layering
• ➕ Potentially simpler future expansion (more commands, completion, docs gen)
• ➖ Heavier dependency footprint for a small tool
• ➖ Current flag + custom TOML is already clear and testable

Recommendation: Current approach is a good tradeoff: keep the CLI lightweight, enforce read-only behavior centrally, and use an MCP wrapper that execs the same binary to guarantee parity. If query capabilities expand (more dialects, more complex SQL), consider migrating read-only enforcement from regex/heuristics to an AST-based parser for stronger guarantees.

Files changed (35) +3088 / -7 · 9 not counted

Enhancement (11) +1613 / -0

main.goAdd MCP stdio server exposing db-query as tools +184/-0

Add MCP stdio server exposing db-query as tools

• Implements an MCP server with tools for listing databases, running queries, pinging, and listing Mongo collections; delegates execution to the db-query CLI via the internal mcpcli wrapper.

cmd/db-query/cmd/db-query-mcp/main.go

config.goImplement TOML config loading and validation +216/-0

Implement TOML config loading and validation

• Adds config structures for database definitions, default path resolution via 'DB_QUERY_CONFIG', validation (including unique names), and BigQuery field/auth normalization (signal-api-style aliases).

cmd/db-query/internal/config/config.go

bigquery.goAdd BigQuery runner with ADC/service-account auth support +177/-0

Add BigQuery runner with ADC/service-account auth support

• Implements BigQuery connection creation, dry-run ping, query execution with optional default dataset/location, row limiting/truncation, and value normalization for JSON output.

cmd/db-query/internal/db/bigquery.go

mongo.goAdd MongoDB runner with read-only query validation +270/-0

Add MongoDB runner with read-only query validation

• Implements MongoDB connect/ping/close, listCollections, and JSON-based find/aggregate execution with explicit rejection of write stages like '$out'/'$merge', plus BSON-to-JSON-friendly value normalization.

cmd/db-query/internal/db/mongo.go

postgres.goSupport Postgres TLS mode that skips hostname verification +111/-0

Support Postgres TLS mode that skips hostname verification

• Adds an alternate Postgres connection path using pgx with a TLS config that can skip hostname verification while still validating the certificate chain when a root CA is provided.

cmd/db-query/internal/db/postgres.go

query_options.goDefine per-query execution options (limit, dataset) +7/-0

Define per-query execution options (limit, dataset)

• Introduces a small options struct passed through runners to control row limiting and BigQuery default dataset selection.

cmd/db-query/internal/db/query_options.go

query_output.goDefine normalized query output shape for all backends +8/-0

Define normalized query output shape for all backends

• Adds a shared '{columns, rows, row_count, truncated}' output struct used by JSON/CSV/table formatting and the MCP wrapper.

cmd/db-query/internal/db/query_output.go

runner.goAdd backend dispatcher for SQL, BigQuery, and Mongo runners +83/-0

Add backend dispatcher for SQL, BigQuery, and Mongo runners

• Implements a unified Runner that selects the correct backend based on config type and exposes Ping/RunQuery plus a Mongo-only ListCollections entrypoint.

cmd/db-query/internal/db/runner.go

sql.goAdd SQL runner for Oracle/Postgres/MySQL/SQLite with read-only SQLite +201/-0

Add SQL runner for Oracle/Postgres/MySQL/SQLite with read-only SQLite

• Implements generic SQL connectivity via sqlx with per-backend DSN building (including read-only SQLite DSNs and MySQL default port), query execution with row limiting, and JSON-friendly value normalization.

cmd/db-query/internal/db/sql.go

exec.goAdd helper for MCP server to execute db-query safely +113/-0

Add helper for MCP server to execute db-query safely

• Implements binary resolution ('DB_QUERY_BIN', sibling binary, or PATH), executes db-query with stdout/stderr separation, and provides helpers for list/query/ping/list-collections operations.

cmd/db-query/internal/mcpcli/exec.go

main.goImplement db-query CLI with read-only enforcement and output formats +243/-0

Implement db-query CLI with read-only enforcement and output formats

• Adds the main CLI: loads TOML config, supports listing DBs, ping, Mongo list-collections, reads SQL from flag or stdin, blocks non-read-only SQL (non-SELECT/WITH, forbidden keywords, multiple statements), and writes JSON/CSV/table output with truncation handling.

cmd/db-query/main.go

Refactor (5)

api.goRelocate cuse API client code under cmd/cuse _{not counted}

Relocate cuse API client code under cmd/cuse

• Moves the existing 'cuse' API implementation into the 'cmd/cuse' module layout without intended functional changes.

cmd/cuse/api.go

browser.goRelocate cuse browser automation under cmd/cuse _{not counted}

Relocate cuse browser automation under cmd/cuse

• Carries over the login/browser automation code into the new 'cmd/cuse' module directory.

cmd/cuse/browser.go

env.goRelocate cuse environment helpers under cmd/cuse _{not counted}

Relocate cuse environment helpers under cmd/cuse

• Moves '.env'/environment helper utilities into the new module path to keep behavior consistent after relocation.

cmd/cuse/env.go

login.goRelocate cuse login flow under cmd/cuse _{not counted}

Relocate cuse login flow under cmd/cuse

• Moves the login-related implementation into the 'cmd/cuse' module directory as part of the CLI reorganization.

cmd/cuse/login.go

main.goRelocate cuse CLI entrypoint under cmd/cuse _{not counted}

Relocate cuse CLI entrypoint under cmd/cuse

• Moves the 'cuse' CLI main package into 'cmd/cuse' to match the new module location.

cmd/cuse/main.go

Tests (7) +563 / -0

browser_test.goRelocate cuse browser tests under cmd/cuse _{not counted}

Relocate cuse browser tests under cmd/cuse

• Moves the existing browser-related tests to match the new 'cmd/cuse' module structure.

cmd/cuse/browser_test.go

main_test.goRelocate cuse CLI tests under cmd/cuse _{not counted}

Relocate cuse CLI tests under cmd/cuse

• Moves the main-package tests to align with the relocated CLI module path.

cmd/cuse/main_test.go

config_test.goAdd unit tests for config validation and lookup behavior +241/-0

Add unit tests for config validation and lookup behavior

• Covers required fields per backend, duplicate name rejection, BigQuery alias normalization/auth defaults, sqlite requirements, and Find() behavior when db name is omitted.

cmd/db-query/internal/config/config_test.go

mongo_test.goTest Mongo query parsing and write-stage rejection +102/-0

Test Mongo query parsing and write-stage rejection

• Adds unit tests verifying JSON parsing requirements and rejecting forbidden aggregate stages to enforce read-only behavior.

cmd/db-query/internal/db/mongo_test.go

runner_test.goEnsure Mongo-only operations are rejected for non-Mongo runners +18/-0

Ensure Mongo-only operations are rejected for non-Mongo runners

• Adds a focused test that ListCollections fails unless the runner is backed by Mongo.

cmd/db-query/internal/db/runner_test.go

sql_test.goTest DSN generation and SQLite read-only querying +142/-0

Test DSN generation and SQLite read-only querying

• Adds tests for MySQL DSN defaults, SQLite read-only DSN building, and an integration-style SQLite query test using a temp database file.

cmd/db-query/internal/db/sql_test.go

main_test.goTest SQL read-only validation rules +60/-0

Test SQL read-only validation rules

• Adds unit tests for allowing SELECT/WITH and trailing semicolons while rejecting write keywords and multiple statements.

cmd/db-query/main_test.go

Documentation (3) +501 / -2

README.mdUpdate cuse build/install instructions for cmd/cuse +2/-2

Update cuse build/install instructions for cmd/cuse

• Updates the from-source instructions to 'cd cmd/cuse' and corrects the relative build output path in the README.

cmd/cuse/README.md

README.mdDocument db-query usage, config, backends, and MCP integration +446/-0

Document db-query usage, config, backends, and MCP integration

• Adds comprehensive docs covering TOML configuration, backend-specific notes (including BigQuery auth and Postgres SSL hostname skipping), usage patterns, output formats, and MCP server setup.

cmd/db-query/README.md

config.example.tomlProvide example TOML config for supported backends +53/-0

Provide example TOML config for supported backends

• Adds a copyable example config showing Oracle, Postgres (with optional SSL settings), BigQuery auth modes, MongoDB, SQLite, and MySQL entries.

cmd/db-query/config.example.toml

Other (9) +411 / -5

release.ymlUpdate release workflow paths for relocated cuse module +3/-3

Update release workflow paths for relocated cuse module

• Switches the Go version file, module cache paths, and GoReleaser workdir from 'cuse/' to 'cmd/cuse/' so tag releases keep working after the relocation.

.github/workflows/release.yml

.goreleaser.yamlRetain GoReleaser config under cmd/cuse _{not counted}

Retain GoReleaser config under cmd/cuse

• Keeps the existing GoReleaser build/archive/checksum configuration colocated with the relocated 'cuse' module.

cmd/cuse/.goreleaser.yaml

MakefileFix cuse build output path after directory move +1/-1

Fix cuse build output path after directory move

• Adjusts the build output location to account for 'cuse' living under 'cmd/cuse/' (now outputs to '../../scripts/cuse').

cmd/cuse/Makefile

go.modRename cuse module path to repo-qualified import path +1/-1

Rename cuse module path to repo-qualified import path

• Changes the module name from 'cuse' to 'github.com/hydronica/ai-toolkit/cmd/cuse' so it can be built and released as an independent module under 'cmd/'.

cmd/cuse/go.mod

go.sumRelocate cuse dependency lockfile under cmd/cuse _{not counted}

Relocate cuse dependency lockfile under cmd/cuse

• Carries the module dependency checksums alongside the relocated 'go.mod'.

cmd/cuse/go.sum

.gitignoreIgnore local db-query configs, certs, and binaries +6/-0

Ignore local db-query configs, certs, and binaries

• Adds ignores for local 'config.toml', auth/cert files, and the 'bin/' output directory used during development.

cmd/db-query/.gitignore

MakefileAdd build/test targets for db-query and db-query-mcp +14/-0

Add build/test targets for db-query and db-query-mcp

• Introduces a simple Makefile to build both binaries, run tests with race/coverage, and clean build artifacts.

cmd/db-query/Makefile

go.modIntroduce db-query module with multi-backend drivers and MCP dependency +90/-0

Introduce db-query module with multi-backend drivers and MCP dependency

• Defines a standalone Go module for 'cmd/db-query' and brings in dependencies for SQL drivers, BigQuery, MongoDB, TOML config loading, and MCP server support.

cmd/db-query/go.mod

go.sumAdd dependency checksums for db-query module +296/-0

Add dependency checksums for db-query module

• Locks dependency versions and checksums for the new db-query module.

cmd/db-query/go.sum

[qodo-code-review]

Code Review by Qodo

🐞 Bugs (0) 📘 Rule violations (0) 📎 Requirement gaps (0) 🎨 UX issues (0) 🔗 Cross-repo conflicts (0) 📜 Skill insights (0)

1. Unauthenticated Postgres TLS ✓ Resolved 🐞 Bug ⛨ Security

Description

When ssl_skip_hostname_verify=true and sslrootcert is not set, postgresTLSConfigSkipHostname
sets InsecureSkipVerify=true without adding a replacement verifier, so the Postgres connection
accepts any server certificate (MITM risk). Config validation does not require sslrootcert in this
mode, so this insecure configuration is permitted.

Code

cmd/db-query/internal/db/postgres.go[R79-108]

+	// Verify the chain against the CA when provided, but skip hostname matching.
+	tlsConfig.InsecureSkipVerify = true
+	if roots != nil {
+		roots := roots
+		tlsConfig.VerifyPeerCertificate = func(rawCerts [][]byte, _ [][]*x509.Certificate) error {
+			if len(rawCerts) == 0 {
+				return fmt.Errorf("no server certificate")
+			}
+			cert, err := x509.ParseCertificate(rawCerts[0])
+			if err != nil {
+				return fmt.Errorf("parse server cert: %w", err)
+			}
+			intermediates := x509.NewCertPool()
+			for _, raw := range rawCerts[1:] {
+				intermediate, err := x509.ParseCertificate(raw)
+				if err != nil {
+					return fmt.Errorf("parse intermediate cert: %w", err)
+				}
+				intermediates.AddCert(intermediate)
+			}
+			_, err = cert.Verify(x509.VerifyOptions{
+				Roots:         roots,
+				Intermediates: intermediates,
+			})
+			if err != nil {
+				return fmt.Errorf("verify server cert: %w", err)
+			}
+			return nil
+		}
+	}

Evidence

TLS verification is explicitly disabled, and manual verification is only configured when a custom
root CA pool exists; there is no config-level guard requiring sslrootcert when hostname
verification is skipped.

cmd/db-query/internal/db/postgres.go[53-110]
cmd/db-query/internal/config/config.go[95-131]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
`ssl_skip_hostname_verify` currently disables hostname verification by setting `tls.Config.InsecureSkipVerify = true`, but only re-enables certificate chain verification when `sslrootcert` is provided. If `sslrootcert` is omitted, the server certificate is not verified at all.

## Issue Context
This is a security boundary for database credentials and query confidentiality.

## Fix Focus Areas
- cmd/db-query/internal/db/postgres.go[53-110]
- cmd/db-query/internal/config/config.go[95-131]

## Suggested fix
- Enforce that `ssl_skip_hostname_verify=true` requires `sslrootcert` (fail fast in config validation).
- Alternatively (stronger), always verify the server cert chain even when `sslrootcert` is empty by using system roots (e.g., `x509.SystemCertPool()`), while still skipping hostname matching.
- Add a unit test for the validation rule (and/or for TLS config behavior).

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

2. SQLite override not read-only ✓ Resolved 🐞 Bug ⛨ Security

Description

For SQLite, a configured connection override is returned unchanged, bypassing
ensureSQLiteReadOnly, so a plain file:/path/to.db (or mode=rw) can open the DB read-write
despite the tool’s read-only contract. This makes the safety boundary depend on users remembering to
add mode=ro manually.

Code

cmd/db-query/internal/db/sql.go[R107-111]

+	case "sqlite":
+		if conn := strings.TrimSpace(dbCfg.Connection); conn != "" {
+			return "sqlite", conn, nil
+		}
+		return "sqlite", sqliteDSN(dbCfg), nil

Evidence

The sqlite connection override path returns the DSN unchanged, while the helper that enforces
read-only (ensureSQLiteReadOnly) is only used when constructing a DSN from dbCfg.DB.

cmd/db-query/internal/db/sql.go[99-115]
cmd/db-query/internal/db/sql.go[160-179]
cmd/db-query/internal/db/sql_test.go[69-77]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
SQLite DSNs built from `db` are forced read-only via `ensureSQLiteReadOnly`, but SQLite DSNs provided via `connection` are passed through as-is.

## Issue Context
The README/config describe SQLite as read-only; `connection` should not weaken that guarantee.

## Fix Focus Areas
- cmd/db-query/internal/db/sql.go[107-112]
- cmd/db-query/internal/db/sql.go[160-179]
- cmd/db-query/internal/db/sql_test.go[69-77]

## Suggested fix
- When `dbCfg.Connection` is set for SQLite:
 - If it has no `mode=` parameter, append `mode=ro` (use `ensureSQLiteReadOnly`).
 - If it has `mode=` and it is not `ro`, reject with a clear error (to prevent explicit `mode=rw` bypass).
- Add tests for `connection = "file:/tmp/x.sqlite"` (should become read-only) and `connection = "file:/tmp/x.sqlite?mode=rw"` (should error).

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

3. Read-only SQL bypass ✓ Resolved 🐞 Bug ⛨ Security

Description

validateReadOnlyQuery relies on a small forbidden-keyword blacklist, so SELECT-prefixed write
forms (e.g., Postgres SELECT ... INTO new_table) are not blocked even though db-query claims
read-only enforcement. The query is then executed verbatim via runner.RunQuery, allowing
non-read-only effects when the DB user has write privileges.

Code

cmd/db-query/main.go[R145-159]

+func validateReadOnlyQuery(query string) error {
+	trimmed := strings.TrimSpace(query)
+	trimmed = strings.TrimSuffix(trimmed, ";")
+	upper := strings.ToUpper(trimmed)
+
+	if !strings.HasPrefix(upper, "SELECT") && !strings.HasPrefix(upper, "WITH") {
+		return errors.New("only read-only SELECT queries are allowed")
+	}
+	if forbidden.MatchString(upper) {
+		return errors.New("query contains forbidden keywords; only read-only SELECT queries are allowed")
+	}
+	if strings.Count(trimmed, ";") > 0 {
+		return errors.New("only a single SQL statement is allowed")
+	}
+	return nil

Evidence

The validator only checks a fixed blacklist and statement prefix, and does not include checks for
SELECT-based write constructs like INTO; after validation, the query is executed through the
runner without additional enforcement.

cmd/db-query/main.go[20-20]
cmd/db-query/main.go[145-159]
cmd/db-query/main.go[105-118]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The current SQL read-only enforcement is a keyword blacklist plus a `SELECT`/`WITH` prefix check. This is not sufficient to prevent write-capable SELECT forms (e.g. `SELECT ... INTO ...`) across supported dialects.

## Issue Context
`db-query` markets itself as read-only; validation is the primary guardrail before passing the SQL directly to the DB driver.

## Fix Focus Areas
- cmd/db-query/main.go[20-20]
- cmd/db-query/main.go[145-159]

## Suggested fix
- Add explicit blocking for common SELECT-based write constructs (at minimum `\bINTO\b` when the statement begins with `SELECT`/`WITH`, and dialect-specific cases like MySQL `INTO OUTFILE`).
- Consider using a SQL parser / AST-based approach (dialect-aware) rather than regex.
- Add regression tests demonstrating that `SELECT ... INTO ...` (and other known bypasses you support) are rejected.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

4. SQL connect ignores context ✓ Resolved 🐞 Bug ☼ Reliability

Description

connectSQL uses sqlx.Connect(driver, dsn) (non-context) before PingContext, so connection
establishment can block past the CLI’s timeout/cancellation context. This undermines -timeout as
an operational guardrail during initial connection setup.

Code

cmd/db-query/internal/db/sql.go[R26-36]

+func connectSQL(ctx context.Context, dbCfg *config.Database) (*sqlRunner, error) {
+	driver, dsn, err := sqlConnectionDetails(dbCfg)
+	if err != nil {
+		return nil, err
+	}
+
+	db, err := sqlx.Connect(driver, dsn)
+	if err != nil {
+		return nil, fmt.Errorf("connect: %w", err)
+	}
+

Evidence

The main CLI uses a timeout context for the whole operation, but the SQL connection setup uses a
non-context connect call, so the timeout cannot reliably bound the connection establishment phase.

cmd/db-query/internal/db/sql.go[26-46]
cmd/db-query/main.go[60-71]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
`connectSQL` uses `sqlx.Connect` which does not accept a context. Only the subsequent ping uses `PingContext`, so cancellation/timeout may not apply to initial connect setup.

## Issue Context
The CLI creates a timeout-bounded context (`context.WithTimeout`) specifically to bound end-to-end operations.

## Fix Focus Areas
- cmd/db-query/internal/db/sql.go[26-46]
- cmd/db-query/main.go[60-71]

## Suggested fix
- Prefer `sqlx.ConnectContext(ctx, driver, dsn)` if available in the pinned sqlx version.
- Otherwise, use `sqlx.Open(driver, dsn)` followed by `PingContext(ctx)` (and close on error) so the only network interaction is context-bounded.
- Add/adjust tests as needed to cover the new connect path.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

Tip of the day

💡 Did you know, you can route each action level your way: inline, summary, both, or drop

More tips ↗ | Customize Qodo ↗ | Qodo docs ↗

[jbsmith7741]

1. Address the comments listed.
2. Can we combine the mcp and cli tools into a single binary with a flag or something that can be used to toggle between the two purposes?
3. In order for this tool to be useful for this repo we would need an associated skill that can be used to query DBs that are define and help with setup connections to Databases.
4. If this is the case then would we want this installed as part of the default install.sh script?
5. Make sure to go through ALL the code to try and reduce the amount of code generated, making a more concise tool.

[jbsmith7741]

Do we add the db-query binary to the release files so they can be downloaded and run without needing go?