@softspark/ai-toolkit 4.30.3 → 4.32.0

package/scripts/install_steps/skill_scope.py

@@ -0,0 +1,188 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright 2024-2026 Lukasz Krzemien (biuro@softspark.eu)
+# Source: https://github.com/softspark/ai-toolkit
+
+"""Scope language knowledge skills to the stacks a user actually works in.
+
+The global install symlinks every ``<lang>-rules`` / ``<lang>-patterns``
+skill into ``~/.claude/skills``. Each one's description then sits in the
+model-visible skill listing of every session, whether or not the user has a
+single project in that language. This step reads the languages detected
+across the registered projects (``projects.json``) and turns the others off
+through Claude Code's ``skillOverrides`` setting.
+
+Rules of engagement:
+
+* Evidence first. With no registered project on disk there is nothing to
+  judge, so nothing is disabled.
+* Only entries this step wrote are ever removed again. They are tracked in
+  ``state.json`` under ``managed_skill_overrides``; a user's own override is
+  left alone even when it names a language skill.
+* ``--language-skills all`` restores every managed entry and persists the
+  choice so later ``install`` / ``update`` runs do not prune again.
+* Reversible by hand: delete the key from ``~/.claude/settings.json``.
+
+Stdlib-only.
+"""
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+from install_steps.detect_language import detect_languages
+from install_steps.install_state import load_state, save_state
+from install_steps.project_registry import load_registry
+
+LANGUAGE_SKILL_SUFFIXES = ("rules", "patterns")
+SCOPE_ALL = "all"
+SCOPE_DETECTED = "detected"
+VALID_SCOPES = (SCOPE_ALL, SCOPE_DETECTED)
+STATE_SCOPE_KEY = "language_skill_scope"
+STATE_MANAGED_KEY = "managed_skill_overrides"
+
+
+def language_skill_names(toolkit_dir: Path) -> dict[str, str]:
+    """Map each shipped language knowledge skill to its language.
+
+    A skill counts as a language skill when it is named ``<lang>-rules`` or
+    ``<lang>-patterns`` and ``app/rules/<lang>/`` exists. ``flutter-patterns``
+    therefore does not (no ``app/rules/flutter``), which is deliberate:
+    only skills generated from a language rule set are scoped.
+    """
+    rules_root = toolkit_dir / "app" / "rules"
+    skills_root = toolkit_dir / "app" / "skills"
+    if not rules_root.is_dir() or not skills_root.is_dir():
+        return {}
+    languages = {p.name for p in rules_root.iterdir() if p.is_dir() and p.name != "common"}
+    mapping: dict[str, str] = {}
+    for skill_dir in sorted(skills_root.iterdir()):
+        if not skill_dir.is_dir() or "-" not in skill_dir.name:
+            continue
+        lang, _, suffix = skill_dir.name.rpartition("-")
+        if suffix in LANGUAGE_SKILL_SUFFIXES and lang in languages:
+            mapping[skill_dir.name] = lang
+    return mapping
+
+
+def detected_languages_from_registry(toolkit_dir: Path) -> set[str] | None:
+    """Union of languages detected across registered projects that still exist.
+
+    Returns ``None`` when no registered project directory exists, which
+    callers must read as "no evidence", not "no languages".
+    """
+    found: set[str] = set()
+    seen_project = False
+    for entry in load_registry():
+        path = entry.get("path")
+        if not isinstance(path, str):
+            continue
+        project_dir = Path(path)
+        if not project_dir.is_dir():
+            continue
+        seen_project = True
+        for module in detect_languages(project_dir, toolkit_dir):
+            if module.startswith("rules-") and module != "rules-common":
+                found.add(module[len("rules-"):])
+    return found if seen_project else None
+
+
+def _load_settings(settings_path: Path) -> dict[str, Any]:
+    if not settings_path.is_file():
+        return {}
+    try:
+        with open(settings_path, encoding="utf-8") as f:
+            data = json.load(f)
+    except (OSError, json.JSONDecodeError):
+        return {}
+    return data if isinstance(data, dict) else {}
+
+
+def _save_settings(settings_path: Path, data: dict[str, Any]) -> None:
+    settings_path.parent.mkdir(parents=True, exist_ok=True)
+    with open(settings_path, "w", encoding="utf-8") as f:
+        json.dump(data, f, indent=4)
+        f.write("\n")
+
+
+def resolve_scope(requested: str, state: dict[str, Any] | None = None) -> str:
+    """Pick the effective scope: explicit flag wins, else the persisted choice."""
+    if requested in VALID_SCOPES:
+        return requested
+    persisted = (state if state is not None else load_state()).get(STATE_SCOPE_KEY)
+    return persisted if persisted in VALID_SCOPES else SCOPE_DETECTED
+
+
+def reconcile_language_skill_overrides(
+    toolkit_dir: Path,
+    settings_path: Path,
+    *,
+    scope: str,
+    dry_run: bool = False,
+) -> tuple[list[str], list[str]]:
+    """Bring ``skillOverrides`` in line with the detected language set.
+
+    Returns ``(disabled, restored)`` skill names. Prints one line per
+    outcome in the install's ``  Verb: detail`` style.
+    """
+    state = load_state()
+    managed: set[str] = {
+        name for name in state.get(STATE_MANAGED_KEY, []) if isinstance(name, str)
+    }
+    skills = language_skill_names(toolkit_dir)
+    settings = _load_settings(settings_path)
+    overrides = settings.get("skillOverrides")
+    if not isinstance(overrides, dict):
+        overrides = {}
+
+    disabled: list[str] = []
+    restored: list[str] = []
+
+    if scope == SCOPE_ALL:
+        languages: set[str] | None = None
+    else:
+        languages = detected_languages_from_registry(toolkit_dir)
+
+    for name, lang in sorted(skills.items()):
+        keep_on = languages is None or lang in languages
+        if keep_on:
+            if name in managed and overrides.get(name) == "off":
+                overrides.pop(name)
+                restored.append(name)
+            managed.discard(name)
+            continue
+        if name in overrides:
+            # The user (or an earlier run) already has an opinion; a run never
+            # adopts an entry it did not write.
+            continue
+        overrides[name] = "off"
+        managed.add(name)
+        disabled.append(name)
+
+    if dry_run:
+        if languages is None and scope != SCOPE_ALL:
+            print("  Would skip: language skill scoping (no registered project on disk)")
+        for name in disabled:
+            print(f"  Would disable: skill {name} (skillOverrides)")
+        for name in restored:
+            print(f"  Would restore: skill {name} (skillOverrides)")
+        return disabled, restored
+
+    if disabled or restored:
+        if overrides:
+            settings["skillOverrides"] = overrides
+        else:
+            settings.pop("skillOverrides", None)
+        _save_settings(settings_path, settings)
+    save_state({STATE_SCOPE_KEY: scope, STATE_MANAGED_KEY: sorted(managed)})
+
+    if languages is None and scope != SCOPE_ALL:
+        print("  Skipped: language skill scoping (no registered project on disk; run install --local in a project first)")
+    elif disabled:
+        print(f"  Disabled: {len(disabled)} language skill(s) outside your detected stacks "
+              f"({', '.join(disabled)})")
+    if restored:
+        print(f"  Restored: {len(restored)} language skill(s) ({', '.join(restored)})")
+    if languages is not None and not disabled and not restored and scope == SCOPE_DETECTED:
+        print(f"  Language skills: scoped to {', '.join(sorted(languages)) or 'no detected languages'} (no change)")
+    return disabled, restored

package/scripts/instruction_core.py

@@ -6,8 +6,12 @@
 from __future__ import annotations
 
 import re
+import sys
 from pathlib import Path
 
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+from frontmatter import split_frontmatter  # noqa: E402
+
 
 CONSTITUTION_PATH = (
     Path(__file__).resolve().parent.parent / "app" / "constitution.md"
@@ -16,14 +20,7 @@ CONSTITUTION_PATH = (
 
 def _strip_frontmatter(text: str) -> str:
     """Return Markdown after an optional leading YAML frontmatter block."""
-    lines = text.splitlines()
-    if not lines or lines[0] != "---":
-        return text.strip()
-    try:
-        closing = lines.index("---", 1)
-    except ValueError:
-        return text.strip()
-    return "\n".join(lines[closing + 1:]).strip()
+    return split_frontmatter(text)[1].strip()
 
 
 def read_constitution(path: Path = CONSTITUTION_PATH) -> str:

package/scripts/merge-hooks.py

@@ -123,12 +123,22 @@ def _is_retired_toolkit_entry(entry: dict) -> bool:
     return True
 
 
+# Handler fields that change *how* a command hook is scheduled, not *what* it
+# runs. A legacy untagged entry that differs only in these is the same hook;
+# otherwise adding `async` or `timeout` in app/hooks.json would leave every
+# existing install running the old copy and the new copy side by side.
+_SCHEDULING_FIELDS = frozenset({
+    "async", "asyncRewake", "timeout", "statusMessage", "shell", "once", "if",
+})
+
+
 def _entry_signature(entry: dict) -> tuple:
     """Return the behavior-defining parts of a hook entry.
 
     Older ai-toolkit installs wrote hook entries without ``_source``. Matching
-    on the event, matcher, and handler payload lets current installs remove
-    those legacy duplicates while preserving unrelated user hooks.
+    on the event, matcher, and handler payload (minus scheduling fields) lets
+    current installs remove those legacy duplicates while preserving unrelated
+    user hooks.
     """
     handlers = []
     for hook in entry.get("hooks", []):
@@ -138,7 +148,7 @@ def _entry_signature(entry: dict) -> tuple:
         handlers.append(tuple(sorted(
             (key, value)
             for key, value in hook.items()
-            if key != "_source"
+            if key != "_source" and key not in _SCHEDULING_FIELDS
         )))
     return (entry.get("matcher", ""), tuple(handlers))
 

package/scripts/pack_codebase.py

@@ -37,7 +37,7 @@ import fnmatch
 import json
 import os
 import sys
-from dataclasses import dataclass, field
+from dataclasses import dataclass
 from pathlib import Path
 
 # Token estimate: 4 chars per token is the standard rough heuristic for English / code.

package/scripts/surface_manifest.py

@@ -44,6 +44,7 @@ from pathlib import Path
 
 sys.path.insert(0, str(Path(__file__).resolve().parent))
 from _common import toolkit_dir as default_toolkit_dir
+from frontmatter import FrontmatterError, load_frontmatter
 
 MANIFEST_RELPATH = Path("app") / "surface.json"
 
@@ -52,14 +53,12 @@ CLI_COMMAND_RE = re.compile(r"^\s+'?([a-z][a-z0-9-]*)'?\s*:")
 
 
 def _frontmatter_fields(path: Path) -> set[str]:
-    parts = path.read_text(encoding="utf-8").split("---")
-    if len(parts) < 3:
+    """Top-level frontmatter keys of one file; a file the subset parser
+    refuses contributes nothing, which the removal check then reports."""
+    try:
+        return {key for key in load_frontmatter(path, strict=False) if FM_FIELD_RE.match(f"{key}:")}
+    except FrontmatterError:
         return set()
-    return {
-        m.group(1)
-        for line in parts[1].splitlines()
-        if (m := FM_FIELD_RE.match(line))
-    }
 
 
 def collect_surface(tk_dir: Path) -> dict:

package/scripts/validate.py

@@ -27,6 +27,7 @@ from pathlib import Path
 
 sys.path.insert(0, str(Path(__file__).resolve().parent))
 from _common import toolkit_dir as default_toolkit_dir, frontmatter_field
+from frontmatter import FrontmatterError, parse_scalar
 from plugin_schema import validate_manifest as _validate_plugin_manifest_schema
 from plugin_schema import validate_references as _validate_plugin_references
 
@@ -147,21 +148,34 @@ MAX_EMITTED_SKILL_NODES = 10_000
 #
 # Ratchet: lower WARN by 2_000 each release until it reaches 12_000. Never lower a
 # threshold in the same change that something violates it — split the skill first,
-# then tighten. The step lives in kb/procedures/release-preparation-sop.md so it
+# then tighten. The step lives in kb/procedures/sop-release.md so it
 # does not rot as a comment nobody reads.
 SKILL_BODY_BUDGET_ERROR = 20_000
 SKILL_BODY_BUDGET_WARN = 18_000
 
+# Skill description budget, in characters of the decoded description text.
+#
+# Every model-invocable skill's description sits in the listing that loads at
+# the start of every session, so a long description is paid for on every turn
+# of every user, not just when the skill fires. The Agent Skills spec caps the
+# field at 1024 characters; anything past that is truncated by the runtime.
+SKILL_DESCRIPTION_LIMIT = 1024
+SKILL_DESCRIPTION_BUDGET_WARN = 400
+
 VALID_RULE_CATEGORIES = frozenset({
     "coding-style",
     "testing",
     "security",
     "performance",
     "git-workflow",
+    "git-team",
     "patterns",
     "frameworks",
 })
 
+# Install profiles a common rule may restrict itself to via `profiles:`.
+VALID_RULE_PROFILES = frozenset({"minimal", "standard", "strict", "full"})
+
 COMMON_RULE_CATEGORIES = frozenset({
     "coding-style",
     "testing",
@@ -256,6 +270,139 @@ def _fm_has(lines: list[str], field: str) -> bool:
     return any(line.startswith(f"{field}:") for line in lines)
 
 
+def _fm_description(fm_lines: list[str]) -> tuple[str, str]:
+    """Return ``(raw first-line value, decoded text)`` for ``description:``.
+
+    Handles the three spellings skills use: a plain scalar, a quoted scalar,
+    and a block scalar (``>-`` / ``|``) whose text continues on indented lines.
+    """
+    for index, line in enumerate(fm_lines):
+        if not line.startswith("description:"):
+            continue
+        raw = line[len("description:"):].strip()
+        if raw and raw[0] in ">|":
+            continuation: list[str] = []
+            for nxt in fm_lines[index + 1:]:
+                if nxt.strip() and not nxt[0].isspace():
+                    break
+                continuation.append(nxt.strip())
+            return raw, " ".join(part for part in continuation if part)
+        return raw, _frontmatter_scalar(raw)
+    return "", ""
+
+
+def _validate_skill_description(label: str, fm_lines: list[str],
+                                vr: ValidationResult) -> None:
+    """Enforce the description budget and reject ambiguous plain scalars."""
+    raw, text = _fm_description(fm_lines)
+    if not raw:
+        return
+    is_plain = raw[0] not in "\"'>|"
+    if is_plain and (": " in raw or " #" in raw):
+        # A plain scalar with `: ` or ` #` parses as a nested mapping or a
+        # comment under strict YAML. Claude Code tolerates it today; a stricter
+        # parser drops every field, including allowed-tools, without a warning.
+        vr.error(
+            f"{label}: description is an unquoted scalar containing ': ' or ' #' "
+            "- quote it or use a '>-' block scalar"
+        )
+    length = len(text)
+    if length > SKILL_DESCRIPTION_LIMIT:
+        vr.error(
+            f"{label}: description is {length} characters "
+            f"(limit {SKILL_DESCRIPTION_LIMIT}) - the runtime truncates it"
+        )
+    elif length > SKILL_DESCRIPTION_BUDGET_WARN:
+        vr.warn(
+            f"{label}: description is {length} characters "
+            f"(budget {SKILL_DESCRIPTION_BUDGET_WARN}) - it loads in every session"
+        )
+
+
+def _validate_rule_profiles(rel: str, language: str, fm_lines: list[str],
+                            vr: ValidationResult) -> int:
+    """Validate an optional ``profiles:`` gate on a common rule source file.
+
+    Same block-list form as ``paths``; every value must be an existing install
+    profile. Per-language rules ship as skills and have no profile, so the key
+    is rejected outside ``app/rules/common/``.
+    """
+    if language != "common":
+        vr.error(f"{rel} - profiles is only meaningful for common rules")
+        return 1
+    errors = 0
+    items: list[str] = []
+    in_block = False
+    for line in fm_lines:
+        if line.startswith("profiles:"):
+            if line[len("profiles:"):].strip():
+                vr.error(f"{rel} - profiles must be a block list, not inline: {line.strip()}")
+                return 1
+            in_block = True
+            continue
+        if not in_block:
+            continue
+        stripped = line.strip()
+        if not stripped:
+            continue
+        if not line.startswith("  - "):
+            break
+        item = stripped[2:].strip().strip('"')
+        if item not in VALID_RULE_PROFILES:
+            vr.error(
+                f"{rel} - unknown profile '{item}' "
+                f"(valid: {', '.join(sorted(VALID_RULE_PROFILES))})"
+            )
+            errors += 1
+            continue
+        items.append(item)
+    if not items and errors == 0:
+        vr.error(f"{rel} - profiles block is empty (drop the key to ship in every profile)")
+        errors += 1
+    return errors
+
+
+def _validate_rule_paths(rel: str, fm_lines: list[str], vr: ValidationResult) -> int:
+    """Validate an optional ``paths:`` scope block on a rule source file.
+
+    Mirrors what ``install_steps.ai_tools._rule_paths`` reads: a bare
+    ``paths:`` key followed by one or more ``  - "glob"`` items. Returns the
+    number of errors reported.
+    """
+    errors = 0
+    items: list[str] = []
+    in_paths = False
+    for line in fm_lines:
+        if line.startswith("paths:"):
+            if line[len("paths:"):].strip():
+                vr.error(f"{rel} - paths must be a block list, not inline: {line.strip()}")
+                return 1
+            in_paths = True
+            continue
+        if not in_paths:
+            continue
+        stripped = line.strip()
+        if not stripped:
+            continue
+        if not line.startswith("  - "):
+            break
+        item = stripped[2:].strip()
+        if len(item) < 3 or item[0] != '"' or item[-1] != '"':
+            vr.error(f"{rel} - paths entry must be a double-quoted glob: {stripped}")
+            errors += 1
+            continue
+        glob_value = item[1:-1]
+        if not glob_value or any(ch in glob_value for ch in ' \\"'):
+            vr.error(f"{rel} - paths glob contains whitespace, backslash, or quote: {stripped}")
+            errors += 1
+            continue
+        items.append(glob_value)
+    if not items and errors == 0:
+        vr.error(f"{rel} - paths block is empty (drop the key for an always-on rule)")
+        errors += 1
+    return errors
+
+
 def _validate_invocation_metadata(label: str, fm_lines: list[str],
                                   vr: ValidationResult) -> None:
     """Reject metadata spellings that DSH interprets differently or ignores."""
@@ -296,14 +443,16 @@ def _validate_invocation_metadata(label: str, fm_lines: list[str],
 
 
 def _frontmatter_scalar(raw_value: str) -> str:
-    """Decode the simple scalar forms used by emitted skill metadata."""
-    value = raw_value.strip()
-    if not value:
-        return ""
-    quoted = re.fullmatch(r'''(["'])(.*?)\1(?:\s+#.*)?''', value)
-    if quoted:
-        return quoted.group(2).strip()
-    return re.split(r"\s+#", value, maxsplit=1)[0].strip()
+    """Decode one scalar the way the shared parser does, never raising.
+
+    Validation reports problems as findings; a value the subset parser
+    refuses (anchor, tag, unterminated quote) decodes to its raw text here and
+    is caught by the dedicated checks that follow.
+    """
+    try:
+        return parse_scalar(raw_value, strict=False)
+    except FrontmatterError:
+        return raw_value.strip()
 
 
 def _parse_supported_top_level_entry(
@@ -672,9 +821,7 @@ def _validate_skill_frontmatter(tk_dir: Path, skill_path: Path,
             f"(budget {SKILL_BODY_BUDGET_WARN}) - move detail into reference/"
         )
 
-    desc_value = _fm_field(fm_lines, "description")
-    if len(desc_value) > 1024:
-        vr.warn(f"{name} - Description exceeds 1024 characters")
+    _validate_skill_description(f"skills/{name}/SKILL.md", fm_lines, vr)
 
 
 def _validate_skill_script_invocations(skill_path: Path, vr: ValidationResult) -> None:
@@ -1104,6 +1251,17 @@ def validate_language_rules(tk_dir: Path, vr: ValidationResult) -> None:
                     vr.error(f"{rel} filename does not match category '{category}'")
                     rule_errors += 1
 
+            # Optional Claude Code `paths` scope. The installer reads only the
+            # block-list form (`  - "glob"`), so reject anything else here
+            # rather than letting a rule silently fall back to always-on.
+            if _fm_has(fm_lines, "paths"):
+                rule_errors += _validate_rule_paths(rel, fm_lines, vr)
+
+            # Optional `profiles` gate (common rules only): same block-list
+            # form, values limited to the install profiles that exist.
+            if _fm_has(fm_lines, "profiles"):
+                rule_errors += _validate_rule_profiles(rel, language, fm_lines, vr)
+
         for category in sorted(expected - seen):
             vr.error(f"app/rules/{language} missing required rule category: {category}")
             rule_errors += 1
@@ -1230,6 +1388,17 @@ def _validate_pack_refs(tk_dir: Path, pack_path: Path, d: dict,
     for err in ref_errors:
         vr.error(f"app/plugins/{pack_name}/plugin.json {err}")
 
+    # Pack skills bypass validate_skills() (they live outside app/skills), yet
+    # they are installed as skills. Apply the same description gate so a pack
+    # cannot ship a listing-bloating or strict-YAML-hostile description.
+    pack_skills_dir = pack_path / "skills"
+    if pack_skills_dir.is_dir():
+        for skill_file in sorted(pack_skills_dir.glob("*/SKILL.md")):
+            if not _has_frontmatter(skill_file):
+                continue
+            rel = str(skill_file.relative_to(tk_dir))
+            _validate_skill_description(rel, _parse_frontmatter_lines(skill_file), vr)
+
     hooks_dir = pack_path / "hooks"
     if hooks_dir.is_dir():
         for hook in sorted(hooks_dir.glob("*.sh")):