@softspark/ai-toolkit 4.12.0 → 4.13.0

package/scripts/install.py

@@ -756,34 +756,36 @@ def main() -> None:
 
     # Record install state (skip for dry-run)
     if not dry_run:
-        auto_detected = None
-        if auto_detect:
-            auto_detected = detect_languages(project_dir, toolkit_dir)
-
-        # Determine what modules to record
-        if resolved_modules is not None:
-            record_modules = resolved_modules
-        else:
-            # Legacy mode: infer modules from profile/only
-            record_modules = _infer_modules_from_legacy(profile, only)
-
         # Extract extends metadata if available
         extends_info = None
         merged = cfg.get("_merged_config")
         if merged and merged.get("_extends_meta"):
             extends_info = merged["_extends_meta"]
 
-        record_install(
-            version=_get_toolkit_version(),
-            modules=record_modules,
-            profile=profile or "standard",
-            auto_detected=auto_detected,
-            extends_info=extends_info,
-        )
+        # state.json describes the global install and drives future `update`
+        # invocations. Project-local installs belong in projects.json and must
+        # never replace the global profile/modules with the last project's
+        # auto-detected language set.
+        if not local:
+            auto_detected = None
+            if auto_detect:
+                auto_detected = detect_languages(project_dir, toolkit_dir)
+
+            if resolved_modules is not None:
+                record_modules = resolved_modules
+            else:
+                record_modules = _infer_modules_from_legacy(profile, only)
+
+            record_install(
+                version=_get_toolkit_version(),
+                modules=record_modules,
+                profile=profile or "standard",
+                auto_detected=auto_detected,
+                extends_info=extends_info,
+            )
 
-        # Record global editors (only for global install, not --local)
-        if not local and installed_eds:
-            record_global_editors(installed_eds)
+            if installed_eds:
+                record_global_editors(installed_eds)
 
         # Register project in global registry (for `ai-toolkit update` propagation)
         # Skipped when called from update_projects.py (--skip-register) to avoid

package/scripts/install_steps/ai_tools.py

@@ -110,7 +110,10 @@ def install_ai_tools(target_dir: Path, rules_dir: Path,
     if "cline" in eds:
         if dry_run:
             print("  Would generate: ~/Documents/Cline/Rules/ai-toolkit-*.md")
-            print("  Would generate: ~/.cline/skills/ai-toolkit-skill-catalogue/SKILL.md")
+            if _claude_skills_discoverable(target_dir):
+                print("  Would reuse: ~/.claude/skills/ (Cline-compatible discovery)")
+            else:
+                print("  Would generate: ~/.cline/skills/ai-toolkit-skill-catalogue/SKILL.md")
         else:
             _install_cline_global(target_dir, rules_dir)
         installed.append("cline")
@@ -277,6 +280,80 @@ def _install_windsurf_global(target_dir: Path, rules_dir: Path) -> None:
     )
 
 
+def _cleanup_retired_windsurf_surfaces(cwd: Path) -> None:
+    """Remove only ai-toolkit content from retired/undocumented Devin paths."""
+    import json
+
+    legacy_hooks = cwd / ".windsurf" / "hooks.json"
+    if legacy_hooks.is_file():
+        try:
+            document = json.loads(legacy_hooks.read_text(encoding="utf-8"))
+        except (OSError, json.JSONDecodeError):
+            print("  Warning: kept invalid .windsurf/hooks.json for manual review")
+        else:
+            hooks = document.get("hooks") if isinstance(document, dict) else None
+            changed = False
+            if isinstance(hooks, dict):
+                kept_hooks: dict = {}
+                for event, entries in hooks.items():
+                    if not isinstance(entries, list):
+                        kept_hooks[event] = entries
+                        continue
+                    survivors = [
+                        entry
+                        for entry in entries
+                        if not (
+                            isinstance(entry, dict)
+                            and (
+                                entry.get("_source") == "ai-toolkit"
+                                or any(
+                                    isinstance(handler, dict)
+                                    and handler.get("_source") == "ai-toolkit"
+                                    for handler in entry.get("hooks", [])
+                                )
+                            )
+                        )
+                    ]
+                    if len(survivors) != len(entries):
+                        changed = True
+                    if survivors:
+                        kept_hooks[event] = survivors
+                if changed:
+                    if kept_hooks:
+                        document["hooks"] = kept_hooks
+                    else:
+                        document.pop("hooks", None)
+                    if document:
+                        legacy_hooks.write_text(
+                            json.dumps(
+                                document,
+                                indent=4,
+                                ensure_ascii=False,
+                                sort_keys=True,
+                            ) + "\n",
+                            encoding="utf-8",
+                        )
+                    else:
+                        legacy_hooks.unlink()
+                    print("  Migrated: removed retired ai-toolkit Cascade hooks")
+
+    retired_pointer = (
+        cwd / ".devin" / "skills" / "ai-toolkit-skill-catalogue"
+    )
+    skill_file = retired_pointer / "SKILL.md"
+    if skill_file.is_file() and "name: ai-toolkit-skill-catalogue" in (
+        skill_file.read_text(encoding="utf-8")
+    ):
+        if retired_pointer.is_symlink():
+            retired_pointer.unlink()
+        else:
+            shutil.rmtree(retired_pointer)
+        for parent in (retired_pointer.parent, retired_pointer.parent.parent):
+            if parent.is_dir() and not any(parent.iterdir()):
+                parent.rmdir()
+        print("  Migrated: removed undocumented .devin/skills toolkit pointer")
+
+
 def _install_cline_global(target_dir: Path, rules_dir: Path) -> None:
     """Install Cline global rules in the documented ~/.cline directory."""
     from generate_cline_rules import generate as gen_cline_rules
@@ -941,6 +1018,18 @@ def _install_local_dry_run(reset: bool, editors: list[str] | None = None,
         if ed in eds:
             print(msg)
 
+    if "windsurf" in eds:
+        if (Path.cwd() / ".windsurf" / "hooks.json").is_file():
+            print("  Would migrate: remove retired ai-toolkit Cascade hooks")
+        if (
+            Path.cwd()
+            / ".devin"
+            / "skills"
+            / "ai-toolkit-skill-catalogue"
+            / "SKILL.md"
+        ).is_file():
+            print("  Would migrate: remove undocumented .devin/skills toolkit pointer")
+
     # Profile-driven extras (matrix in kb/reference/global-install-model.md)
     if "copilot" in eds and add_copilot_dir:
         print("  Would generate: .github/instructions/ + .github/prompts/ (profile >= standard)")
@@ -950,7 +1039,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: .devin/hooks.v1.json + .windsurf/hooks.json (Cascade, deprecated) + .devin/skills/ + .windsurf/skills/ (profile=full)")
+            print("  Would generate: .devin/hooks.v1.json + .windsurf/skills/ (profile=full)")
         if "cline" in eds:
             print("  Would generate: .cline/skills/ (profile=full)")
         if "augment" in eds:
@@ -1174,6 +1263,7 @@ def _create_local_ai_tool_configs(cwd: Path, rules_dir: Path,
             _try_generator("generate_cursor_skills", cwd, emit_skill_pointer=emit_pointer)
 
     if "windsurf" in eds:
+        _cleanup_retired_windsurf_surfaces(cwd)
         inject_with_rules(
             "generate-windsurf.sh",
             cwd / ".windsurfrules",
@@ -1183,11 +1273,11 @@ 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)
+            # Cascade's .windsurf/hooks.json surface ended on 2026-07-01.
+            # Devin CLI uses the Claude-compatible .devin/hooks.v1.json format.
             _try_generator("generate_devin_hooks", cwd)
-            # Windsurf pointer stays unconditional (its .claude scan is gated).
+            # Current Devin docs list .windsurf/skills as a supported path;
+            # .devin/skills is not documented.
             _try_generator("generate_windsurf_skills", cwd)
 
     if "cline" in eds:

package/scripts/install_steps/install_state.py

@@ -197,6 +197,8 @@ def record_install(
     state["profile"] = profile
     if auto_detected is not None:
         state["auto_detected_languages"] = sorted(auto_detected)
+    else:
+        state.pop("auto_detected_languages", None)
 
     if extends_info is not None:
         state["extends"] = {

package/scripts/update_projects.py

@@ -28,8 +28,19 @@ def _update_project(project: dict[str, Any], install_script: str, extra_args: li
     # Pass saved editors from registry so update re-installs the same editors
     cmd_args = ["python3", install_script, "--local"] + extra_args
     project_editors = project.get("editors", [])
-    if project_editors:
+    has_editor_override = any(
+        arg == "--editors" or arg.startswith("--editors=")
+        for arg in extra_args
+    )
+    if project_editors and not has_editor_override:
         cmd_args.extend(["--editors", ",".join(project_editors)])
+    has_profile_override = any(
+        arg == "--profile" or arg.startswith("--profile=")
+        for arg in extra_args
+    )
+    project_profile = project.get("profile", "")
+    if project_profile and not has_profile_override:
+        cmd_args.extend(["--profile", project_profile])
 
     try:
         proc = subprocess.run(

package/scripts/validate.py

@@ -124,6 +124,10 @@ LANGUAGE_RULE_CATEGORIES = frozenset({
 
 PLANNED_ASSETS = [
     "app/.claude-plugin/plugin.json",
+    "app/claude-app/hooks/hooks.json",
+    "app/claude-app/skills/ai-toolkit-rules/SKILL.md",
+    "app/claude-app/global-instructions.md",
+    "scripts/claude_app.py",
     "scripts/doctor.py",
     "scripts/benchmark_ecosystem.py",
     "scripts/harvest_ecosystem.py",
@@ -561,9 +565,37 @@ def validate_planned_assets(tk_dir: Path, vr: ValidationResult) -> None:
             assert d["name"]
             assert d["version"]
             assert d["description"]
-            print("  OK: plugin manifest JSON is valid")
+            assert isinstance(d.get("repository"), str)
+            ignored = {"npm", "install", "marketplace", "claude-code"} & set(d)
+            assert not ignored
+            for path_field in ("hooks", "skills"):
+                relative = str(d[path_field]).removeprefix("./")
+                assert (tk_dir / "app" / relative).exists()
+            print("  OK: plugin manifest matches the official schema surface")
         except (json.JSONDecodeError, KeyError, AssertionError):
-            vr.error("Invalid plugin manifest JSON or missing required fields")
+            vr.error("Invalid plugin manifest JSON, official fields, or component paths")
+
+    try:
+        from claude_app import (
+            GLOBAL_INSTRUCTIONS_PATH,
+            PLUGIN_HOOKS_PATH,
+            PLUGIN_RULES_SKILL_PATH,
+            render_global_instructions,
+            render_plugin_hooks,
+            render_rules_skill,
+        )
+        generated = (
+            (PLUGIN_HOOKS_PATH, render_plugin_hooks()),
+            (PLUGIN_RULES_SKILL_PATH, render_rules_skill()),
+            (GLOBAL_INSTRUCTIONS_PATH, render_global_instructions()),
+        )
+        stale = [path for path, expected in generated if path.read_text(encoding="utf-8") != expected]
+        if stale:
+            vr.error("Stale Claude app assets; run: python3 scripts/claude_app.py sync")
+        else:
+            print("  OK: Claude app plugin assets match canonical rules/hooks")
+    except (OSError, ValueError, json.JSONDecodeError) as exc:
+        vr.error(f"Invalid Claude app generated assets: {exc}")
 
     # Validate benchmark dashboard JSON
     benchmark_dashboard = tk_dir / "benchmarks" / "ecosystem-dashboard.json"