If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/TaKO8Ki/gobang shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

WAIT — Stale — last commit 2y ago

• 9 active contributors
• MIT licensed
• CI configured
• ⚠ Stale — last commit 2y ago
• ⚠ Single-maintainer risk — top contributor 90% of recent commits
• ⚠ No test directory detected

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live TaKO8Ki/gobang repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/TaKO8Ki/gobang.

What it runs against: a local clone of TaKO8Ki/gobang — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in TaKO8Ki/gobang | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | Last commit ≤ 940 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of TaKO8Ki/gobang. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/TaKO8Ki/gobang.git
#   cd gobang
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of TaKO8Ki/gobang and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "TaKO8Ki/gobang(\\.git)?\\b" \\
  && ok "origin remote is TaKO8Ki/gobang" \\
  || miss "origin remote is not TaKO8Ki/gobang (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 940 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~910d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/TaKO8Ki/gobang"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Gobang is a cross-platform TUI (terminal user interface) database management tool written in Rust that provides keyboard-driven navigation and SQL query execution across MySQL, PostgreSQL, and SQLite databases. It replaces GUI database clients with a lightweight, keyboard-only interface inspired by vim keybindings, allowing developers to browse schemas, execute queries, and view result tables entirely within the terminal. Monorepo with two crates: the main src/ contains the TUI app (src/app.rs is the core orchestrator, src/components/ holds UI elements like sql_editor, record_table, connections), and database-tree/ is a separate library (database-tree/src/databasetree.rs) that abstracts schema navigation. Event handling lives in src/event/ and database drivers (MySQL, PostgreSQL, SQLite) are in src/database/.

Database developers and DevOps engineers who spend significant time in terminals and prefer keyboard-driven workflows; users on resource-constrained systems or SSH sessions who cannot use heavyweight GUI tools like DBeaver or DataGrip; Rust enthusiasts who want a native, fast database client.

Gobang is actively developed but still alpha (v0.1.0-alpha.5). It has basic CI/CD setup in .github/workflows (ci.yml, release.yml) and is distributed across multiple package managers (Homebrew, Scoop, AUR, NixOS, pkgsrc), indicating community adoption. However, the README lists incomplete features (SQL editor, custom keybindings, themes) and the alpha tag signals breaking changes are expected—not production-ready for mission-critical work.

Single-maintainer risk is significant (TaKO8Ki is the primary author). The dependency tree is moderate (~15 major crates including sqlx, tokio, tui) with async/SQL handling delegated to stable, well-maintained libraries, but the alpha status means the API and command structure could break. No visible test suite in the file list (no tests/ directory mentioned) is a red flag for a data-touching tool.

The project is in active maintenance mode with release workflows in place (release.yml), suggesting regular version bumps. The TODO list in the README indicates work on SQL editor completion, custom keybindings, and theme support. No recent commit data is visible in the file list, but the presence of CI workflows and multi-platform package manager integration suggests ongoing polish.

git clone https://github.com/TaKO8Ki/gobang.git
cd gobang
cargo build --release
cargo run --release

Then edit or create a config file (sample.toml is provided) to add database connections, and run gobang -c <config-path> to start.

Daily commands:

cargo run --release
# or with a custom config:
cargo run --release -- -c sample.toml

For development: cargo run (debug) or cargo build (compilation only).

• src/app.rs: Main orchestrator that ties together events, UI components, and database operations; core state machine for the TUI application
• src/components/mod.rs: Exports all UI components and manages their visibility/interaction lifecycle
• src/database/mod.rs: Abstract trait definition for database drivers; any new database support requires implementation here
• database-tree/src/databasetree.rs: Core logic for building and traversing the database schema tree (databases → tables → columns)
• src/event/key.rs: Keyboard event mapping and vim-like keybinding definitions; main place to understand control flow
• src/config.rs: Config file parsing for database connections; essential for understanding how connections are loaded
• src/components/sql_editor.rs: SQL editor component (currently incomplete per README); likely where most feature work happens next
• src/components/record_table.rs: Renders query results as a scrollable table; critical path for displaying data

Adding a new database driver: extend src/database/mod.rs and create a new file like src/database/cockroachdb.rs following the patterns in src/database/mysql.rs. Fixing UI bugs: edit src/components/<component-name>.rs (e.g., src/components/record_table.rs for table rendering). Adding keybindings: modify src/event/key.rs and the event handling in src/app.rs. Schema navigation: modify database-tree/src/databasetree.rs for tree logic.

Config file required: Gobang cannot connect to databases without a valid TOML config file specifying connection strings; there is no interactive connection wizard (mentioned in TODOs). Async runtime: All database I/O is async (tokio), so any synchronous code blocks the entire UI—mutations must respect this. SQLx compile-time checking: sqlx verifies SQL queries at compile time against a live database (requires DATABASE_URL env var during build), which can slow CI or fail if DB is unreachable. Platform-specific dependencies: Unix (non-macOS) systems require the which crate (specified in Cargo.toml under cfg gate), which could cause build issues on Windows if not properly handled.

• Async/await with Tokio — Gobang uses tokio for non-blocking I/O to keep the TUI responsive while executing database queries; understanding async Rust is critical for modifying database operations without freezing the UI
• Tree data structure (N-ary tree) — The schema browser (database-tree crate) represents databases → tables → columns as an N-ary tree; contributors modifying schema navigation must understand tree traversal and iteration
• Trait-based abstraction (async-trait) — Database drivers (MySQL, PostgreSQL, SQLite) implement a common async trait in src/database/mod.rs; adding new database support requires understanding Rust trait bounds and async traits
• Immediate Mode GUI (IMGui) vs Retained Mode — tui-rs uses a retained-mode approach where components maintain state across frames; understanding this differs from immediate-mode GUIs common in web frameworks
• Event-driven architecture — Gobang's event loop (src/event/events.rs) decouples user input from rendering; keyboard events flow through a central event handler that updates app state and components
• vim keybindings (hjkl navigation) — The primary user interaction model uses hjkl for movement and modal editing patterns; understanding vim's philosophy is essential for navigating and extending keybindings
• Terminal Capabilities (terminfo, ANSI escape codes) — Crossterm abstracts terminal I/O and rendering; debugging display issues or adding new terminal features requires knowledge of how ANSI codes and terminal capability negotiation work

• datafuselabs/databend — Cloud-native SQL database engine with Rust-based architecture; complementary for understanding async database clients at scale
• sqlx-rs/sqlx — The async SQL toolkit Gobang depends on; understanding sqlx internals helps debug query execution and connection pooling
• ratatui-org/ratatui — Successor/fork of the tui-rs library Gobang uses; useful for understanding TUI rendering patterns and contributing upstream fixes
• pgcli/pgcli — Python-based PostgreSQL CLI with autocomplete and similar keyboard-driven design; inspiration for Gobang's UI philosophy
• dbcli/mycli — MySQL CLI with similar TUI approach; shows alternative patterns for database-specific CLI tools

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add integration tests for database module covering MySQL, PostgreSQL, and SQLite

The repo supports three database backends (src/database/mysql.rs, src/database/postgres.rs, src/database/sqlite.rs) but there are no visible integration tests in the dev-dependencies or test directory. Testing connection pooling, query execution, and error handling across all three backends would catch regressions early and improve code reliability for a tool that manages production databases.

• [ ] Create src/database/tests/mod.rs with test modules for each database type
• [ ] Add test fixtures/sample databases (SQLite test file, docker-compose for MySQL/PostgreSQL in CI)
• [ ] Write tests for connection establishment, basic SELECT/INSERT/UPDATE queries, and error handling in src/database/tests/
• [ ] Update .github/workflows/ci.yml to spin up MySQL and PostgreSQL services for integration tests

Add unit tests for src/components/ module covering UI state management

The components directory contains 13 modules (command.rs, completion.rs, connections.rs, databases.rs, etc.) that handle complex UI state (filtering, tab management, table rendering). No test files are visible, making refactoring risky. Testing the state transitions in record_table.rs, table_filter.rs, and database_filter.rs would catch bugs and document expected behavior.

• [ ] Create tests/ directory at repo root and add tests/components_integration.rs
• [ ] Write unit tests for src/components/record_table.rs focusing on sorting, pagination, and cell value display
• [ ] Write unit tests for src/components/table_filter.rs and src/components/database_filter.rs for filter state transitions
• [ ] Add property-based tests using proptest for filter query parsing in src/components/completion.rs

Implement comprehensive error handling documentation and add error recovery tests for src/database/

The database module uses anyhow::Result but there's no visible documentation of error types or recovery strategies. The src/components/error.rs exists but lacks corresponding tests. Adding structured error types and tests would help new contributors understand failure modes when connections drop, queries timeout, or data is invalid.

• [ ] Create src/database/error.rs with a custom Error enum replacing generic anyhow usage (connection errors, query errors, auth errors)
• [ ] Add documentation comments to src/database/mod.rs explaining error recovery strategies for each backend
• [ ] Write tests in src/database/tests/errors.rs covering connection timeout, auth failure, and malformed query scenarios
• [ ] Update src/components/error.rs to match new error types and add unit tests for error display rendering

• Add unit tests to database-tree/src/tree_iter.rs and database-tree/src/treeitems_iter.rs—there is no tests/ directory visible, and tree iteration logic is critical to schema navigation; writing tests would both catch bugs and help a new contributor understand the tree structure.
• Implement missing help text for SQL editor in src/components/help.rs—the README lists 'SQL editor' as incomplete, and the help component exists but likely lacks documentation for the editor; adding help modal content requires understanding keybindings without much complex logic.
• Extract hardcoded keybindings from src/app.rs into a configurable keymap struct (related to 'Custom key bindings' TODO)—currently key handling is scattered; consolidating this would enable the planned custom keybindings feature and improve code readability.

• High · Outdated and Vulnerable Dependencies — Cargo.toml (dependencies section). The codebase uses several dependencies with known vulnerabilities or outdated versions. Notably: tui v0.15.0 (from 2021), sqlx v0.5.6 (outdated), crossterm v0.20 (deprecated), and tokio v1.11.0 (very old). These versions contain publicly disclosed security vulnerabilities and lack security patches. Fix: Update all dependencies to their latest stable versions. Run 'cargo audit' to identify specific CVEs and apply patches. Consider using 'cargo-outdated' for dependency management.
• High · Potential SQL Injection via Dynamic Query Construction — src/database/mysql.rs, src/database/postgres.rs, src/database/sqlite.rs, src/components/sql_editor.rs. The codebase contains database query functionality in src/database/ modules (mysql.rs, postgres.rs, sqlite.rs). Without seeing the implementation, dynamic SQL query construction from user input via the SQL editor component (src/components/sql_editor.rs) could be vulnerable to SQL injection if not properly parameterized. Fix: Ensure all database queries use prepared statements with parameterized queries. Never concatenate user input directly into SQL strings. Use sqlx's built-in query builder with type-safe parameters.
• High · Insecure Dependency: structopt and clap (Argument Parsing) — Cargo.toml (clap, structopt dependencies), src/cli.rs. The application uses clap v2.33.3 and structopt v0.3.22, both of which are very old (2020-2021). These versions may have unpatched vulnerabilities. Additionally, direct use of user-supplied command-line arguments without proper validation could lead to injection attacks. Fix: Upgrade to clap v4.x (latest major version) which has better security and validation. Replace deprecated structopt with clap's derive feature. Validate all CLI arguments for expected formats.
• Medium · Hardcoded Configuration Paths — src/config.rs, sample.toml. The application uses dirs-next crate to manage configuration directories (src/config.rs likely uses this). Default behavior may expose sensitive database credentials in plaintext in configuration files without encryption. Fix: Implement encryption for stored database credentials. Use environment variables for sensitive data instead of config files. Consider using a secrets management approach or credential helper tools.
• Medium · Missing Input Validation in Table Filter Component — src/components/table_filter.rs, src/components/database_filter.rs. The table_filter.rs and database_filter.rs components accept user input for filtering. Without proper validation and escaping, this could enable injection attacks, especially if filters are used to construct dynamic queries. Fix: Implement strict input validation with whitelist patterns for filter inputs. Sanitize all user input before using in query construction. Use parameterized queries exclusively.
• Medium · Insufficient Error Handling and Information Disclosure — src/components/error.rs, src/database/mod.rs. Error components (src/components/error.rs) may display sensitive information such as database connection strings, query details, or system paths to users. This could aid attackers in reconnaissance. Fix: Implement secure error handling that logs detailed errors server-side but shows generic user-friendly messages. Never expose database credentials, internal paths, or query details to the UI.
• Medium · Clipboard Management Security — src/clipboard.rs. The clipboard.rs component handles copying data to system clipboard. Sensitive data (credentials, query results) may persist in clipboard history unencrypted, accessible to other applications. Fix: Clear clipboard data after a timeout (e.g., 30 seconds). Warn users before copying sensitive data. Consider providing an option to disable clipboard integration for sensitive environments.
• Low · Missing SECURITY.md File — Repository root. The repository lacks a SECURITY.md file with responsible disclosure guidelines. This makes it difficult for security researchers to report vulnerabilities responsibly. Fix: Create a SECURITY.md file outlining the vulnerability disclosure process and security contact information.
• Low · No Security Headers or HTTPS — undefined. undefined Fix: undefined

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.