Nb MCP Server

🚀 Opencode Plugins for Quality Assurance

This directory houses Opencode plugins that offer quality assurance and enforce development workflows. These plugins are ported from Claude Code hooks.

🚀 Quick Start

The Opencode plugins for quality assurance are designed to enhance your development process. They provide checks and enforcements at various stages of your workflow.

✨ Features

1. post-edit-linter.js (WORKING)

• Purpose: Executes linters after file updates.
• Event: tool.execute.after (for the edit tool).
• Behavior:
  • Checks the availability of the hatch command.
  • Verifies the existence of the develop Hatch environment.
  • Runs hatch --env develop run linters.
  • Throws an error with truncated output (maximum 50 lines) if the linters fail.
  • Exits early if the conditions are not met (e.g., hatch is not available).
  • Note: It uses tool.execute.after instead of file.edited because LLM - initiated edits do not trigger file.edited.

2. git-commit-guard.js-disabled (DISABLED - Opencode bash tool limitation)

• Purpose: Would prevent git commits when linters or tests fail.
• Status: DISABLED - Opencode's bash tool does not pass the command in input.args.command.
• Issue: The plugin intercepts tool.execute.before, but input.args is empty for the bash tool.
• Original intent: A port of the Claude Code hook pre-bash-git-commit-check.

3. python-environment-guard.js-disabled (DISABLED - Opencode bash tool limitation)

• Purpose: Would detect improper Python usage in Bash commands.
• Status: DISABLED - Opencode's bash tool does not pass the command in input.args.command.
• Issue: The plugin intercepts tool.execute.before, but input.args is empty for the bash tool.
• Original intent: A port of the Claude Code hook pre-bash-python-check.

📦 Installation

When copying this template to a downstream project:

1. Navigate to the plugin directory:

   cd .auxiliary/configuration/coders/opencode/plugin
   

2. Install dependencies:

   npm install
   

3. Ensure symlink exists:

   # From project root
   ln -sf .auxiliary/configuration/coders/opencode .opencode
   

4. Verify plugin loading: Opencode should automatically load plugins from .opencode/plugin/.

📚 Documentation

Dependencies

• shlex: Shell command parsing (port of Python's shlex module), used in disabled plugins.
• bun: Runtime (provided by Opencode).

Porting Notes

These plugins are ports of Claude Code hooks with varying success:

Critical Discovery

• Opencode's bash tool limitation: During testing, it was found that Opencode's bash tool does not pass the command string in input.args.command (or any input.args field). The input.args object is empty {} when the bash tool is invoked, preventing plugins from intercepting and analyzing bash commands.
• Working solution: Only post-edit-linter.js works because it uses tool.execute.after for the edit tool, where file information is available in output.metadata.filediff.file.

Error Messages

All error messages match the original Claude Code hooks exactly, including:

• Linter output truncation to 50 lines.
• "Divine admonition" for git commit blocking.
• Warning messages for Python usage.

Testing

To test the plugins:

1. File edit test: Edit a Python file and verify that the linters run.
2. Git commit test: Try git commit -m "test" and verify that the checks run.
3. Python usage test: Try python -c "print('test')" and verify the warning.

Troubleshooting

• Plugins not loading:
  • Verify that the .opencode symlink points to .auxiliary/configuration/coders/opencode.
  • Check if the Opencode version supports the plugin API.
  • Ensure that the dependencies are installed (npm install).
• Command not found errors:
  • Verify that hatch is installed and in the PATH.
  • Check if the develop Hatch environment exists: hatch env show.
• Timeout issues:
  • Timeouts match Python hooks (60s, 120s, 300s).
  • Uses Promise.race with setTimeout since the Bun shell lacks native timeout.

Source Code

The original Claude Code hooks are located in template/.auxiliary/configuration/coders/claude/scripts/:

• post-edit-linter
• pre-bash-git-commit-check
• pre-bash-python-check