@softspark/ai-toolkit 2.12.0 → 3.0.0

package/scripts/generate_gemini_commands.py

@@ -0,0 +1,158 @@
+#!/usr/bin/env python3
+"""Generate ``.gemini/commands/ai-toolkit-*.toml`` files for Gemini CLI.
+
+User-invocable skills become Gemini custom slash commands. Knowledge skills
+(``user-invocable: false``) are excluded — they load automatically via
+``GEMINI.md`` context instead of ``/`` invocation.
+
+Per github.com/google-gemini/gemini-cli, Gemini custom commands are TOML
+files with at minimum:
+
+    description = "<one-line summary shown in the palette>"
+    prompt = \"\"\"
+    <multi-line prompt body>
+    \"\"\"
+
+Argument substitution uses the ``{{args}}`` placeholder. We translate the
+Claude Code ``$ARGUMENTS`` token that appears in some skill bodies into
+``{{args}}`` so the same skill works across both runtimes.
+
+Files are prefixed ``ai-toolkit-`` so install/uninstall can identify ours
+without touching user-authored Gemini commands.
+
+Usage:
+  python3 scripts/generate_gemini_commands.py [target-dir]
+
+Writes files to ``target-dir/.gemini/commands/``.
+"""
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+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)."""
+    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 _translate_placeholders(body: str) -> str:
+    """Rewrite Claude-style ``$ARGUMENTS`` placeholders to Gemini ``{{args}}``."""
+    return body.replace("$ARGUMENTS", "{{args}}")
+
+
+def _render_gemini_command(skill_file: Path) -> str:
+    """Render a single Gemini TOML command file from a user-invocable skill.
+
+    Bodies are emitted as TOML multi-line **literal** strings (``'''...'''``)
+    so embedded regex such as ``\\s``, ``\\d``, ``\\n`` are passed through
+    verbatim. Literal strings accept no escape sequences, which is exactly
+    what we want for prompt fidelity.
+    """
+    description = frontmatter_field(skill_file, "description")
+    body = _skill_body(skill_file).rstrip()
+    body = _translate_placeholders(body)
+
+    if "'''" in body:
+        raise ValueError(
+            f"{skill_file}: body contains ''' which would terminate a TOML "
+            f"multi-line literal string. Rewrite the skill to avoid that "
+            f"sequence or switch this generator to basic strings for it."
+        )
+
+    safe_desc = (description or "").replace('"', '\\"')
+
+    lines: list[str] = []
+    lines.append(f'description = "{safe_desc}"')
+    lines.append("prompt = '''")
+    if body:
+        lines.append(body)
+    lines.append("'''")
+    lines.append("")
+    return "\n".join(lines)
+
+
+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")
+    disable_model = frontmatter_field(skill_file, "disable-model-invocation")
+    if disable_model and disable_model.lower() in ("true", "1", "yes"):
+        return True
+    return False
+
+
+def _cleanup_stale(commands_out: Path) -> int:
+    """Remove stale ai-toolkit-* command files whose source no longer exists.
+
+    Also removes commands whose source skill is no longer user-invocable.
+    Only touches files prefixed ``ai-toolkit-`` so user-authored commands
+    are preserved.
+    """
+    if not commands_out.is_dir():
+        return 0
+    removed = 0
+    for f in sorted(commands_out.glob(f"{COMMAND_PREFIX}*.toml")):
+        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 Gemini TOML command files and return (written, removed_stale).
+
+    By default writes to ``target_dir/.gemini/commands/`` (project-local).
+    Pass ``config_root=~/.gemini`` for the global layout.
+    """
+    base = config_root if config_root is not None else target_dir / ".gemini"
+    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}.toml"
+        out_path.write_text(_render_gemini_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: .gemini/commands/ ({written} commands"
+    if removed:
+        msg += f", {removed} stale removed"
+    msg += ")"
+    print(msg)
+
+
+if __name__ == "__main__":
+    main()

package/scripts/generate_gemini_hooks.py

@@ -0,0 +1,159 @@
+#!/usr/bin/env python3
+"""Generate .gemini/settings.json hooks block for Gemini CLI.
+
+Merges ai-toolkit hook entries into `<target>/.gemini/settings.json`. User
+settings (everything outside the `hooks` key or any hook entry not tagged
+`_source: ai-toolkit`) are preserved byte-for-byte.
+
+Gemini CLI hook events (per docs/hooks/reference.md, google-gemini/gemini-cli):
+    BeforeTool, AfterTool, BeforeAgent, AfterAgent, BeforeModel,
+    BeforeToolSelection, AfterModel, SessionStart, SessionEnd,
+    Notification, PreCompress
+
+The ai-toolkit registry nominally includes `Stop`, but the upstream Gemini CLI
+does not implement it; `AfterAgent` is the closest equivalent (fires once per
+turn after the model's final response) and we wire our `save-session.sh` /
+`quality-check.sh` there.
+
+Hook scripts are shared with Claude Code / Codex and live under
+`~/.softspark/ai-toolkit/hooks/`. This generator does NOT duplicate shell code.
+
+Usage:
+    python3 scripts/generate_gemini_hooks.py [target-dir]
+
+Writes `<target-dir>/.gemini/settings.json` (merge-safe, idempotent).
+"""
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+
+HOOKS_PREFIX = '"$HOME/.softspark/ai-toolkit/hooks/'
+SOURCE_TAG = "ai-toolkit"
+
+# Event -> list of (matcher, script) pairs. Matcher semantics:
+#   - Tool events (BeforeTool/AfterTool): regex over tool_name
+#     (built-in tools: run_shell_command, write_file, edit, replace, read_file...)
+#   - Agent/Model/Session events: matcher is ignored upstream but harmless to omit
+GEMINI_HOOKS: dict[str, list[tuple[str, str]]] = {
+    "SessionStart": [
+        ("", "session-start.sh"),
+        ("", "mcp-health.sh"),
+        ("", "session-context.sh"),
+    ],
+    "BeforeTool": [
+        # run_shell_command covers Bash-equivalent destructive patterns
+        ("run_shell_command", "guard-destructive.sh"),
+        ("run_shell_command", "commit-quality.sh"),
+        # File-touching tools — guard paths + config
+        ("write_file|edit|replace|read_file", "guard-path.sh"),
+        ("write_file|edit|replace", "guard-config.sh"),
+    ],
+    "AfterTool": [
+        ("write_file|edit|replace", "post-tool-use.sh"),
+        ("run_shell_command|write_file|edit|replace", "governance-capture.sh"),
+    ],
+    "BeforeAgent": [
+        ("", "user-prompt-submit.sh"),
+        ("", "track-usage.sh"),
+    ],
+    "AfterAgent": [
+        # Closest equivalent to Claude's Stop event. Gemini has no native Stop.
+        ("", "quality-check.sh"),
+        ("", "save-session.sh"),
+    ],
+    "BeforeModel": [
+        # Light-weight observability slot. Reuses the session-context probe.
+        ("", "session-context.sh"),
+    ],
+    "SessionEnd": [
+        ("", "session-end.sh"),
+    ],
+}
+
+
+def build_hook_entry(matcher: str, script: str) -> dict:
+    """Build a single Gemini hook entry (merge-safe shape)."""
+    entry: dict = {
+        "_source": SOURCE_TAG,
+        "hooks": [
+            {
+                "type": "command",
+                "command": f"{HOOKS_PREFIX}{script}\"",
+            }
+        ],
+    }
+    if matcher:
+        entry["matcher"] = matcher
+    return entry
+
+
+def build_toolkit_hooks() -> dict[str, list[dict]]:
+    """Build the toolkit's hook entries grouped by event."""
+    result: dict[str, list[dict]] = {}
+    for event, entries in GEMINI_HOOKS.items():
+        result[event] = [build_hook_entry(m, s) for m, s in entries]
+    return result
+
+
+def _is_toolkit_entry(entry: dict) -> bool:
+    return isinstance(entry, dict) and entry.get("_source") == SOURCE_TAG
+
+
+def strip_toolkit_hooks(hooks: dict) -> dict:
+    """Drop any existing ai-toolkit-tagged entries, keep everything else."""
+    kept: dict = {}
+    for event, entries in hooks.items():
+        if not isinstance(entries, list):
+            kept[event] = entries
+            continue
+        survivors = [e for e in entries if not _is_toolkit_entry(e)]
+        if survivors:
+            kept[event] = survivors
+    return kept
+
+
+def merge_hooks(existing_hooks: dict, toolkit_hooks: dict) -> dict:
+    """Strip old toolkit entries, then append the current batch."""
+    merged = strip_toolkit_hooks(existing_hooks)
+    for event, entries in toolkit_hooks.items():
+        merged.setdefault(event, []).extend(entries)
+    return merged
+
+
+def generate(target_dir: Path) -> Path:
+    """Write `<target_dir>/.gemini/settings.json` and return its path."""
+    gemini_dir = target_dir / ".gemini"
+    gemini_dir.mkdir(parents=True, exist_ok=True)
+    settings_path = gemini_dir / "settings.json"
+
+    settings: dict = {}
+    if settings_path.is_file():
+        try:
+            with open(settings_path, encoding="utf-8") as f:
+                settings = json.load(f)
+            if not isinstance(settings, dict):
+                settings = {}
+        except (json.JSONDecodeError, OSError):
+            settings = {}
+
+    existing_hooks = settings.get("hooks") if isinstance(settings.get("hooks"), dict) else {}
+    settings["hooks"] = merge_hooks(existing_hooks or {}, build_toolkit_hooks())
+
+    with open(settings_path, "w", encoding="utf-8") as f:
+        json.dump(settings, f, indent=4, ensure_ascii=False, sort_keys=True)
+        f.write("\n")
+    return settings_path
+
+
+def main() -> None:
+    target = Path(sys.argv[1]) if len(sys.argv) > 1 else Path.cwd()
+    path = generate(target)
+    total = sum(len(v) for v in GEMINI_HOOKS.values())
+    print(f"Generated: {path.relative_to(target) if path.is_relative_to(target) else path} "
+          f"({total} hooks across {len(GEMINI_HOOKS)} events)")
+
+
+if __name__ == "__main__":
+    main()

package/scripts/generate_gemini_skills.py

@@ -0,0 +1,98 @@
+#!/usr/bin/env python3
+"""Generate a Gemini CLI skill pointer under ``.gemini/skills/``.
+
+Gemini supports the Agent Skills standard via
+``.gemini/skills/<skill-name>/SKILL.md``. Rather than duplicating the full
+ai-toolkit skill catalogue into Gemini's skills directory (which would
+produce 99 near-duplicate files on every install), we emit a single
+**pointer skill** that teaches Gemini to resolve real skills from the
+canonical Claude Code locations:
+
+  * ``.claude/skills/<name>/SKILL.md`` (project-local install)
+  * ``~/.claude/skills/<name>/SKILL.md`` (global install)
+
+This mirrors the pattern used by ``generate_antigravity.py``.
+
+Usage:
+  python3 scripts/generate_gemini_skills.py [target-dir]
+
+Writes ``<target-dir>/.gemini/skills/ai-toolkit-skill-catalogue/SKILL.md``.
+"""
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+from emission import emit_skills_bullets
+
+
+# ---------------------------------------------------------------------------
+# Skill pointer — a single SKILL.md that directs Gemini to our catalogue
+# ---------------------------------------------------------------------------
+
+POINTER_SKILL_NAME = "ai-toolkit-skill-catalogue"
+
+
+def _pointer_skill_md() -> str:
+    """Build the SKILL.md body for the Gemini pointer skill."""
+    body = (
+        "# AI Toolkit Skill Catalogue\n\n"
+        "This workspace uses the ai-toolkit. Real skills are installed "
+        "alongside Claude Code at `.claude/skills/` (project install) or "
+        "`~/.claude/skills/` (global install). If the ai-toolkit installer "
+        "has run, every skill below already exists as an agent-invocable "
+        "SKILL.md on disk.\n\n"
+        "## When to use this skill\n\n"
+        "- You are asked to run a task that maps to one of the catalogued "
+        "skills below.\n"
+        "- You want to discover which skills the user has installed before "
+        "reinventing the wheel.\n\n"
+        "## How to invoke a catalogue entry\n\n"
+        "1. Match the user's task to a skill name in the catalogue.\n"
+        "2. Read the skill's SKILL.md from `.claude/skills/<name>/SKILL.md` "
+        "or `~/.claude/skills/<name>/SKILL.md` (whichever exists).\n"
+        "3. Follow its Rules, Gotchas, and When NOT to Use sections.\n\n"
+        "## Catalogue (installed skills)\n\n"
+        f"{emit_skills_bullets()}\n"
+    )
+    return (
+        "---\n"
+        f"name: {POINTER_SKILL_NAME}\n"
+        "description: Index of ai-toolkit skills installed at .claude/skills/"
+        " or ~/.claude/skills/. Read this first when the user's request "
+        "matches a named skill.\n"
+        "---\n"
+        f"{body}"
+    )
+
+
+def _write_skill_pointer(target_dir: Path) -> None:
+    """Write the pointer SKILL.md under .gemini/skills/<name>/."""
+    skill_dir = target_dir / ".gemini" / "skills" / POINTER_SKILL_NAME
+    skill_dir.mkdir(parents=True, exist_ok=True)
+    (skill_dir / "SKILL.md").write_text(_pointer_skill_md(), encoding="utf-8")
+    print(f"  Generated: .gemini/skills/{POINTER_SKILL_NAME}/SKILL.md")
+
+
+# ---------------------------------------------------------------------------
+# Main
+# ---------------------------------------------------------------------------
+
+def generate(target_dir: Path, *, emit_skill_pointer: bool = True) -> None:
+    """Write ``.gemini/skills/ai-toolkit-skill-catalogue/SKILL.md``.
+
+    ``emit_skill_pointer`` controls whether the pointer SKILL.md is written.
+    Set to ``False`` to leave Gemini's skills directory untouched.
+    """
+    if emit_skill_pointer:
+        _write_skill_pointer(target_dir)
+
+
+def main() -> None:
+    target = Path(sys.argv[1]) if len(sys.argv) > 1 else Path.cwd()
+    generate(target)
+
+
+if __name__ == "__main__":
+    main()

package/scripts/generate_roo_modes.py

@@ -1,5 +1,23 @@
 #!/usr/bin/env python3
-"""Generate .roomodes JSON from app/agents/*.md.
+"""Generate ``.roomodes`` JSON from ``app/agents/*.md``.
+
+Roo Code's custom mode format supports these top-level properties:
+
+  * ``slug`` — internal identifier, used for mode-specific rule dirs
+  * ``name`` — display name shown in the UI
+  * ``description`` — short one-line summary shown below the name in the
+    mode selector (required for the redesigned selector)
+  * ``roleDefinition`` — detailed expertise text placed at the start of
+    the system prompt
+  * ``whenToUse`` — optional guidance consumed by the Orchestrator mode
+    and mode-switch tool to pick the right mode for a given task
+  * ``groups`` — list of allowed tool groups
+
+Previously this script emitted only ``slug``, ``name``, ``roleDefinition``,
+and ``groups``. Per the Roo Code docs (features/custom-modes), both
+``description`` and ``whenToUse`` are now first-class fields: the
+description field is what the UI renders under the mode name, while
+``roleDefinition`` should carry the deeper persona text.
 
 Usage: ./scripts/generate_roo_modes.py > .roomodes
 """
@@ -43,6 +61,25 @@ def _read_body(filepath: Path) -> str:
     return "\n".join(lines)
 
 
+def _first_sentence(description: str, *, limit: int = 140) -> str:
+    """Extract a short summary for the ``whenToUse`` hint.
+
+    Roo's orchestrator uses ``whenToUse`` to pick between modes, so a
+    terse action-oriented sentence is more useful than the full agent
+    description. Falls back to the first ~140 chars if no period is
+    found before the limit.
+    """
+    if not description:
+        return ""
+    text = description.strip().replace("\n", " ")
+    dot = text.find(". ")
+    if 0 < dot <= limit:
+        return text[:dot + 1]
+    if len(text) <= limit:
+        return text
+    return text[:limit].rsplit(" ", 1)[0] + "..."
+
+
 def main() -> None:
     first = True
     sys.stdout.write('{\n  "customModes": [\n')
@@ -60,6 +97,7 @@ def main() -> None:
 
         role_def = _read_body(agent_file)
         role_text = f"{description}\n\n{role_def}"
+        when_to_use = _first_sentence(description)
 
         if first:
             first = False
@@ -69,7 +107,10 @@ def main() -> None:
         sys.stdout.write("    {\n")
         sys.stdout.write(f'      "slug": "{_json_escape(slug)}",\n')
         sys.stdout.write(f'      "name": "{_json_escape(name)}",\n')
+        sys.stdout.write(f'      "description": "{_json_escape(description)}",\n')
         sys.stdout.write(f'      "roleDefinition": "{_json_escape(role_text)}",\n')
+        if when_to_use:
+            sys.stdout.write(f'      "whenToUse": "{_json_escape(when_to_use)}",\n')
         sys.stdout.write('      "groups": ["read", "edit", "command", "mcp"]\n')
         sys.stdout.write("    }")
 

package/scripts/generate_windsurf_hooks.py

@@ -0,0 +1,143 @@
+#!/usr/bin/env python3
+"""Generate .windsurf/hooks.json for Windsurf Cascade.
+
+Writes `<target>/.windsurf/hooks.json`. Existing user hook entries are
+preserved; only entries tagged `_source: ai-toolkit` are replaced on
+regeneration. Windsurf merges system / user / workspace hooks at runtime, so
+this file is safe to live alongside `~/.codeium/windsurf/hooks.json`.
+
+Windsurf Cascade events (per docs.windsurf.com/windsurf/cascade/hooks.md):
+    pre_read_code, post_read_code, pre_write_code, post_write_code,
+    pre_run_command, post_run_command, pre_mcp_tool_use, post_mcp_tool_use,
+    pre_user_prompt, post_cascade_response,
+    post_cascade_response_with_transcript, post_setup_worktree
+    (12 total).
+
+Pre-hooks can block via exit code 2 (see `guard-destructive.sh`). Each entry
+takes `command` (macOS/Linux) + optional `powershell` (Windows). We only emit
+`command` because our hook scripts are bash-only.
+
+Usage:
+    python3 scripts/generate_windsurf_hooks.py [target-dir]
+"""
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+
+HOOKS_PREFIX = '"$HOME/.softspark/ai-toolkit/hooks/'
+SOURCE_TAG = "ai-toolkit"
+
+# Event -> list of script names.
+WINDSURF_HOOKS: dict[str, list[str]] = {
+    "pre_read_code": [
+        "guard-path.sh",
+    ],
+    "pre_write_code": [
+        "guard-path.sh",
+        "guard-config.sh",
+    ],
+    "post_write_code": [
+        "post-tool-use.sh",
+        "governance-capture.sh",
+    ],
+    "pre_run_command": [
+        "guard-destructive.sh",
+        "commit-quality.sh",
+    ],
+    "post_run_command": [
+        "governance-capture.sh",
+    ],
+    "pre_mcp_tool_use": [
+        "guard-config.sh",
+    ],
+    "pre_user_prompt": [
+        "user-prompt-submit.sh",
+        "track-usage.sh",
+    ],
+    "post_cascade_response": [
+        "quality-check.sh",
+        "save-session.sh",
+    ],
+    "post_setup_worktree": [
+        "session-context.sh",
+    ],
+}
+
+
+def build_hook_entry(script: str) -> dict:
+    """Build a single Windsurf hook entry.
+
+    Uses `bash -c` semantics via the raw command (Windsurf already runs the
+    macOS/Linux `command` via `bash -c`).
+    """
+    return {
+        "_source": SOURCE_TAG,
+        "command": f"{HOOKS_PREFIX}{script}\"",
+        "show_output": False,
+    }
+
+
+def build_toolkit_hooks() -> dict[str, list[dict]]:
+    return {event: [build_hook_entry(s) for s in scripts]
+            for event, scripts in WINDSURF_HOOKS.items()}
+
+
+def _is_toolkit_entry(entry: dict) -> bool:
+    return isinstance(entry, dict) and entry.get("_source") == SOURCE_TAG
+
+
+def strip_toolkit_hooks(hooks: dict) -> dict:
+    kept: dict = {}
+    for event, entries in hooks.items():
+        if not isinstance(entries, list):
+            kept[event] = entries
+            continue
+        survivors = [e for e in entries if not _is_toolkit_entry(e)]
+        if survivors:
+            kept[event] = survivors
+    return kept
+
+
+def merge_hooks(existing: dict, toolkit: dict) -> dict:
+    merged = strip_toolkit_hooks(existing)
+    for event, entries in toolkit.items():
+        merged.setdefault(event, []).extend(entries)
+    return merged
+
+
+def generate(target_dir: Path) -> Path:
+    ws_dir = target_dir / ".windsurf"
+    ws_dir.mkdir(parents=True, exist_ok=True)
+    path = ws_dir / "hooks.json"
+
+    doc: dict = {}
+    if path.is_file():
+        try:
+            with open(path, encoding="utf-8") as f:
+                doc = json.load(f)
+            if not isinstance(doc, dict):
+                doc = {}
+        except (json.JSONDecodeError, OSError):
+            doc = {}
+
+    existing_hooks = doc.get("hooks") if isinstance(doc.get("hooks"), dict) else {}
+    doc["hooks"] = merge_hooks(existing_hooks or {}, build_toolkit_hooks())
+
+    with open(path, "w", encoding="utf-8") as f:
+        json.dump(doc, f, indent=4, ensure_ascii=False, sort_keys=True)
+        f.write("\n")
+    return path
+
+
+def main() -> None:
+    target = Path(sys.argv[1]) if len(sys.argv) > 1 else Path.cwd()
+    path = generate(target)
+    total = sum(len(v) for v in WINDSURF_HOOKS.values())
+    print(f"Generated: {path.relative_to(target) if path.is_relative_to(target) else path} "
+          f"({total} hooks across {len(WINDSURF_HOOKS)} events)")
+
+
+if __name__ == "__main__":
+    main()