@softspark/ai-toolkit 2.4.1 → 2.6.1

package/scripts/generate_opencode_plugin.py

@@ -0,0 +1,169 @@
+#!/usr/bin/env python3
+"""Generate the ai-toolkit opencode plugin at ``.opencode/plugins/ai-toolkit-hooks.js``.
+
+opencode plugins are JS/TS modules with a NAMED export that receive a
+context (``$``, ``project``, ``client``, ``directory``, ``worktree``) and
+return a hooks object. Docs: https://opencode.ai/docs/plugins/
+
+This generator emits a single-file plugin that bridges ai-toolkit's
+shared Bash hooks (``$HOME/.softspark/ai-toolkit/hooks/*.sh``) to
+opencode lifecycle events. Coverage map:
+
+  opencode event              -> ai-toolkit Bash hook(s)
+  ---------------------------------------------------------------
+  session.created             -> session-start.sh + session-context.sh + mcp-health.sh
+  session.compacted           -> pre-compact.sh + pre-compact-save.sh
+  session.deleted             -> session-end.sh + save-session.sh
+  message.updated             -> user-prompt-submit.sh + track-usage.sh
+  message.part.updated        -> user-prompt-submit.sh + track-usage.sh
+  tool.execute.before (bash)  -> guard-destructive.sh + commit-quality.sh
+  tool.execute.after          -> post-tool-use.sh
+  permission.asked            -> guard-destructive.sh
+  command.executed            -> post-tool-use.sh
+
+Security: hooks are invoked via ``$`` with the script path bound to a
+JS constant (no opencode-payload interpolation into the command). Event
+payloads are passed on stdin as JSON. Non-zero exit codes are logged to
+stderr; ``exit 2`` is preserved as a block signal for PreToolUse guards.
+
+Usage:
+  python3 scripts/generate_opencode_plugin.py [target-dir] [--config-root PATH]
+"""
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+PLUGIN_BODY = r"""// ai-toolkit opencode plugin — bridges shared Bash hooks to opencode events.
+// Auto-generated by ai-toolkit. Do not edit by hand; re-run to update:
+//   ai-toolkit opencode-plugin
+// Docs: https://opencode.ai/docs/plugins/
+//
+// Hooks live at $HOME/.softspark/ai-toolkit/hooks/*.sh and are shared with
+// Claude Code and Codex CLI. This plugin invokes them via Bun's `$` shell
+// with the script path bound as a JS constant — no string interpolation of
+// opencode event payloads into the shell, so event data cannot inject
+// shell metacharacters. Payloads are passed on stdin as JSON.
+
+const HOOKS_DIR = `${process.env.HOME}/.softspark/ai-toolkit/hooks`;
+
+/** Invoke a Bash hook with a JSON payload on stdin. */
+async function runHook($, script, payload) {
+  const scriptPath = `${HOOKS_DIR}/${script}`;
+  try {
+    const input = JSON.stringify(payload ?? {});
+    const proc = $`bash ${scriptPath}`.env({
+      ...process.env,
+      AI_TOOLKIT_EVENT: payload?.event || "unknown",
+    });
+    proc.stdin.write(input);
+    proc.stdin.end();
+    const result = await proc.quiet().nothrow();
+    if (result.exitCode !== 0 && result.exitCode !== 2) {
+      // Exit 2 is the toolkit's "block" signal — pass through to opencode as a guard.
+      process.stderr.write(
+        `[ai-toolkit] ${script} exited ${result.exitCode}\n${result.stderr.toString()}`
+      );
+    }
+    return result.exitCode;
+  } catch (err) {
+    process.stderr.write(`[ai-toolkit] failed to run ${script}: ${err.message}\n`);
+    return 0;
+  }
+}
+
+export const AiToolkitHooks = async ({ $, project, directory, worktree }) => ({
+  event: async ({ event }) => {
+    const payload = { event: event.type, project, directory, worktree };
+    switch (event.type) {
+      case "session.created":
+        await runHook($, "session-start.sh", payload);
+        await runHook($, "session-context.sh", payload);
+        await runHook($, "mcp-health.sh", payload);
+        break;
+      case "session.compacted":
+        await runHook($, "pre-compact.sh", payload);
+        await runHook($, "pre-compact-save.sh", payload);
+        break;
+      case "session.deleted":
+        await runHook($, "session-end.sh", payload);
+        await runHook($, "save-session.sh", payload);
+        break;
+      case "message.updated":
+      case "message.part.updated":
+        await runHook($, "user-prompt-submit.sh", payload);
+        await runHook($, "track-usage.sh", payload);
+        break;
+      case "permission.asked":
+        await runHook($, "guard-destructive.sh", payload);
+        break;
+      case "command.executed":
+        await runHook($, "post-tool-use.sh", payload);
+        break;
+    }
+  },
+
+  "tool.execute.before": async (input, output) => {
+    const payload = {
+      event: "tool.execute.before",
+      tool: input?.tool,
+      args: output?.args,
+      project,
+    };
+    if (input?.tool === "bash") {
+      await runHook($, "guard-destructive.sh", payload);
+      await runHook($, "commit-quality.sh", payload);
+    }
+  },
+
+  "tool.execute.after": async (input, output) => {
+    const payload = {
+      event: "tool.execute.after",
+      tool: input?.tool,
+      result: output,
+      project,
+    };
+    await runHook($, "post-tool-use.sh", payload);
+  },
+});
+"""
+
+
+def generate(target_dir: Path, config_root: Path | None = None) -> Path:
+    """Write the opencode plugin file and return its path.
+
+    ``config_root`` lets the caller override the default project-local
+    layout. When omitted, writes to ``target_dir/.opencode/plugins/``.
+    Pass ``config_root=~/.config/opencode`` to lay down the plugin
+    globally at ``~/.config/opencode/plugins/ai-toolkit-hooks.js``.
+    """
+    base = config_root if config_root is not None else target_dir / ".opencode"
+    plugins_dir = base / "plugins"
+    plugins_dir.mkdir(parents=True, exist_ok=True)
+    path = plugins_dir / "ai-toolkit-hooks.js"
+    path.write_text(PLUGIN_BODY, encoding="utf-8")
+    return path
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Generate opencode plugin")
+    parser.add_argument("target", nargs="?", default=".", help="Target directory")
+    parser.add_argument(
+        "--config-root",
+        type=Path,
+        default=None,
+        help="Override base (e.g. ~/.config/opencode for global install).",
+    )
+    args = parser.parse_args()
+    target = Path(args.target)
+    path = generate(target, config_root=args.config_root)
+    try:
+        rel = path.relative_to(target)
+    except ValueError:
+        rel = path
+    print(f"Generated: {rel}")
+
+
+if __name__ == "__main__":
+    main()

package/scripts/install_steps/ai_tools.py

@@ -92,6 +92,14 @@ def install_ai_tools(target_dir: Path, rules_dir: Path,
             _install_codex_global(target_dir, rules_dir)
         installed.append("codex")
 
+    if "opencode" in eds:
+        if dry_run:
+            print("  Would inject: ~/.config/opencode/{AGENTS.md, agents/, "
+                  "commands/, plugins/ai-toolkit-hooks.js, opencode.json}")
+        else:
+            _install_opencode_global(target_dir, rules_dir)
+        installed.append("opencode")
+
     print()
     print(f"  Available: {', '.join(GLOBAL_CAPABLE_EDITORS)}")
     print("  Note: Copilot, Cline, Roo Code, Aider, Antigravity have no global config -- use 'ai-toolkit install --local' per project")
@@ -128,6 +136,51 @@ def _install_codex_global(target_dir: Path, rules_dir: Path) -> None:
     _install_codex_skills(target_dir)
 
 
+def _install_opencode_global(target_dir: Path, rules_dir: Path) -> None:
+    """Install opencode at the global level (~/.config/opencode/).
+
+    Creates:
+      - ~/.config/opencode/AGENTS.md (marker injection with rules)
+      - ~/.config/opencode/agents/ai-toolkit-*.md (subagents)
+      - ~/.config/opencode/commands/ai-toolkit-*.md (slash commands)
+      - ~/.config/opencode/plugins/ai-toolkit-hooks.js (hook bridge)
+      - ~/.config/opencode/opencode.json (MCP merge, preserves user keys)
+    """
+    opencode_home = target_dir / ".config" / "opencode"
+    inject_with_rules(
+        "generate_opencode.py",
+        opencode_home / "AGENTS.md",
+        rules_dir,
+    )
+
+    from generate_opencode_agents import generate as gen_opencode_agents
+    written, removed = gen_opencode_agents(target_dir, config_root=opencode_home)
+    msg = f"  Created: ~/.config/opencode/agents/ ({written} agents"
+    if removed:
+        msg += f", {removed} stale removed"
+    msg += ")"
+    print(msg)
+
+    from generate_opencode_commands import generate as gen_opencode_commands
+    written, removed = gen_opencode_commands(target_dir, config_root=opencode_home)
+    msg = f"  Created: ~/.config/opencode/commands/ ({written} commands"
+    if removed:
+        msg += f", {removed} stale removed"
+    msg += ")"
+    print(msg)
+
+    from generate_opencode_plugin import generate as gen_opencode_plugin
+    gen_opencode_plugin(target_dir, config_root=opencode_home)
+    print("  Created: ~/.config/opencode/plugins/ai-toolkit-hooks.js")
+
+    from generate_opencode_json import merge_into_opencode_json
+    _, count = merge_into_opencode_json(
+        target_dir, output_path=opencode_home / "opencode.json"
+    )
+    suffix = f" ({count} MCP server(s) merged)" if count else " (no MCP servers)"
+    print(f"  Created: ~/.config/opencode/opencode.json{suffix}")
+
+
 def inject_with_rules(
     generator_script: str,
     target_file: Path,
@@ -194,7 +247,7 @@ def run_script(script_name: str, *args: str, capture: bool = False) -> str:
 # All known editor identifiers for --editors flag
 ALL_EDITORS = [
     "copilot", "cursor", "windsurf", "cline", "roo",
-    "aider", "augment", "antigravity", "codex",
+    "aider", "augment", "antigravity", "codex", "gemini", "opencode",
 ]
 
 # Map of project files/dirs → editor names for auto-detection
@@ -213,7 +266,15 @@ _EDITOR_MARKERS: dict[str, str] = {
     ".agent/rules": "antigravity",
     ".agents/skills": "codex",
     ".codex": "codex",
+    # NOTE: AGENTS.md alone is ambiguous (Codex + opencode both read it);
+    # prefer the dedicated .opencode/ and opencode.json markers when
+    # disambiguating. If only AGENTS.md is present, Codex takes precedence
+    # to preserve v2.4.x behavior.
     "AGENTS.md": "codex",
+    "opencode.json": "opencode",
+    ".opencode": "opencode",
+    ".opencode/agents": "opencode",
+    ".opencode/commands": "opencode",
 }
 
 
@@ -485,6 +546,7 @@ def _install_local_dry_run(reset: bool, editors: list[str] | None = None) -> Non
         "aider":        "  Would generate: .aider.conf.yml + CONVENTIONS.md",
         "augment":      "  Would generate: .augment/rules/ai-toolkit-*.md",
         "antigravity":  "  Would generate: .agent/rules/ + .agent/workflows/",
+        "opencode":     "  Would generate: AGENTS.md + .opencode/{agents,commands,plugins}/ + opencode.json",
     }
     for ed, msg in _EDITOR_DRY_RUN.items():
         if ed in eds:
@@ -511,6 +573,24 @@ def _reset_local_configs(cwd: Path) -> None:
             p.unlink()
             print(f"  Removed: {rel}")
 
+    # opencode: remove only ai-toolkit-prefixed generated files so the
+    # user's own .opencode/agents/ or commands/ entries are preserved.
+    # opencode.json is left alone — it may contain user MCP servers and other
+    # project settings; reinstall re-merges our MCP entries idempotently.
+    opencode_plugin = cwd / ".opencode" / "plugins" / "ai-toolkit-hooks.js"
+    if opencode_plugin.is_file():
+        opencode_plugin.unlink()
+        print("  Removed: .opencode/plugins/ai-toolkit-hooks.js")
+    for sub in ("agents", "commands"):
+        sub_dir = cwd / ".opencode" / sub
+        if sub_dir.is_dir():
+            removed_any = False
+            for f in sorted(sub_dir.glob("ai-toolkit-*.md")):
+                f.unlink()
+                removed_any = True
+            if removed_any:
+                print(f"  Removed: .opencode/{sub}/ai-toolkit-*.md")
+
 
 def _create_local_claude_md(cwd: Path, reset: bool) -> None:
     claude_local = cwd / "CLAUDE.md"
@@ -699,6 +779,42 @@ def _create_local_ai_tool_configs(cwd: Path, rules_dir: Path,
         # .agents/skills/ — filtered symlinks (Codex-compatible skills only)
         _install_codex_skills(cwd)
 
+    if "opencode" in eds:
+        # AGENTS.md — shared with Codex via marker injection (opencode reads same file)
+        # Use a dedicated section tag so Codex and opencode don't clobber each other.
+        inject_with_rules(
+            "generate_opencode.py",
+            cwd / "AGENTS.md",
+            rules_dir,
+        )
+        # .opencode/agents/ — native subagents
+        from generate_opencode_agents import generate as gen_opencode_agents
+        written, removed = gen_opencode_agents(cwd)
+        msg = f"  Created: .opencode/agents/ ({written} agents"
+        if removed:
+            msg += f", {removed} stale removed"
+        msg += ")"
+        print(msg)
+        # .opencode/commands/ — native slash commands
+        from generate_opencode_commands import generate as gen_opencode_commands
+        written, removed = gen_opencode_commands(cwd)
+        msg = f"  Created: .opencode/commands/ ({written} commands"
+        if removed:
+            msg += f", {removed} stale removed"
+        msg += ")"
+        print(msg)
+        # .opencode/plugins/ai-toolkit-hooks.js — lifecycle hook bridge
+        from generate_opencode_plugin import generate as gen_opencode_plugin
+        gen_opencode_plugin(cwd)
+        print("  Created: .opencode/plugins/ai-toolkit-hooks.js")
+        # opencode.json — merge MCP servers from .mcp.json (preserves user keys)
+        from generate_opencode_json import merge_into_opencode_json
+        _, mcp_count = merge_into_opencode_json(cwd)
+        if mcp_count:
+            print(f"  Updated: opencode.json ({mcp_count} MCP server(s) from .mcp.json)")
+        else:
+            print("  Updated: opencode.json ($schema set)")
+
     synced_paths = sync_project_mcp_to_editors(cwd, sorted(eds))
     for path in synced_paths:
         rel = path.relative_to(cwd)

package/scripts/install_steps/install_state.py

@@ -89,7 +89,7 @@ def remove_mcp_template(name: str) -> None:
 DEFAULT_GLOBAL_EDITORS: list[str] = []
 
 # All editors that support global install (opt-in via --editors)
-GLOBAL_CAPABLE_EDITORS = ["augment", "codex", "cursor", "gemini", "windsurf"]
+GLOBAL_CAPABLE_EDITORS = ["augment", "codex", "cursor", "gemini", "opencode", "windsurf"]
 
 
 def get_global_editors() -> list[str]:

package/scripts/plugin.py

@@ -912,7 +912,7 @@ def cmd_status(editors: list[str]) -> None:
                     print(f"    Hooks: {', '.join(h.name for h in hooks)}")
             elif editor == "codex":
                 rules_dir = CODEX_ROOT / ".agents" / "rules"
-                rule_files = sorted(rules_dir.glob(f"ai-toolkit-plugin-{name}-*.md")) if rules_dir.is_dir() else []
+                rule_files = sorted(rules_dir.glob(f"plugin-{name}-*.md")) if rules_dir.is_dir() else []
                 if rule_files:
                     print(f"    Rules: {', '.join(f.name for f in rule_files)}")
             if name == "memory-pack":