diff --git a/.agents/skills/xsql/SKILL.md b/.agents/skills/xsql/SKILL.md new file mode 100644 index 0000000..8fe5646 --- /dev/null +++ b/.agents/skills/xsql/SKILL.md @@ -0,0 +1,123 @@ +--- +name: xsql +description: Use when Codex needs to inspect MySQL or PostgreSQL with the xsql CLI, especially for safe read-only querying, schema discovery, profile inspection, machine-readable JSON output, stable error-code handling, SSH-backed connections, or MCP server setup in this repository. +--- + +# xsql + +Use `xsql` as an AI-first database CLI. Prefer it when the task requires stable JSON output, explicit error codes, schema discovery, or profile-aware access to MySQL/PostgreSQL. + +## Read The Contract First + +Read only the docs needed for the task: + +- `docs/cli-spec.md`: command behavior, output formats, exit codes +- `docs/error-contract.md`: JSON/YAML success and failure shapes, stable error codes +- `docs/ai.md`: AI-oriented workflow, `schema dump`, MCP usage +- `docs/config.md`: profile layout, config path resolution, CLI/ENV/config precedence +- `docs/db.md`: read-only policy and query safety model +- `docs/ssh-proxy.md`: SSH behavior, host-key validation, proxy fallback + +If the user asks for code changes to xsql itself, align with these docs before editing code. If implementation and docs diverge, update docs first. + +## Default Operating Rules + +- Prefer `--format json` for agent work, even if TTY would default to table. +- Treat `stdout` as data and `stderr` as logs; never parse logs as result data. +- Check `ok`, `schema_version`, and `error.code` instead of relying on human-readable text. +- Assume read-only mode unless the user explicitly requests write behavior. +- Do not suggest or use `--unsafe-allow-write` unless the task truly requires writes and the user has made that intent explicit. +- Do not leak secrets, full DSNs, passwords, private keys, or passphrases in output, logs, or summaries. +- Treat `--ssh-skip-known-hosts-check` as a risky last resort and call out the security tradeoff if it is required. + +## Working Sequence + +Use this sequence unless the user already knows the exact profile and SQL to run: + +1. Identify the profile with `xsql profile list --format json`. +2. Inspect the chosen profile with `xsql profile show --format json`. +3. Discover schema with `xsql schema dump -p -f json`. +4. Write a minimal read-only query against the confirmed tables and columns. +5. Run `xsql query "" -p -f json`. +6. Validate `ok`, `schema_version`, returned columns/rows, or `error.code`. + +Prefer `schema dump` over guessing table names or dialect details. + +## Command Patterns + +```bash +# List available profiles +xsql profile list --format json + +# Inspect a profile before querying +xsql profile show --format json + +# Discover schema before writing SQL +xsql schema dump --profile --format json + +# Filter schema discovery when the table family is known +xsql schema dump --profile --table "user*" --format json + +# Run a read-only query +xsql query "SELECT id, name FROM users LIMIT 10" --profile --format json + +# Export tool metadata for agent integration +xsql spec --format json + +# Start MCP server +xsql mcp server +``` + +## Querying Guidance + +- Start with schema discovery, then query. +- Keep queries narrow: explicit columns, predicates, and `LIMIT`. +- Match SQL syntax to the target engine after confirming whether the profile is MySQL or PostgreSQL. +- Use aggregation or sampling before asking for large result sets. +- Expect read-only enforcement to block writes through both SQL analysis and read-only transactions. + +## Output And Error Handling + +For machine-readable formats, expect: + +```json +{"ok":true,"schema_version":1,"data":{...}} +``` + +```json +{"ok":false,"schema_version":1,"error":{"code":"...","message":"...","details":{...}}} +``` + +Handle failures by `error.code` and exit status, not by fragile string matching. Important exit codes in this repo: + +- `0`: success +- `2`: argument/config error +- `3`: DB or SSH connection error +- `4`: read-only policy blocked a write +- `5`: database execution error +- `10`: internal error + +Table and CSV output are for humans; they do not include `ok` or `schema_version`. + +## Config And Profile Rules + +- Resolve precedence as `CLI > ENV > Config`. +- Use `XSQL_`-prefixed env vars when environment configuration is needed. +- Default config lookup is `./xsql.yaml`, then `~/.config/xsql/xsql.yaml`, unless `--config` is provided. +- Prefer keyring-backed secrets. Plaintext secrets require explicit allowance. +- If no profile is passed and a `default` profile exists, xsql may use it automatically. + +## SSH Rules + +- Prefer the built-in SSH driver-dial path; it is the default design for MySQL/PostgreSQL. +- Use the local port-forwarding proxy mode only when the workflow explicitly needs `xsql proxy` semantics or a driver fallback. +- Keep host-key verification enabled by default. +- For one-shot commands such as `query` and `schema dump`, expect fresh SSH/DB connections rather than long-lived reconnect behavior. + +## If You Are Modifying xsql + +- Keep CLI-layer logic in `cmd/xsql` thin. +- Keep core behavior in `internal/*`, not coupled to Cobra types. +- Preserve output contracts and stable error codes. +- Update docs before implementing any external behavior change. +- Add or update tests for JSON output, exit codes, and read-only behavior. diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 0ed21f9..7a64acd 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -10,30 +10,10 @@ { "name": "xsql", "description": "Use when you need to safely inspect MySQL/PostgreSQL data or schema via the xsql CLI.", - "version": "1.0.0", - "author": { - "name": "zx06" - }, - "homepage": "https://github.com/zx06/xsql", - "repository": "https://github.com/zx06/xsql", - "license": "MIT", - "keywords": [ - "xsql", - "sql", - "mysql", - "postgresql", - "database", - "cli", - "ssh", - "query" + "source": "./", + "skills": [ + "./.agents/skills/xsql" ], - "category": "database", - "tags": [ - "read-only", - "schema", - "mcp" - ], - "source": "./.claude-plugin", "strict": true } ] diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json deleted file mode 100644 index c5479bf..0000000 --- a/.claude-plugin/plugin.json +++ /dev/null @@ -1,22 +0,0 @@ -{ - "name": "xsql", - "version": "1.0.0", - "description": "Use when you need to safely inspect MySQL/PostgreSQL data or schema via the xsql CLI.", - "author": { - "name": "zx06", - "url": "https://github.com/zx06" - }, - "homepage": "https://github.com/zx06/xsql", - "repository": "https://github.com/zx06/xsql", - "license": "MIT", - "keywords": [ - "xsql", - "sql", - "mysql", - "postgresql", - "database", - "cli", - "ssh", - "query" - ] -} diff --git a/skills/xsql/SKILL.md b/skills/xsql/SKILL.md deleted file mode 100644 index cb6af57..0000000 --- a/skills/xsql/SKILL.md +++ /dev/null @@ -1,128 +0,0 @@ ---- -name: xsql -description: Use when you need to safely inspect MySQL/PostgreSQL data or schema via the xsql CLI. -license: MIT -compatibility: Designed for Claude Code and compatible AI agents that can run CLI commands. -metadata: - repository: https://github.com/zx06/xsql - docs: https://github.com/zx06/xsql#readme - category: database-cli -allowed-tools: Bash(xsql:*) ---- - -# xsql - AI-first Cross-Database CLI Tool - -xsql is a command-line tool designed for AI agents to execute read-only SQL queries on MySQL and PostgreSQL databases, with optional SSH tunnel support. - -## Installation - -```bash -go install github.com/zx06/xsql/cmd/xsql@latest -``` - -## Prerequisites - -- Ensure a valid `xsql.yaml` exists (`./xsql.yaml` or `~/.config/xsql/xsql.yaml`) or pass `--config`. -- Confirm the target profile exists before running queries. - -## Quick Reference - -```bash -# Query with profile -xsql query "SELECT * FROM users LIMIT 10" -p -f json - -# List all profiles -xsql profile list -f json - -# Show profile details -xsql profile show -f json - -# Get tool spec -xsql spec --format json - -# Check version -xsql version -``` - -## Common Query Workflows - -### 0. Identify the target database - -```bash -# List profiles -xsql profile list -f json - -# Inspect a profile to confirm database/host -xsql profile show -f json -``` - -### 1. Explore schema - -SQL syntax varies by database (MySQL vs PostgreSQL). Adjust statements as needed. - -```bash -# List tables -xsql query "SHOW TABLES" -p -f json - -# Describe a table -xsql query "DESCRIBE table_name" -p -f json -``` - -### 2. Understand data distribution - -```bash -# Count rows -xsql query "SELECT COUNT(*) AS total FROM table_name" -p -f json - -# Sample rows -xsql query "SELECT * FROM table_name LIMIT 10" -p -f json -``` - -### 3. Investigate problematic records - -```bash -# Time window -xsql query "SELECT * FROM table_name WHERE created_at >= NOW() - INTERVAL 7 DAY" -p -f json - -# Key field filter -xsql query "SELECT * FROM table_name WHERE status = 'failed' LIMIT 50" -p -f json -``` - -## Commands - -| Command | Purpose | -| --- | --- | -| `xsql query ` | Run a query (read-only by default) | -| `xsql profile list` | List profiles | -| `xsql profile show` | Show profile details | -| `xsql spec` | Export tool spec | -| `xsql version` | Version info | -| `xsql mcp server` | MCP integration | - -### Query Flags - -- `-p, --profile`: Select profile -- `-f, --format`: `json|yaml|table|csv|auto` -- `--unsafe-allow-write`: Allow writes (dangerous, disabled by default) -- `--allow-plaintext`: Allow plaintext passwords (only when explicitly enabled in config) -- `--ssh-skip-known-hosts-check`: Skip known_hosts check (risky) - -## Output & Errors - -- Non-TTY defaults to JSON, TTY defaults to table -- Use `-f json` to force JSON output -- stdout is data; stderr is logs -- Success: `{"ok":true,...}`; failure: `{"ok":false,"error":{...}}` -- Exit codes are stable; use `error.code` for programmatic handling - -## Config & Env - -- Priority: CLI > ENV > Config -- Paths: `--config` > `./xsql.yaml` > `~/.config/xsql/xsql.yaml` -- Store secrets in keyring when possible; allow plaintext only when explicitly enabled - -## Best Practices - -- Use `-f json` for machine consumption -- Use `ok` and `error.code` to decide success -- Read-only by default; writes require `--unsafe-allow-write`