@softspark/ai-toolkit 4.6.0 → 4.8.0

package/scripts/generate_devin_hooks.py

@@ -0,0 +1,149 @@
+#!/usr/bin/env python3
+"""Generate ``.devin/hooks.v1.json`` for the Devin CLI (formerly Windsurf).
+
+Devin CLI uses a hook format **compatible with Claude Code hooks**
+(docs.devin.ai/cli/extensibility/hooks/overview). This generator is the
+replacement for the deprecated Cascade ``.windsurf/hooks.json`` surface,
+which stops working when Cascade sunsets on 2026-07-01. Devin Local / Devin
+CLI do NOT read ``.windsurf/hooks.json`` as a fallback, so the hooks must be
+regenerated onto this new file.
+
+Output file: ``<target>/.devin/hooks.v1.json``. Per the Devin docs the
+standalone ``hooks.v1.json`` file's entire contents ARE the hooks object —
+there is **no** top-level ``"hooks"`` wrapper key (unlike
+``.claude/settings.json`` or ``.devin/config.json``).
+
+Events use Claude-style PascalCase names. Matchers are regexes against the
+Devin **tool name** (``read``, ``edit``, ``exec``, ``grep``, ``glob``,
+``mcp__<server>__<tool>``) — NOT Claude's ``Bash``/``Edit`` names — so the
+shared guard scripts reliably fire under Devin.
+
+Blocking contract: the shared guard scripts emit ``{"decision":"block",
+"reason":...}`` on stdout (plain mode) AND exit 2 — Devin honors both (docs:
+exit 2 = deny; JSON ``{"decision":"block"}`` = deny). Hooks therefore run
+WITHOUT ``AI_TOOLKIT_HOOK_FORMAT=json`` because Devin expects the flat
+``{"decision","reason"}`` shape, not Claude's ``hookSpecificOutput`` envelope.
+
+Existing user hook entries are preserved; only entries tagged
+``_source: ai-toolkit`` are replaced on regeneration.
+
+Usage:
+    python3 scripts/generate_devin_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 (matcher_regex, [script names]).
+# Matchers target Devin tool names: read, edit, exec, mcp__<server>__<tool>.
+# An empty matcher fires for every tool name (Devin: omitted/empty = match all).
+DEVIN_HOOKS: dict[str, list[tuple[str, list[str]]]] = {
+    "PreToolUse": [
+        ("^(read|edit)$", ["guard-path.sh"]),
+        ("^edit$", ["guard-config.sh"]),
+        ("^exec$", ["guard-destructive.sh", "commit-quality.sh", "revert-guard.sh"]),
+        ("^mcp__", ["guard-config.sh"]),
+    ],
+    "PostToolUse": [
+        ("^edit$", ["post-tool-use.sh", "governance-capture.sh", "test-cohesion.sh"]),
+        ("^exec$", ["governance-capture.sh"]),
+        ("^mcp__.*__(smart_query|hybrid_search_kb|crag_search|multi_hop_search|verify_answer)$",
+         ["search-tracker.sh"]),
+    ],
+    "UserPromptSubmit": [
+        ("", ["user-prompt-submit.sh", "track-usage.sh"]),
+    ],
+    "Stop": [
+        ("", ["quality-check.sh", "save-session.sh", "stop-search-check.sh"]),
+    ],
+    # Cascade's post_setup_worktree has no Devin equivalent; session-context
+    # moves to SessionStart (Devin fires SessionStart when a session begins).
+    "SessionStart": [
+        ("", ["session-context.sh"]),
+    ],
+}
+
+
+def build_hook_entry(matcher: str, scripts: list[str]) -> dict:
+    """Build one Devin matcher-group: ``{matcher, hooks:[{type,command}]}``."""
+    return {
+        "_source": SOURCE_TAG,
+        "matcher": matcher,
+        "hooks": [
+            {"type": "command", "command": f'{HOOKS_PREFIX}{s}"'}
+            for s in scripts
+        ],
+    }
+
+
+def build_toolkit_hooks() -> dict[str, list[dict]]:
+    return {
+        event: [build_hook_entry(matcher, scripts) for matcher, scripts in groups]
+        for event, groups in DEVIN_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:
+    """Drop ai-toolkit matcher-groups; keep user-authored entries."""
+    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:
+    devin_dir = target_dir / ".devin"
+    devin_dir.mkdir(parents=True, exist_ok=True)
+    path = devin_dir / "hooks.v1.json"
+
+    # The standalone hooks.v1.json file IS the hooks object (no wrapper key).
+    existing: dict = {}
+    if path.is_file():
+        try:
+            with open(path, encoding="utf-8") as f:
+                existing = json.load(f)
+            if not isinstance(existing, dict):
+                existing = {}
+        except (json.JSONDecodeError, OSError):
+            existing = {}
+
+    merged = merge_hooks(existing, build_toolkit_hooks())
+
+    with open(path, "w", encoding="utf-8") as f:
+        json.dump(merged, 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(scripts) for groups in DEVIN_HOOKS.values()
+                for _, scripts in groups)
+    rel = path.relative_to(target) if path.is_relative_to(target) else path
+    print(f"Generated: {rel} ({total} hooks across {len(DEVIN_HOOKS)} events)")
+
+
+if __name__ == "__main__":
+    main()

package/scripts/generate_windsurf_hooks.py

@@ -1,6 +1,12 @@
 #!/usr/bin/env python3
 """Generate .windsurf/hooks.json for Windsurf Cascade.
 
+DEPRECATED SURFACE: the Cascade agent is available only through 2026-07-01
+(Devin Local is the default agent since the 2026-06-02 Devin Desktop rebrand),
+and this hooks.json schema is Cascade-scoped. Migrate to the Devin CLI
+lifecycle-hooks surface (docs.devin.ai/cli/extensibility/hooks/*) before that
+date; tracked in the ecosystem registry status_note for windsurf.
+
 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

package/scripts/generate_windsurf_rules.py

@@ -1,17 +1,25 @@
 #!/usr/bin/env python3
-"""Generate ``.windsurf/rules/*.md`` (and workflows) for Windsurf IDE.
+"""Generate ``.devin/rules/*.md`` and ``.windsurf/rules/*.md`` (and workflows)
+for Devin Desktop (formerly Windsurf).
 
-Windsurf reads directory-based rules from ``.windsurf/rules/*.md`` (since
-mid-2025). Each rule file supports YAML frontmatter with these fields
-(from docs.windsurf.com/windsurf/cascade/memories):
+Windsurf rebranded to Devin Desktop on 2026-06-02. ``.devin/`` is now the
+primary read+write workspace tree; ``.windsurf/`` is a legacy read-only
+fallback that current builds still honor (docs.devin.ai/desktop/devin-desktop-faq:
+"The application already supports .devin/ as the primary workspace directory
+and falls back to .windsurf/ for backward compatibility"). We dual-emit the
+same content to both trees so old Windsurf builds keep working during the
+transition.
+
+Each rule file supports YAML frontmatter with these fields
+(from docs.devin.ai/desktop — memories docs):
 
 * ``trigger`` — activation mode: ``always_on`` | ``glob`` | ``model_decision``
-  | ``manual``. When omitted, Windsurf defaults to manual-only.
+  | ``manual``. When omitted, the IDE defaults to manual-only.
 * ``globs`` — comma-separated glob patterns (only when ``trigger: glob``).
 * ``description`` — shown to the model when ``trigger: model_decision``.
 
-Windsurf also reads workflow markdown files from ``.windsurf/workflows/*.md``
-which users invoke via ``/<name>`` slash commands (Cascade). This generator
+Workflow markdown files (invoked via ``/<name>`` slash commands) are emitted
+to ``.devin/workflows/*.md`` and ``.windsurf/workflows/*.md``. This generator
 emits the same workflow catalogue used by Antigravity and Cline.
 
 The legacy ``.windsurfrules`` single-file format is still produced by
@@ -142,20 +150,26 @@ def _build_rules(language_modules: list[str] | None,
 
 
 # ---------------------------------------------------------------------------
-# Workflows — .windsurf/workflows/<name>.md invocable via /<name>
+# Workflows — <tree>/workflows/<name>.md invocable via /<name>
 # ---------------------------------------------------------------------------
 
+# .devin/ is primary since the 2026-06-02 Devin Desktop rebrand; .windsurf/
+# is the legacy fallback still read by pre-rebrand builds.
+CONFIG_TREES: tuple[str, ...] = (".devin", ".windsurf")
+
+
 def _write_workflows(target_dir: Path, *, cleanup: bool = True) -> None:
-    """Write ``.windsurf/workflows/*.md`` files for Cascade slash commands."""
-    workflows_dir = target_dir / ".windsurf" / "workflows"
-    workflows_dir.mkdir(parents=True, exist_ok=True)
+    """Write ``workflows/*.md`` slash-command files to both config trees."""
+    for tree in CONFIG_TREES:
+        workflows_dir = target_dir / tree / "workflows"
+        workflows_dir.mkdir(parents=True, exist_ok=True)
 
-    if cleanup:
-        cleanup_stale(workflows_dir, set(STANDARD_WORKFLOWS.keys()))
+        if cleanup:
+            cleanup_stale(workflows_dir, set(STANDARD_WORKFLOWS.keys()))
 
-    for filename, content_fn in STANDARD_WORKFLOWS.items():
-        (workflows_dir / filename).write_text(content_fn(), encoding="utf-8")
-        print(f"  Generated: .windsurf/workflows/{filename}")
+        for filename, content_fn in STANDARD_WORKFLOWS.items():
+            (workflows_dir / filename).write_text(content_fn(), encoding="utf-8")
+            print(f"  Generated: {tree}/workflows/{filename}")
 
 
 # ---------------------------------------------------------------------------
@@ -170,15 +184,16 @@ def generate(target_dir: Path, *,
              managed_scopes: tuple[str, ...] = (
                  STANDARD_SCOPE, LANG_SCOPE, CUSTOM_SCOPE,
              )) -> None:
-    """Write ``.windsurf/rules/*.md`` and ``.windsurf/workflows/*.md``."""
+    """Write ``rules/*.md`` and ``workflows/*.md`` to both config trees."""
     rules = _build_rules(language_modules, rules_dir)
-    write_rules(
-        target_dir,
-        rules,
-        ".windsurf/rules",
-        cleanup=cleanup,
-        managed_scopes=managed_scopes,
-    )
+    for tree in CONFIG_TREES:
+        write_rules(
+            target_dir,
+            rules,
+            f"{tree}/rules",
+            cleanup=cleanup,
+            managed_scopes=managed_scopes,
+        )
 
     if emit_workflows:
         _write_workflows(target_dir, cleanup=cleanup)

package/scripts/generate_windsurf_skills.py

@@ -1,5 +1,11 @@
 #!/usr/bin/env python3
-"""Generate a Windsurf skill pointer under ``.windsurf/skills/``."""
+"""Generate a Devin Desktop (formerly Windsurf) skill pointer.
+
+Dual-emits under ``.devin/skills/`` (primary since the 2026-06-02 rebrand)
+and ``.windsurf/skills/`` (legacy fallback). Pass an explicit ``skill_root``
+to emit a single location instead (used for the ``~/.codeium/windsurf/``
+global install path).
+"""
 from __future__ import annotations
 
 import sys
@@ -8,13 +14,17 @@ from pathlib import Path
 sys.path.insert(0, str(Path(__file__).resolve().parent))
 from skill_pointer import POINTER_SKILL_NAME, write_pointer_skill
 
+DEFAULT_SKILL_ROOTS: tuple[str, ...] = (".devin/skills", ".windsurf/skills")
+
 
 def generate(target_dir: Path, *, emit_skill_pointer: bool = True,
-             skill_root: str = ".windsurf/skills") -> None:
+             skill_root: str | None = None) -> None:
     if not emit_skill_pointer:
         return
-    write_pointer_skill(target_dir, skill_root, "Windsurf")
-    print(f"  Generated: {skill_root}/{POINTER_SKILL_NAME}/SKILL.md")
+    roots = (skill_root,) if skill_root else DEFAULT_SKILL_ROOTS
+    for root in roots:
+        write_pointer_skill(target_dir, root, "Windsurf")
+        print(f"  Generated: {root}/{POINTER_SKILL_NAME}/SKILL.md")
 
 
 def main() -> None:

package/scripts/install_steps/ai_tools.py

@@ -381,6 +381,9 @@ _EDITOR_MARKERS: dict[str, str] = {
     ".cursor/rules": "cursor",
     ".windsurfrules": "windsurf",
     ".windsurf/rules": "windsurf",
+    # .devin/ is the primary Devin Desktop tree since the 2026-06-02 rebrand;
+    # .windsurf/ markers stay to detect legacy installs.
+    ".devin/rules": "windsurf",
     ".clinerules": "cline",
     ".roomodes": "roo",
     ".roo/rules": "roo",
@@ -411,11 +414,25 @@ def _detect_editors(cwd: Path) -> list[str]:
     found: set[str] = set()
     for marker, editor in _EDITOR_MARKERS.items():
         p = cwd / marker
-        if p.exists():
-            found.add(editor)
+        if not p.exists():
+            continue
+        if marker == ".agents/skills" and _is_pointer_only_skills_dir(p):
+            # The Antigravity CLI pointer skill also lives in .agents/skills/;
+            # only real (materialized) skills indicate a Codex install.
+            continue
+        found.add(editor)
     return sorted(found)
 
 
+def _is_pointer_only_skills_dir(skills_dir: Path) -> bool:
+    """True when a skills dir holds only the ai-toolkit pointer skill."""
+    try:
+        entries = [e.name for e in skills_dir.iterdir() if not e.name.startswith(".")]
+    except OSError:
+        return False
+    return entries == ["ai-toolkit-skill-catalogue"]
+
+
 def _resolve_editors(editors_arg: str, cwd: Path) -> list[str]:
     """Resolve --editors argument to a list of editor names.
 
@@ -709,7 +726,7 @@ def _install_local_dry_run(reset: bool, editors: list[str] | None = None,
     _EDITOR_DRY_RUN = {
         "copilot":      "  Would inject: .github/copilot-instructions.md",
         "cursor":       "  Would generate: .cursorrules + .cursor/rules/*.mdc",
-        "windsurf":     "  Would generate: .windsurfrules + .windsurf/rules/*.md",
+        "windsurf":     "  Would generate: .windsurfrules + .devin/rules/*.md + .windsurf/rules/*.md",
         "cline":        "  Would generate: .clinerules/*.md",
         "roo":          "  Would generate: .roomodes + .roo/rules/*.md",
         "aider":        "  Would generate: .aider.conf.yml + CONVENTIONS.md",
@@ -731,7 +748,7 @@ def _install_local_dry_run(reset: bool, editors: list[str] | None = None,
         if "cursor" in eds:
             print("  Would generate: .cursor/hooks.json + .cursor/agents/ + .cursor/skills/ (profile=full)")
         if "windsurf" in eds:
-            print("  Would generate: .windsurf/hooks.json + .windsurf/skills/ (profile=full)")
+            print("  Would generate: .devin/hooks.v1.json + .windsurf/hooks.json (Cascade, deprecated) + .devin/skills/ + .windsurf/skills/ (profile=full)")
         if "cline" in eds:
             print("  Would generate: .cline/skills/ (profile=full)")
         if "augment" in eds:
@@ -963,7 +980,10 @@ def _create_local_ai_tool_configs(cwd: Path, rules_dir: Path,
         gen_windsurf_rules(cwd, language_modules=language_modules,
                            rules_dir=rules_dir)
         if add_native_surfaces:
+            # .windsurf/hooks.json is Cascade-scoped and dies 2026-07-01;
+            # .devin/hooks.v1.json is the Devin CLI replacement (Claude format).
             _try_generator("generate_windsurf_hooks", cwd)
+            _try_generator("generate_devin_hooks", cwd)
             # Windsurf pointer stays unconditional (its .claude scan is gated).
             _try_generator("generate_windsurf_skills", cwd)
 

package/scripts/validate.py

@@ -846,11 +846,15 @@ def _validate_version_sync(tk_dir: Path, vr: ValidationResult) -> None:
 # generators come and go.
 _NATIVE_HOOK_EDITORS = {"claude", "opencode"}
 
+# generate_<stem>_hooks.py stems that belong to an existing README platform key.
+_HOOK_STEM_ALIAS = {"devin": "windsurf"}
+
 # README platform label (lowercased) -> canonical editor key.
 _README_PLATFORM_KEY = {
     "claude code": "claude",
     "cursor": "cursor",
     "windsurf": "windsurf",
+    "windsurf (devin desktop)": "windsurf",
     "gemini cli": "gemini",
     "github copilot": "copilot",
     "cline": "cline",
@@ -876,10 +880,12 @@ def _validate_editor_hooks_honesty(tk_dir: Path, vr: ValidationResult) -> None:
         return  # installed copy without source — nothing to cross-check
 
     # Actual hook-enabled editors: native set + generate_<editor>_hooks.py stems.
+    # Some stems map back to a README platform key (e.g. the Devin CLI hooks
+    # generator is part of the windsurf/Devin-Desktop integration).
     actual = set(_NATIVE_HOOK_EDITORS)
     for gen in scripts_dir.glob("generate_*_hooks.py"):
         stem = gen.name[len("generate_"):-len("_hooks.py")]
-        actual.add(stem)
+        actual.add(_HOOK_STEM_ALIAS.get(stem, stem))
 
     content = readme.read_text(encoding="utf-8")
     if "| Hooks |" not in content: