@softspark/ai-toolkit 2.4.1 → 2.6.1

package/scripts/generate_opencode.py

@@ -0,0 +1,117 @@
+#!/usr/bin/env python3
+"""Generate AGENTS.md content for opencode (https://opencode.ai).
+
+opencode reads AGENTS.md using the same convention as OpenAI Codex CLI.
+The generated file is safe for both editors to consume from the same
+project root — each injects into its own marker-wrapped block.
+
+Usage: ./scripts/generate_opencode.py > AGENTS.md
+"""
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+from codex_skill_adapter import codex_skill_description
+from emission import (
+    agents_dir,
+    skills_dir,
+    generate_quality_standards,
+    generate_workflow_guidelines,
+    print_toolkit_end,
+    print_toolkit_start,
+)
+from frontmatter import frontmatter_field
+from paths import RULES_DIR
+
+
+def _emit_agents() -> str:
+    """Emit agents as opencode subagent bullets."""
+    lines: list[str] = []
+    for agent_file in sorted(agents_dir.glob("*.md")):
+        name = frontmatter_field(agent_file, "name")
+        description = frontmatter_field(agent_file, "description")
+        if not name or not description:
+            continue
+        lines.append(f"- **{name}**: {description}")
+    return "\n".join(lines)
+
+
+def _emit_skills() -> str:
+    """Emit user-invocable skills as opencode command bullets.
+
+    Adapts Claude orchestration-only descriptions via the Codex adapter —
+    opencode, like Codex, lacks Claude's Agent/Team/Task primitives so the
+    same translation layer applies.
+    """
+    lines: list[str] = []
+    for skill_dir in sorted(skills_dir.iterdir()):
+        if skill_dir.name.startswith("_"):
+            continue
+        skill_file = skill_dir / "SKILL.md"
+        if not skill_file.is_file():
+            continue
+        name = frontmatter_field(skill_file, "name")
+        description = codex_skill_description(skill_file)
+        if not name or not description:
+            continue
+        lines.append(f"- **{name}**: {description}")
+    return "\n".join(lines)
+
+
+def main() -> None:
+    print_toolkit_start()
+
+    print("# AI Toolkit — opencode Configuration")
+    print()
+    print(
+        "Shared AI development toolkit with specialized subagents,"
+        " opencode-compatible commands, quality hooks, and a safety constitution."
+    )
+    print()
+    print(
+        "opencode reads this file at session start. Subagents are also"
+        " installed under `.opencode/agents/` and slash commands under"
+        " `.opencode/commands/` for native `@` and `/` autocomplete."
+    )
+
+    # Agents
+    print()
+    print("## Available Subagents")
+    print()
+    print("Invoke with `@<name>` in opencode, or delegate via `spawn_agent`:")
+    print()
+    print(_emit_agents())
+
+    # Skills / slash commands
+    print()
+    print("## Available Commands")
+    print()
+    print("Invoke with `/<name>` in opencode. Knowledge-only skills load automatically:")
+    print()
+    print(_emit_skills())
+
+    # Guidelines
+    print()
+    print(generate_quality_standards())
+    print()
+    print(generate_workflow_guidelines())
+
+    print_toolkit_end()
+
+    # Registered custom rules from ~/.softspark/ai-toolkit/rules/
+    if RULES_DIR.is_dir():
+        for rule_file in sorted(RULES_DIR.glob("*.md")):
+            rule_name = rule_file.stem
+            print()
+            print(f"<!-- TOOLKIT:{rule_name} START -->")
+            print("<!-- Auto-injected by ai-toolkit. Re-run to update. -->")
+            print()
+            print(rule_file.read_text(encoding="utf-8").rstrip())
+            print()
+            print(f"<!-- TOOLKIT:{rule_name} END -->")
+
+
+if __name__ == "__main__":
+    main()

package/scripts/generate_opencode_agents.py

@@ -0,0 +1,126 @@
+#!/usr/bin/env python3
+"""Generate .opencode/agents/*.md files for opencode (https://opencode.ai).
+
+Each ai-toolkit agent becomes an opencode subagent with frontmatter:
+
+    ---
+    description: "..."
+    mode: subagent
+    ---
+
+    <body from agent file>
+
+Generated files are prefixed ``ai-toolkit-`` so they never collide with
+user-authored opencode agents and can be cleanly removed on uninstall.
+
+Usage:
+  python3 scripts/generate_opencode_agents.py [target-dir]
+
+Writes files to target-dir/.opencode/agents/.
+"""
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+from emission import agents_dir
+from frontmatter import frontmatter_field
+
+AGENT_PREFIX = "ai-toolkit-"
+
+
+def _agent_body(agent_file: Path) -> str:
+    """Return the markdown body of an agent file (content after frontmatter)."""
+    text = agent_file.read_text(encoding="utf-8")
+    if not text.startswith("---"):
+        return text.strip() + "\n"
+    # Skip first frontmatter block
+    parts = text.split("---", 2)
+    if len(parts) < 3:
+        return text.strip() + "\n"
+    return parts[2].lstrip("\n")
+
+
+def _render_opencode_agent(agent_file: Path) -> str:
+    """Render a single opencode subagent .md file from an ai-toolkit agent."""
+    name = frontmatter_field(agent_file, "name")
+    description = frontmatter_field(agent_file, "description")
+    model = frontmatter_field(agent_file, "model")
+    color = frontmatter_field(agent_file, "color")
+
+    # Escape description for YAML quoted string
+    safe_desc = description.replace('"', "'")
+
+    lines: list[str] = ["---"]
+    lines.append(f'description: "{safe_desc}"')
+    lines.append("mode: subagent")
+    # opencode requires `provider/model-id` for the `model` field. ai-toolkit
+    # only stores a short alias (opus/sonnet/haiku) which is not mappable
+    # without assuming a provider, so we deliberately omit it — opencode falls
+    # back to the user's `default_agent` / top-level `model` config.
+    _ = model  # intentionally unused
+    if color:
+        lines.append(f"color: {color}")
+    lines.append("---")
+    lines.append("")
+    body = _agent_body(agent_file).rstrip()
+    if body:
+        lines.append(body)
+    lines.append("")
+    return "\n".join(lines)
+
+
+def _cleanup_stale(agents_out: Path) -> int:
+    """Remove stale ai-toolkit-* agent files whose source no longer exists."""
+    if not agents_out.is_dir():
+        return 0
+    removed = 0
+    for f in sorted(agents_out.glob(f"{AGENT_PREFIX}*.md")):
+        source_name = f.stem[len(AGENT_PREFIX):]
+        source = agents_dir / f"{source_name}.md"
+        if not source.is_file():
+            f.unlink()
+            removed += 1
+    return removed
+
+
+def generate(
+    target_dir: Path, config_root: Path | None = None
+) -> tuple[int, int]:
+    """Write opencode agent files and return (written, removed_stale).
+
+    By default writes to ``target_dir/.opencode/agents/`` (project-local).
+    Pass ``config_root=~/.config/opencode`` for the global layout, which
+    lives directly under ``agents/`` (no ``.opencode/`` prefix).
+    """
+    base = config_root if config_root is not None else target_dir / ".opencode"
+    agents_out = base / "agents"
+    agents_out.mkdir(parents=True, exist_ok=True)
+
+    written = 0
+    for agent_file in sorted(agents_dir.glob("*.md")):
+        name = frontmatter_field(agent_file, "name")
+        description = frontmatter_field(agent_file, "description")
+        if not name or not description:
+            continue
+        out_path = agents_out / f"{AGENT_PREFIX}{name}.md"
+        out_path.write_text(_render_opencode_agent(agent_file), encoding="utf-8")
+        written += 1
+
+    removed = _cleanup_stale(agents_out)
+    return written, removed
+
+
+def main() -> None:
+    target = Path(sys.argv[1]) if len(sys.argv) > 1 else Path.cwd()
+    written, removed = generate(target)
+    msg = f"Generated: .opencode/agents/ ({written} agents"
+    if removed:
+        msg += f", {removed} stale removed"
+    msg += ")"
+    print(msg)
+
+
+if __name__ == "__main__":
+    main()

package/scripts/generate_opencode_commands.py

@@ -0,0 +1,158 @@
+#!/usr/bin/env python3
+"""Generate .opencode/commands/*.md files for opencode (https://opencode.ai).
+
+User-invocable skills become opencode slash commands. Knowledge skills
+(``user-invocable: false``) are excluded — they load automatically via
+AGENTS.md context instead of `/` invocation.
+
+Generated commands use the required ``template`` frontmatter field.
+Files are prefixed ``ai-toolkit-`` for clean uninstall.
+
+opencode commands: https://opencode.ai/docs/commands/
+"""
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+from codex_skill_adapter import build_codex_skill_text, is_codex_adapted_skill
+from emission import skills_dir
+from frontmatter import frontmatter_field
+
+COMMAND_PREFIX = "ai-toolkit-"
+
+
+def _skill_body(skill_file: Path) -> str:
+    """Return the markdown body of a skill (content after frontmatter).
+
+    For skills that rely on Claude-only orchestration primitives, route
+    through the Codex adapter so `Agent`/`TeamCreate`/`TaskCreate` get
+    rewritten to opencode-compatible delegation guidance. The adapter's
+    output is compatible with opencode's subagent model (``spawn_agent``
+    conventions, plan tracking) because both lack Claude primitives.
+    """
+    if is_codex_adapted_skill(skill_file):
+        adapted = build_codex_skill_text(skill_file)
+        # Strip the adapted frontmatter — we emit our own below
+        parts = adapted.split("---", 2)
+        return parts[2].lstrip("\n") if len(parts) >= 3 else adapted
+
+    text = skill_file.read_text(encoding="utf-8")
+    if not text.startswith("---"):
+        return text
+    parts = text.split("---", 2)
+    return parts[2].lstrip("\n") if len(parts) >= 3 else text
+
+
+def _render_opencode_command(skill_file: Path) -> str:
+    """Render a single opencode command .md file from a user-invocable skill."""
+    name = frontmatter_field(skill_file, "name")
+    description = frontmatter_field(skill_file, "description")
+    agent_field = frontmatter_field(skill_file, "agent")
+    # opencode does NOT read "body" — the prompt is entirely in the `template`
+    # frontmatter field. We embed the SKILL.md body as the template using a
+    # YAML block scalar (``|``) which preserves newlines without escaping.
+    body = _skill_body(skill_file).rstrip()
+
+    lines: list[str] = ["---"]
+    if description:
+        safe_desc = description.replace('"', "'")
+        lines.append(f'description: "{safe_desc}"')
+    if agent_field:
+        # opencode accepts an `agent` frontmatter field pointing at a subagent
+        lines.append(f"agent: {_map_agent_name(agent_field)}")
+    lines.append("template: |")
+    for tpl_line in body.splitlines() or [""]:
+        lines.append(f"  {tpl_line}" if tpl_line else "  ")
+    lines.append("---")
+    lines.append("")
+    return "\n".join(lines)
+
+
+def _map_agent_name(value: str) -> str:
+    """Map ai-toolkit agent names to opencode subagent names.
+
+    Our opencode agents are installed with the ``ai-toolkit-`` prefix by
+    ``generate_opencode_agents.py``, so rewrite here for consistency.
+    """
+    value = value.strip()
+    if not value:
+        return value
+    if value.startswith(COMMAND_PREFIX):
+        return value
+    return f"{COMMAND_PREFIX}{value}"
+
+
+def _is_user_invocable(skill_file: Path) -> bool:
+    """Return True if the skill should be exposed as a `/` command."""
+    invocable = frontmatter_field(skill_file, "user-invocable")
+    if invocable:
+        return invocable.lower() not in ("false", "0", "no")
+    # Absence + `disable-model-invocation: true` = task skill (user-invocable)
+    disable_model = frontmatter_field(skill_file, "disable-model-invocation")
+    if disable_model and disable_model.lower() in ("true", "1", "yes"):
+        return True
+    # Default: NOT invocable — avoids exposing knowledge skills as commands
+    return False
+
+
+def _cleanup_stale(commands_out: Path) -> int:
+    """Remove stale ai-toolkit-* command files whose source no longer exists or is no longer invocable."""
+    if not commands_out.is_dir():
+        return 0
+    removed = 0
+    for f in sorted(commands_out.glob(f"{COMMAND_PREFIX}*.md")):
+        source_name = f.stem[len(COMMAND_PREFIX):]
+        source = skills_dir / source_name / "SKILL.md"
+        if not source.is_file() or not _is_user_invocable(source):
+            f.unlink()
+            removed += 1
+    return removed
+
+
+def generate(
+    target_dir: Path, config_root: Path | None = None
+) -> tuple[int, int]:
+    """Write opencode command files and return (written, removed_stale).
+
+    By default writes to ``target_dir/.opencode/commands/`` (project-local).
+    Pass ``config_root=~/.config/opencode`` for the global layout, which
+    lives directly under ``commands/`` (no ``.opencode/`` prefix).
+    """
+    base = config_root if config_root is not None else target_dir / ".opencode"
+    commands_out = base / "commands"
+    commands_out.mkdir(parents=True, exist_ok=True)
+
+    written = 0
+    for skill_dir in sorted(skills_dir.iterdir()):
+        if skill_dir.name.startswith("_"):
+            continue
+        skill_file = skill_dir / "SKILL.md"
+        if not skill_file.is_file():
+            continue
+        if not _is_user_invocable(skill_file):
+            continue
+        name = frontmatter_field(skill_file, "name")
+        if not name:
+            continue
+        out_path = commands_out / f"{COMMAND_PREFIX}{name}.md"
+        out_path.write_text(_render_opencode_command(skill_file), encoding="utf-8")
+        written += 1
+
+    removed = _cleanup_stale(commands_out)
+    return written, removed
+
+
+def main() -> None:
+    target = Path(sys.argv[1]) if len(sys.argv) > 1 else Path.cwd()
+    written, removed = generate(target)
+    msg = f"Generated: .opencode/commands/ ({written} commands"
+    if removed:
+        msg += f", {removed} stale removed"
+    msg += ")"
+    print(msg)
+
+
+if __name__ == "__main__":
+    main()

package/scripts/generate_opencode_json.py

@@ -0,0 +1,133 @@
+#!/usr/bin/env python3
+"""Merge MCP servers from .mcp.json into opencode.json for opencode.
+
+opencode MCP config: https://opencode.ai/docs/mcp-servers/
+
+Schema per server:
+  Local:  {"type": "local",  "command": [...], "enabled": true, "environment": {...}}
+  Remote: {"type": "remote", "url": "...",      "enabled": true, "headers": {...}}
+
+Our canonical source is .mcp.json (Claude-style) with:
+  {"mcpServers": {"name": {"command": "...", "args": [...], "env": {...}}}}
+  or: {"name": {"url": "..."}} for remote.
+
+We translate into opencode's shape and merge under the ``mcp`` key.
+All non-``mcp`` keys are preserved verbatim — idempotent on re-run.
+
+Usage:
+  python3 scripts/generate_opencode_json.py [target-dir]
+"""
+from __future__ import annotations
+
+import copy
+import json
+import sys
+from pathlib import Path
+
+SCHEMA_URL = "https://opencode.ai/config.json"
+
+
+def _load_json(path: Path) -> dict:
+    if not path.is_file():
+        return {}
+    with open(path, encoding="utf-8") as f:
+        data = json.load(f)
+    if not isinstance(data, dict):
+        raise ValueError(f"{path} must contain a JSON object")
+    return data
+
+
+def _write_json(path: Path, data: dict) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    with open(path, "w", encoding="utf-8") as f:
+        json.dump(data, f, indent=2)
+        f.write("\n")
+
+
+def _translate_server(name: str, server: dict) -> dict:
+    """Translate a Claude-style server entry into opencode's shape."""
+    out: dict = {}
+    if "url" in server:
+        out["type"] = "remote"
+        out["url"] = server["url"]
+        if "headers" in server and isinstance(server["headers"], dict):
+            out["headers"] = copy.deepcopy(server["headers"])
+    elif "command" in server:
+        out["type"] = "local"
+        cmd = server["command"]
+        args = server.get("args") or []
+        if isinstance(cmd, list):
+            out["command"] = list(cmd) + list(args)
+        else:
+            out["command"] = [cmd, *args]
+        env = server.get("env") or server.get("environment")
+        if isinstance(env, dict) and env:
+            out["environment"] = copy.deepcopy(env)
+    else:
+        # Unknown shape — preserve as-is so opencode can report the error
+        out = copy.deepcopy(server)
+        out.setdefault("type", "local")
+
+    out.setdefault("enabled", True)
+    if "timeout" in server:
+        out["timeout"] = server["timeout"]
+    return out
+
+
+def _read_mcp_servers(project_dir: Path) -> dict:
+    """Read canonical .mcp.json and return the servers map.
+
+    Returns {} when no .mcp.json exists (non-fatal).
+    """
+    config = project_dir / ".mcp.json"
+    if not config.is_file():
+        return {}
+    data = _load_json(config)
+    servers = data.get("mcpServers", {})
+    if not isinstance(servers, dict):
+        return {}
+    return servers
+
+
+def merge_into_opencode_json(
+    target_dir: Path, output_path: Path | None = None
+) -> tuple[Path, int]:
+    """Merge .mcp.json servers into an opencode.json file.
+
+    Reads ``target_dir/.mcp.json`` as the canonical source. By default
+    writes to ``target_dir/opencode.json`` (project-local). Pass
+    ``output_path=~/.config/opencode/opencode.json`` for the global layout.
+
+    Returns (path, server_count). If no .mcp.json exists, still ensures
+    the output has the $schema key set (creates a minimal file).
+    """
+    servers = _read_mcp_servers(target_dir)
+    path = output_path if output_path is not None else target_dir / "opencode.json"
+    data = _load_json(path)
+    data.setdefault("$schema", SCHEMA_URL)
+
+    if servers:
+        bucket = data.setdefault("mcp", {})
+        if not isinstance(bucket, dict):
+            raise ValueError(f"{path} has invalid 'mcp' data (expected object)")
+        for name, entry in servers.items():
+            if not isinstance(entry, dict):
+                continue
+            bucket[name] = _translate_server(name, entry)
+
+    _write_json(path, data)
+    return path, len(servers)
+
+
+def main() -> None:
+    target = Path(sys.argv[1]) if len(sys.argv) > 1 else Path.cwd()
+    path, count = merge_into_opencode_json(target)
+    rel = path.relative_to(target) if path.is_relative_to(target) else path
+    if count:
+        print(f"Generated: {rel} ({count} MCP server(s) merged)")
+    else:
+        print(f"Generated: {rel} (no MCP servers; .mcp.json not found)")
+
+
+if __name__ == "__main__":
+    main()