Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
167 lines (126 loc) · 7.52 KB

CONTRIBUTING.md

File metadata and controls

167 lines (126 loc) · 7.52 KB
Raw

Contributing to CockroachDB Plugin for Codex

Thank you for your interest in contributing! This guide covers the plugin itself — hooks, MCP configuration, and tooling. For contributing skills, see the cockroachdb-skills CONTRIBUTING.md instead; skills are maintained upstream and synced here automatically.

Getting Started

Prerequisites

  • Codex CLI installed
  • MCP Toolbox for Databases v1.0.0+ (Homebrew, binary download, or container)
  • Python 3 (for hook scripts — no external dependencies)
  • A running CockroachDB instance (local or cloud)

Setup

git clone --recurse-submodules https://github.com/cockroachdb/codex-plugin.git
cd codex-plugin

Set your connection environment variables:

export COCKROACHDB_HOST=localhost
export COCKROACHDB_PORT=26257
export COCKROACHDB_USER=root
export COCKROACHDB_PASSWORD=
export COCKROACHDB_DATABASE=defaultdb
export COCKROACHDB_SSLMODE=disable

Test the plugin locally:

codex plugin marketplace add "$(pwd)"
codex plugin add cockroachdb@cockroachdb-codex-plugin

Validate that the marketplace install layout is correct:

python3 -m unittest -v tests/test_plugin_package.py
REPO_URL="file://$(pwd)" ./scripts/validate-marketplace-install.sh HEAD

Project Structure

.agents/plugins/
  marketplace.json         # Codex marketplace catalog entry
plugins/cockroachdb/       # Plugin payload (the directory Codex installs)
  .codex-plugin/
    plugin.json            # Plugin manifest (version managed by Release Please)
  .mcp.json                # MCP server definitions (Toolbox stdio, Cloud)
  tools.yaml               # MCP Toolbox source and tool definitions
  hooks/
    hooks.json             # Hook triggers and matchers (Codex's default hooks location)
  scripts/
    validate-sql.py        # PreToolUse: blocks dangerous SQL patterns
    check-sql-files.py     # PostToolUse: lints files for anti-patterns
    setup-cockroachdb.sh   # Local 3-node cluster + Toolbox bootstrap
  assets/
    logo.svg               # Brand mark
  skills/                  # Synced from cockroachdb-skills submodule (do not edit directly)
scripts/                   # Repo-level tooling (not shipped with the plugin)
  sync-skills.sh           # Refresh plugins/cockroachdb/skills/ from submodule
  validate-marketplace-install.sh
submodules/
  cockroachdb-skills/      # Upstream skills submodule

What You Can Contribute

Area Examples
Hooks New safety checks, additional SQL anti-pattern detection
MCP config New backend integrations, connection improvements
Tools New tool definitions in tools.yaml
Bug fixes Path handling, env var defaults, config issues
Documentation README improvements, inline comments

What belongs elsewhere

Development Workflow

  1. Fork the repository and create a feature branch:

    git checkout -b fix/describe-your-change

  2. Make your changes — match the existing code style and conventions.

  3. Test locally — install the plugin from the local path: codex plugin marketplace add "$(pwd)" && codex plugin add cockroachdb@cockroachdb-codex-plugin. Verify your change works.

  4. Test hook scripts (if modified):

    # validate-sql.py — expects JSON on stdin
echo '{"tool_input":{"sql":"SELECT 1"}}' | python3 plugins/cockroachdb/scripts/validate-sql.py

# check-sql-files.py — expects JSON on stdin
echo '{"tool_input":{"file_path":"test.sql"}}' | python3 plugins/cockroachdb/scripts/check-sql-files.py

  5. Commit using Conventional Commits:

    git commit -m "fix: quote PLUGIN_ROOT for paths with spaces"
git commit -m "feat: add new hook to validate index definitions"
git commit -m "docs: clarify Cloud MCP setup in README"

  6. Open a Pull Request against main.

Commit Conventions

This repo uses Release Please for automated versioning and changelogs. Your commit prefix determines what happens:

Prefix Effect Example
fix: Patch release (0.1.x) fix: handle empty SQL in validate hook
feat: Minor release (0.x.0) feat: add index validation hook
docs: No release docs: update README with new backend
chore: No release chore: update submodule reference

Important:

  • Never bump the version in plugin.json or .release-please-manifest.json manually — Release Please owns these files.
  • Use fix: or feat: only for changes that should appear in the changelog and trigger a release.

Guidelines

Hooks

  • Hook scripts must be Python 3 with no external dependencies (stdlib only).
  • Read JSON from stdin, write JSON to stdout.
  • Always exit 0 and signal a block through JSON. Codex treats exit 2 with stderr text as a block, so a crashing script would block every matched call; the trailing ; exit 0 in each command keeps a missing or crashing script fail-open.
  • Keep hooks in plugins/cockroachdb/hooks/hooks.json, where Codex looks by default when the manifest declares no hooks.
  • Codex runs hook commands in the session's working directory, not the plugin root, so reference scripts through ${PLUGIN_ROOT}, which Codex substitutes into the command, and quote it for paths with spaces: 
    "command": "python3 \"${PLUGIN_ROOT}/scripts/your-script.py\" --codex; exit 0"
  • Pass --codex to the scripts. Codex rejects unknown top-level keys in hook output and then ignores the whole output, so the scripts emit only systemMessage and hookSpecificOutput in that mode.
  • Matchers see Codex's tool names: MCP tools become mcp__<server>__<tool> with every character outside [A-Za-z0-9_] replaced by _ (so mcp__cockroachdb_toolbox__cockroachdb_execute_sql), and file edits are apply_patch, whose input is the patch text in tool_input.command.
  • Codex runs plugin hooks only after the user trusts them in /hooks, and asks again when a hook definition changes.

MCP Configuration

  • .mcp.json defines MCP server backends.
  • Use env_vars to forward variables to stdio servers and env_http_headers to source HTTP header values from variables.
  • The tools.yaml file uses Toolbox v1.1.0 map-based format with ${VAR:default} syntax for defaults.

Skills

Skills are synced from the upstream cockroachdb-skills submodule into plugins/cockroachdb/skills/ by a weekly CI workflow. Do not edit files in plugins/cockroachdb/skills/ directly — changes will be overwritten. Contribute new skills to the upstream repo instead.

Reporting Issues

  • Use GitHub Issues for bugs and feature requests.
  • Include your plugin version (plugin.json → version), Codex version, and OS.
  • For connection issues, include the MCP backend you're using (Toolbox, Cloud MCP, or ccloud).

License

By contributing, you agree that your contributions will be licensed under the Apache-2.0 License.