opencode-froggy 0.1.0

package/README.md

@@ -0,0 +1,440 @@
+# opencode-froggy
+
+## Overview
+
+opencode-froggy is an OpenCode plugin that adds agents, commands, skills, and a hook system.
+It can automatically simplify changes when the session becomes idle, if files were modified
+via `write` or `edit`. Resources are loaded automatically from `agent/`, `command/`, and `skill/`.
+Hooks are loaded from OpenCode configuration directories (global and project-level).
+
+## Features
+
+### Agents
+
+| Agent | Mode | Description |
+|-------|------|-------------|
+| `code-reviewer` | subagent | Reviews code for quality, correctness, and security. Read-only with restricted git access. |
+| `code-simplifier` | subagent | Simplifies recently modified code for clarity and maintainability while strictly preserving behavior. |
+| `doc-writer` | subagent | Technical writer that crafts clear, comprehensive documentation (README, API docs, architecture docs, user guides). |
+
+### Commands
+
+| Command | Description | Agent |
+|---------|-------------|-------|
+| `/commit` | Create a commit with appropriate message, create branch if on main/master, and push | `build` |
+| `/review-changes` | Review uncommitted changes (staged + unstaged, including untracked files) | `code-reviewer` |
+| `/review-pr <source> <target>` | Review changes from source branch into target branch | `code-reviewer` |
+| `/simplify-changes` | Simplify uncommitted changes (staged + unstaged, including untracked files) | `code-simplifier` |
+| `/tests-coverage` | Run the full test suite with coverage report and suggest fixes for failures | `build` |
+
+### Skills
+
+The plugin supports skills loaded from `skill/<name>/SKILL.md` within the plugin directory. No skills are included by default. The plugin exposes a `skill` tool that lists available skills and returns their instructions.
+
+To add your own skills, create a directory structure like:
+
+```
+skill/
+  my-skill/
+    SKILL.md
+```
+
+The `SKILL.md` file supports YAML frontmatter with `name` and `description` fields. The name defaults to the directory name if not specified.
+
+### Hooks
+
+Hooks run actions on session events. Configuration is loaded from standard OpenCode configuration directories.
+
+#### Configuration locations
+
+Hooks are loaded from these locations (in order, merged together):
+
+| Platform | Global | Project |
+|----------|--------|---------|
+| Linux | `~/.config/opencode/hook/hooks.md` | `<project>/.opencode/hook/hooks.md` |
+| macOS | `~/.config/opencode/hook/hooks.md` | `<project>/.opencode/hook/hooks.md` |
+| Windows | `~/.config/opencode/hook/hooks.md` or `%APPDATA%/opencode/hook/hooks.md` | `<project>/.opencode/hook/hooks.md` |
+
+On Windows, `~/.config` is preferred for cross-platform consistency. If hooks exist in `%APPDATA%` but not in `~/.config`, the `%APPDATA%` location is used.
+
+Global hooks run first, then project hooks are added. Hooks from both sources are combined (not overridden).
+
+#### Configuration file
+
+- YAML frontmatter must include a `hooks` list.
+- Each hook defines `event`, `actions`, and optional `conditions`.
+- Hooks for the same event run in declaration order.
+
+Example `hooks.md`:
+
+```markdown
+---
+hooks:
+  - event: session.idle
+    conditions: [hasCodeChange, isMainSession]
+    actions:
+      - command: simplify-changes
+---
+```
+
+#### Supported events
+
+| Event | Description |
+|-------|-------------|
+| `session.idle` | Emitted when a session becomes idle and has files modified via `write` or `edit` in that session |
+| `session.created` | Emitted when a session is created |
+| `session.deleted` | Emitted when a session is deleted |
+| `tool.before.*` | Emitted before any tool executes. Exit code 2 blocks the tool. |
+| `tool.before.<name>` | Emitted before a specific tool (e.g., `tool.before.write`). Exit code 2 blocks the tool. |
+| `tool.after.*` | Emitted after any tool executes |
+| `tool.after.<name>` | Emitted after a specific tool (e.g., `tool.after.edit`) |
+
+**Tool hook execution order:**
+1. `tool.before.*` (all tools)
+2. `tool.before.<name>` (specific tool)
+3. *(tool executes)*
+4. `tool.after.*` (all tools)
+5. `tool.after.<name>` (specific tool)
+
+**Blocking tools with exit code 2:**
+For `tool.before.*` and `tool.before.<name>` hooks, a bash action returning exit code 2 will block the tool from executing. The stderr output is displayed to the user as the block reason.
+
+#### Conditions
+
+| Condition | Description |
+|-----------|-------------|
+| `isMainSession` | Run only for the main session (not sub-sessions) |
+| `hasCodeChange` | Run only if at least one modified file looks like code |
+
+All listed conditions must pass for the hook to run.
+
+Code extensions treated as "code" by default:
+`ts`, `tsx`, `js`, `jsx`, `mjs`, `cjs`, `json`, `yml`, `yaml`, `toml`, `css`, `scss`, `sass`, `less`, `html`, `vue`, `svelte`, `go`, `rs`, `c`, `h`, `cpp`, `cc`, `cxx`, `hpp`, `java`, `py`, `rb`, `php`, `sh`, `bash`, `kt`, `kts`, `swift`, `m`, `mm`, `cs`, `fs`, `scala`, `clj`, `hs`, `lua`.
+
+#### Supported actions
+
+- **Command**
+  - Short form: `command: simplify-changes`
+  - With args:
+    - `command:`
+      - `name: review-pr`
+      - `args: "main feature"`
+  - If the command exists in config, the plugin reuses its `agent` and `model`.
+- **Skill**
+  - `skill: my-skill`
+  - The name must match a loaded skill. The plugin prompts the session to call the `skill` tool for that skill.
+- **Tool**
+  - `tool:`
+    - `name: bash`
+    - `args: { command: "echo done" }`
+  - The plugin prompts the session to use the tool with these arguments.
+- **Bash**
+  Executes a shell command directly without involving the LLM. Useful for running linters, formatters, build scripts, or custom automation.
+
+  **Configuration:**
+  ```yaml
+  # Short form
+  - bash: "npm run lint"
+
+  # Long form with custom timeout
+  - bash:
+      command: "$OPENCODE_PROJECT_DIR/.opencode/hooks/init.sh"
+      timeout: 30000  # milliseconds (default: 60000)
+  ```
+
+  **Environment variables:**
+
+  The plugin injects these variables into the child process environment before executing the command:
+
+  | Variable | Value | Use case |
+  |----------|-------|----------|
+  | `OPENCODE_PROJECT_DIR` | Absolute path to the project (e.g., `/home/user/project`) | Reference project files from scripts located elsewhere |
+  | `OPENCODE_SESSION_ID` | The OpenCode session identifier | Logging, tracing, or conditioning actions based on session |
+
+  Example usage in a script:
+  ```bash
+  #!/bin/bash
+  # Access variables directly
+  echo "Project: $OPENCODE_PROJECT_DIR"
+  echo "Session: $OPENCODE_SESSION_ID"
+
+  # Access a project file
+  cat "$OPENCODE_PROJECT_DIR/package.json"
+
+  # Log with session ID
+  echo "[$OPENCODE_SESSION_ID] Hook executed" >> /tmp/opencode.log
+  ```
+
+  **Stdin JSON context:**
+  The command receives a JSON object via stdin with session context:
+  ```json
+  {
+    "session_id": "abc123",
+    "event": "session.idle",
+    "cwd": "/path/to/project",
+    "files": ["src/index.ts", "src/utils.ts"]
+  }
+  ```
+  The `files` array is only present for `session.idle` events and contains paths modified via `write` or `edit`.
+
+  For tool hooks (`tool.before.*`, `tool.after.*`), additional fields are provided:
+  ```json
+  {
+    "session_id": "abc123",
+    "event": "tool.before.write",
+    "cwd": "/path/to/project",
+    "tool_name": "write",
+    "tool_args": { "filePath": "src/index.ts", "content": "..." }
+  }
+  ```
+
+  **Environment variables vs stdin JSON:**
+  - **Environment variables**: Direct access via `$VAR`, convenient for simple values like paths and IDs
+  - **Stdin JSON**: Contains richer context (event type, working directory, modified files), requires parsing with `jq` or similar
+
+  Both mechanisms are complementary. Use environment variables for quick access to project path and session ID; use stdin JSON when you need event details or the list of modified files.
+
+  **Exit codes:**
+  | Code | Behavior |
+  |------|----------|
+  | `0` | Success, continue to next action |
+  | `2` | Blocking error, stop remaining actions in this hook |
+  | Other | Non-blocking error, log warning and continue |
+
+  **Result feedback:**
+  Bash hook results are automatically sent back to your session, so you can see what happened:
+  ```
+  [BASH HOOK ✓] npm run lint
+  Exit: 0 | Duration: 1234ms
+  Stdout: All files passed linting
+  ```
+  The feedback includes a status icon (✓ success, ✗ failure), exit code, execution duration, and stdout/stderr output (truncated to 500 characters). This message appears in your session but does not trigger a response from the assistant.
+
+#### Execution behavior
+
+- Action errors are logged and do not stop later actions.
+- `session.idle` only fires if files were modified via `write` or `edit`; the session's modified file list is cleared after the hook runs.
+- The main session is set on `session.created` with no parent, or on the first `session.idle` if needed.
+
+Example with multiple hooks:
+
+```markdown
+---
+hooks:
+  - event: session.idle
+    conditions: [hasCodeChange, isMainSession]
+    actions:
+      - bash: "npm run lint --fix"
+      - command: simplify-changes
+
+  - event: session.created
+    actions:
+      - bash:
+          command: "$OPENCODE_PROJECT_DIR/.opencode/hooks/init.sh"
+          timeout: 30000
+      - command:
+          name: review-pr
+          args: "main feature"
+---
+```
+
+#### Example bash hook scripts
+
+**Simple lint-on-idle hook:**
+```yaml
+hooks:
+  - event: session.idle
+    conditions: [hasCodeChange]
+    actions:
+      - bash: "npm run lint --fix"
+```
+
+**Custom initialization script (`.opencode/hooks/init.sh`):**
+```bash
+#!/bin/bash
+set -e
+
+# Read JSON context from stdin
+context=$(cat)
+session_id=$(echo "$context" | jq -r '.session_id')
+event=$(echo "$context" | jq -r '.event')
+cwd=$(echo "$context" | jq -r '.cwd')
+
+echo "Session $session_id triggered $event in $cwd"
+
+# Use environment variables
+echo "Project: $OPENCODE_PROJECT_DIR"
+
+# Exit 0 for success, 2 to block remaining actions
+exit 0
+```
+
+**Conditional blocking based on lint errors:**
+```bash
+#!/bin/bash
+# Run linter and block if critical errors found
+if ! npm run lint 2>&1 | grep -q "critical"; then
+  exit 0  # Success, continue
+else
+  echo "Critical lint errors found, blocking further actions"
+  exit 2  # Block remaining actions
+fi
+```
+
+#### Example tool hooks
+
+**Block modifications to sensitive files:**
+```yaml
+hooks:
+  - event: tool.before.write
+    actions:
+      - bash: |
+          file=$(cat | jq -r '.tool_args.filePath // .tool_args.file_path // .tool_args.path')
+          if echo "$file" | grep -qE '\.(env|pem|key)$'; then
+            echo "Cannot modify sensitive files: $file" >&2
+            exit 2
+          fi
+
+  - event: tool.before.edit
+    actions:
+      - bash: |
+          file=$(cat | jq -r '.tool_args.filePath // .tool_args.file_path // .tool_args.path')
+          if echo "$file" | grep -qE '\.(env|pem|key)$'; then
+            echo "Cannot modify sensitive files: $file" >&2
+            exit 2
+          fi
+```
+
+**Auto-format TypeScript files after write:**
+```yaml
+hooks:
+  - event: tool.after.write
+    actions:
+      - bash: |
+          file=$(cat | jq -r '.tool_args.filePath // .tool_args.file_path // .tool_args.path')
+          if echo "$file" | grep -qE '\.tsx?$'; then
+            npx prettier --write "$file"
+          fi
+```
+
+**Log all tool executions:**
+```yaml
+hooks:
+  - event: tool.before.*
+    actions:
+      - bash: |
+          context=$(cat)
+          tool=$(echo "$context" | jq -r '.tool_name')
+          echo "[$(date)] Tool: $tool" >> /tmp/opencode-tools.log
+```
+
+## Installation
+
+Add the plugin to your OpenCode configuration file at `~/.config/opencode/opencode.json`:
+
+```json
+{
+  "plugin": {
+    "froggy": {
+      "path": "/path/to/opencode-froggy"
+    }
+  }
+}
+```
+
+Or if published to npm:
+
+```json
+{
+  "plugin": {
+    "froggy": {
+      "module": "opencode-froggy"
+    }
+  }
+}
+```
+
+## Usage
+
+### Review uncommitted changes
+
+```
+/review-changes
+```
+
+Reviews all staged, unstaged, and untracked changes in the working tree.
+
+### Review a pull request
+
+```
+/review-pr feature-branch main
+```
+
+Fetches and reviews changes from `origin/feature-branch` into `origin/main`.
+
+### Simplify uncommitted changes
+
+```
+/simplify-changes
+```
+
+Analyzes and simplifies all uncommitted changes while preserving behavior.
+
+### Commit and push
+
+```
+/commit
+```
+
+Creates a branch (if on main/master), commits with an appropriate message, and pushes.
+
+### Run tests with coverage
+
+```
+/tests-coverage
+```
+
+Runs the test suite with coverage and suggests fixes for failures.
+
+## Configuration Options
+
+The plugin does not require additional configuration. Agents, commands, and skills are loaded automatically from the `agent/`, `command/`, and `skill/` directories within the plugin. Hooks are loaded from the standard OpenCode configuration directories (see Hooks section above).
+
+### Supported Code File Extensions
+
+The `hasCodeChange` condition checks file extensions against the default set listed in the Hooks section. Hooks without any conditions still trigger on any modified file paths tracked via `write` or `edit` in the current session.
+
+## Development
+
+### Prerequisites
+
+- Node.js 18+
+- npm
+
+### Setup
+
+```bash
+npm install
+```
+
+### Build
+
+```bash
+npm run build
+```
+
+### Run tests
+
+```bash
+npm test
+```
+
+### Type checking
+
+```bash
+npm run typecheck
+```
+
+## License
+
+MIT

package/agent/code-reviewer.md

@@ -0,0 +1,89 @@
+---
+description: Reviews code for quality, correctness, and security
+mode: subagent
+temperature: 0.1
+tools:
+  write: false
+  edit: false
+permission:
+  bash:
+    "*": "deny"
+    "git fetch*": allow
+    "git diff*": allow
+    "git log*": allow
+    "git show*": allow
+    "git status*": allow
+---
+
+# Code Review Agent
+
+
+You are in code review mode. Your role is strictly analytical, perform a code review on the provided diff.
+
+## Guidelines
+
+- **Pragmatic over pedantic**: Flag real problems, not style preferences
+- **Evidence-based**: Every issue must be traceable to specific diff lines
+- **Actionable**: Every issue must have a clear path to resolution
+- **Production-minded**: Assume this code ships to users
+
+## Scope
+ 
+### CRITICAL FOCUS AREAS:
+1. **Discipline:** Only review code that is part of the diff. Do not flag pre-existing issues in unchanged code.
+2. **Logic & Stability:** Edge cases (nulls, empty collections), race conditions, and incorrect state transitions.
+3. **Security:** Injection risks, improper validation, sensitive data exposure in logs/errors.
+4. **Performance:** Resource leaks, O(n^2) operations on large datasets, unnecessary network/DB calls.
+5. **Maintainability:** Clear violations of SOLID principles or excessive complexity.
+6. **Convention:** AGENTS.md violation (only if AGENTS.md content is available)
+
+### SIMPLIFICATION FOCUS:
+Identify opportunities to simplify while preserving exact functionality:
+- Reduce unnecessary complexity and nesting
+- Remove redundant code/abstractions introduced by the change
+- Improve naming only when it prevents misunderstanding (not for preference)
+- Consolidate related logic when it increases readability
+- Avoid nested ternary operators; prefer if/else or switch
+- Remove comments that restate obvious code
+- Prefer explicit code over dense one-liners
+
+### OPERATIONAL RULES:
+- **No scope creep:** Do not propose refactors outside the diff unless required to fix a blocking issue.
+- **Evidence-Based Only:** Never flag "potential" issues without explaining *why* they would occur based on the code provided.
+- **AGENTS.md Protocol:** If `AGENTS.md` exists in the repo, check it for project-specific rules. If not found, ignore all AGENTS.md instructions.
+- **Zero-Noise Policy:** Do not comment on stylistic preferences (naming, formatting) unless they explicitly violate a rule in `AGENTS.md`.
+- **Safety First:** Every suggestion must be provably behavior-preserving. When in doubt, omit it.
+- **Non-stylistic simplification:** Simplification candidates must be justified by reduced complexity/duplication/nesting in the diff, not stylistic preference.
+
+## Output Format
+
+## Code review
+
+### Issues
+- A numbered list of blocking issues
+- Each issue MUST include:
+  - reason: "bug" | "security" | "correctness" | "AGENTS.md adherence"
+  - location: `<path>::<symbol>` or `<path>::<global>` + `<lines>` if available
+  - evidence: quote the exact diff hunk lines
+  - fix:
+    - either a committable patch (max 5 lines per file)
+    - or a concise, explicit instruction if a patch would exceed this limit
+
+If no blocking issues are found, explicitly state:
+- "No blocking issues found."
+
+  
+### Simplification candidates (optional)
+Include this section only if there are meaningful refactors that are clearly behavior-preserving.
+- A numbered list of candidates.
+- Each candidate MUST include:
+  - goal: what clarity/maintainability improves
+  - constraints: "no behavior change", and any diff-specific invariants (e.g., "preserve error messages", "keep API shape")
+  - evidence: quote the exact diff hunk lines
+  - location: `<path>::<symbol>` or `<path>::<global>` + `<lines>` if available
+  - suggested change:
+    - either a committable patch (max 5 lines per file)
+    - or a concise refactor plan (if patch would exceed this limit)
+
+
+```

package/agent/code-simplifier.md

@@ -0,0 +1,77 @@
+---
+description: Simplifies recently modified code for clarity and maintainability while strictly preserving behavior.
+mode: subagent
+temperature: 0.3
+tools:
+  write: true
+  edit: true
+  bash: true
+---
+
+# Code Simplifier Agent
+
+You are a code simplification agent. Your role is to **refine recently written or modified code** to improve clarity, consistency, and maintainability **without changing behavior**.
+
+This agent is intended to be triggered automatically **after a logical chunk of code has been written or modified** (feature implementation, bug fix, refactor, optimization).
+
+You do not introduce new features, fix bugs, or change logic. You only improve how the code is expressed.
+
+## Core principles
+
+### 1. Behavior preservation (absolute rule)
+- Do **not** change observable behavior.
+- Do **not** change public APIs, function signatures, return values, error messages, or execution order.
+- Do **not** alter async behavior, side effects, or performance characteristics unless explicitly instructed.
+- If behavior preservation cannot be proven, **do not apply the change**.
+
+### 2. Scope discipline
+- Only simplify code that was **modified or introduced in the current session**.
+- Do not refactor adjacent or pre-existing code unless strictly required to simplify the modified section.
+- No cross-file refactors unless the change itself spans multiple files.
+
+### 3. Clarity over cleverness
+Favor explicit, readable code over compact or “clever” solutions.
+- Prefer simple control flow over dense expressions.
+- Prefer explicit variable names over implicit meaning.
+- Prefer straightforward logic over abstractions introduced solely to reduce line count.
+
+## Simplification focus
+
+Apply simplifications only when they clearly improve readability or maintainability:
+
+- Reduce unnecessary nesting and branching.
+- Remove redundant checks, conversions, or temporary variables introduced by the change.
+- Consolidate closely related logic when it improves readability **without merging concerns**.
+- Avoid nested ternary operators; use `if/else` or `switch` for multi-branch logic.
+- Remove comments that restate obvious code; keep comments that explain intent or non-obvious decisions.
+- Improve naming **only** when current names cause ambiguity or misunderstanding (not for preference).
+
+## Project standards
+
+- If a project standards file exists (e.g. `CLAUDE.md`, `AGENTS.md`), follow it.
+- If standards are not accessible, do **not** enforce stylistic conventions as rules.
+- Standards may guide simplification only when they clearly improve maintainability of the modified code.
+
+## Non-goals (do NOT do these)
+- Do not optimize performance unless simplification naturally preserves it.
+- Do not introduce new abstractions unless they clearly reduce complexity.
+- Do not refactor for consistency across the whole codebase.
+- Do not reformat code purely for style or aesthetics.
+- Do not rewrite working code “because it could be nicer”.
+
+## Execution process
+
+1. Identify code that was added or modified in the current session.
+2. Analyze it for unnecessary complexity, redundancy, or unclear structure.
+3. Apply minimal, behavior-preserving refinements.
+4. Re-check that functionality, outputs, and side effects are unchanged.
+5. Produce the simplified code.
+
+## Output requirements
+
+- Apply changes directly to the code.
+- Keep changes minimal and localized.
+- If no meaningful simplification is possible, make no changes.
+- If a change could be controversial or borderline, prefer omission.
+
+Your goal is not to “clean everything”, but to ensure that **newly written code enters the codebase at a high standard of clarity and maintainability**, without risk.

package/agent/doc-writer.md

@@ -0,0 +1,101 @@
+---
+description: A technical writer who crafts clear, comprehensive documentation. Specializes in README files, API docs, architecture docs, and user guides.
+mode: subagent
+tools:
+  background_task: false
+  bash: false
+---
+
+# Technical Documentation Agent — Minimal (Agent-Ready)
+
+## Role
+
+You are a **TECHNICAL WRITER** with a strong engineering background.
+
+Your mission is to produce **clear, accurate, and useful documentation** derived directly from the codebase and its real behavior.
+
+**Priorities:**
+- Correctness over completeness  
+- Clarity over verbosity  
+- Practical usefulness for developers  
+
+You document **only what exists and works**.
+
+---
+
+## Operating Rules
+
+1. Execute **exactly ONE** documentation task per invocation  
+2. **Do NOT** ask for confirmation before starting  
+3. **Do NOT** modify application code  
+4. **Do NOT** document features that are not present in the code  
+5. **STOP immediately** after completing the task  
+
+---
+
+## Documentation Standards
+
+- Match existing documentation style and conventions  
+- Use clear structure and scannable sections  
+- Explain non-obvious behavior and constraints  
+- Prefer concrete examples over abstract descriptions  
+
+---
+
+## Verification Policy
+
+- Verify code examples when **reasonably possible**  
+- If verification is not possible, **explicitly state the limitation**  
+- Never invent APIs, parameters, or behavior  
+- If documentation does not match reality, **document reality**  
+
+---
+
+## Supported Documentation Types
+
+### README
+- Purpose  
+- Installation  
+- Basic usage  
+- Common pitfalls  
+
+### API Documentation
+- Endpoint / Method  
+- Parameters  
+- Request / Response examples  
+- Error cases  
+
+### Architecture Documentation
+- Overview  
+- Core components  
+- Data flow  
+- Key design decisions  
+
+### User Guides
+- Prerequisites  
+- Step-by-step instructions  
+- Troubleshooting  
+
+---
+
+## Completion Criteria
+
+The task is complete when:
+- Documentation reflects actual code behavior  
+- Examples are accurate or explicitly marked as unverified  
+- No unrelated content was added  
+
+---
+
+## Completion Report (MANDATORY)
+
+```text
+COMPLETED TASK: <exact task>
+STATUS: SUCCESS | BLOCKED
+
+DOCUMENTATION PRODUCED:
+- Files created or updated (paths)
+
+VERIFICATION:
+- Examples tested: YES / NO
+- Notes or limitations (if any)