@softspark/ai-toolkit 4.31.0 → 4.32.1

package/scripts/plugin.py

@@ -2006,6 +2006,16 @@ def _apply_asset_install(
             "inode": version.inode,
         }
         print(f"    Installed plugin {spec.kind}: {spec.path.name}")
+    return _merge_asset_ownership(previous_ownership, name, editor, produced_entries)
+
+
+def _merge_asset_ownership(
+    previous_ownership: dict | None,
+    name: str,
+    editor: str,
+    produced_entries: dict[str, dict],
+) -> dict:
+    """Fold one editor's freshly written assets into the pack's ownership record."""
     entries = _asset_entries(previous_ownership, name)
     entries.update(produced_entries)
     consumers = _shared_asset_consumers(previous_ownership, name)
@@ -2022,6 +2032,37 @@ def _apply_asset_install(
     }
 
 
+def _ownership_from_copied_assets(
+    name: str,
+    editor: str,
+    pack_dir: Path,
+    hook_specs: list[dict],
+    previous_ownership: dict | None,
+) -> dict:
+    """Record what the non-transactional Claude/Codex install just copied.
+
+    ``_copy_plugin_hook_scripts`` and ``_copy_plugin_scripts`` write the same
+    paths ``_prepare_asset_specs`` describes but never recorded them, so
+    removal had nothing to verify against and preserved every file as
+    "untracked" (v4.32.1). Reading the versions back from disk after the copy
+    gives removal the same sha256/mode/inode contract the JSON runtimes get.
+    """
+    produced: dict[str, dict] = {}
+    for spec in _prepare_asset_specs(name, pack_dir, hook_specs):
+        version = _read_file_version(spec.path)
+        if version is None:
+            continue
+        produced[spec.key] = {
+            "path": str(spec.path),
+            "kind": spec.kind,
+            "sha256": hashlib.sha256(version.content).hexdigest(),
+            "mode": version.mode,
+            "device": version.device,
+            "inode": version.inode,
+        }
+    return _merge_asset_ownership(previous_ownership, name, editor, produced)
+
+
 def _preflight_asset_removal(
     transaction: PluginFileTransaction,
     ownership: dict | None,
@@ -2075,6 +2116,74 @@ def _apply_asset_removal(
         print(f"    WARN preserved changed or user-owned plugin asset: {path}")
 
 
+def _remove_owned_plugin_assets(state: dict | None, name: str, editor: str) -> None:
+    """Delete the hook and script files this pack installed for ``editor``.
+
+    Claude and Codex removal never consulted ``shared_asset_ownership``: the
+    files were written on install, recorded, and then reported as "untracked"
+    on remove because nothing looked the record up. Every pack left its hooks
+    and ``plugin-scripts/<name>/`` behind (v4.32.1).
+
+    Same rules as the transactional runtimes: an entry is deleted only when
+    this editor consumes it, no other editor still does, and the file on disk
+    is byte- and inode-identical to what install recorded. Anything else
+    (user edits, a file install never wrote, a symlink) is preserved and named.
+    """
+    ownership = _shared_asset_ownership_for(state or {}, name)
+    entries = _asset_entries(ownership, name)
+    consumers = _shared_asset_consumers(ownership, name)
+    editor_keys = set(consumers.get(editor, ()))
+    other_keys = {
+        key
+        for consumer, keys in consumers.items()
+        if consumer != editor
+        for key in keys
+    }
+    scripts_root = TOOLKIT_DATA_DIR / "plugin-scripts" / name
+    hook_prefix = f"plugin-{name}-"
+    handled: set[Path] = set()
+
+    for key, entry in entries.items():
+        raw_path = entry.get("path")
+        if not isinstance(raw_path, str):
+            continue
+        path = Path(raw_path)
+        handled.add(path.absolute())
+        if key not in editor_keys or key in other_keys:
+            continue
+        kind = entry.get("kind")
+        if kind == "hook":
+            safe = path.parent.absolute() == HOOKS_DIR.absolute() and path.name.startswith(hook_prefix)
+        elif kind == "script":
+            safe = path.parent.absolute() == scripts_root.absolute()
+        else:
+            safe = False
+        if not safe:
+            print(f"    WARN refused to remove plugin asset outside its owned root: {path}")
+            continue
+        if path.is_symlink():
+            print(f"    WARN preserved symlinked plugin asset: {path}")
+            continue
+        version = _read_file_version(path)
+        if version is None:
+            continue
+        if not _asset_entry_matches(path, version, entry):
+            print(f"    WARN preserved changed plugin asset: {path}")
+            continue
+        path.unlink()
+        print(f"    Removed plugin asset: {path.name}")
+
+    for hook in sorted(HOOKS_DIR.glob(f"{hook_prefix}*")):
+        if hook.absolute() not in handled:
+            print(f"    WARN preserved untracked plugin hook: {hook}")
+    if scripts_root.is_dir():
+        for leftover in sorted(scripts_root.iterdir()):
+            if leftover.absolute() not in handled:
+                print(f"    WARN preserved untracked plugin script: {leftover}")
+        if not any(scripts_root.iterdir()):
+            scripts_root.rmdir()
+
+
 def _state_after_removal(
     state: dict,
     editor: str,
@@ -2616,19 +2725,15 @@ def _remove_claude_pack_links(pack: dict, pack_dir: Path) -> None:
 
 
 def remove_pack_claude(
-    name: str, pack: dict, pack_dir: Path, *, keep_shared_assets: bool
+    name: str, pack: dict, pack_dir: Path, *, keep_shared_assets: bool,
+    state: dict | None = None,
 ) -> bool:
     hook_specs = _resolve_pack_hooks(pack, pack_dir)
     rule_specs = _resolve_pack_rules(pack, pack_dir)
     _remove_claude_pack_links(pack, pack_dir)
 
     if not keep_shared_assets:
-        for hook in HOOKS_DIR.glob(f"plugin-{name}-*"):
-            print(f"    WARN preserved untracked plugin hook: {hook}")
-
-        scripts_dir = TOOLKIT_DATA_DIR / "plugin-scripts" / name
-        if scripts_dir.is_dir():
-            print(f"    WARN preserved untracked plugin scripts: {scripts_dir}")
+        _remove_owned_plugin_assets(state, name, "claude")
 
     if any(not spec["is_core"] for spec in hook_specs):
         _strip_claude_hooks(name)
@@ -3000,7 +3105,8 @@ def install_pack_codex(name: str, pack: dict, pack_dir: Path) -> bool:
 
 
 def remove_pack_codex(
-    name: str, pack: dict, pack_dir: Path, *, keep_shared_assets: bool
+    name: str, pack: dict, pack_dir: Path, *, keep_shared_assets: bool,
+    state: dict | None = None,
 ) -> bool:
     _assert_safe_codex_surface()
     _strip_codex_hooks(name)
@@ -3016,14 +3122,10 @@ def remove_pack_codex(
                 print(f"    WARN preserved user-owned Codex hook: {hook.name}")
 
     if not keep_shared_assets:
-        # Clean paths used by releases before native Codex plugin assets moved
-        # under $CODEX_HOME. Claude still owns these when installed for both.
-        for hook in HOOKS_DIR.glob(f"plugin-{name}-*"):
-            print(f"    WARN preserved untracked plugin hook: {hook}")
-
-        scripts_dir = TOOLKIT_DATA_DIR / "plugin-scripts" / name
-        if scripts_dir.is_dir():
-            print(f"    WARN preserved untracked plugin scripts: {scripts_dir}")
+        # Paths used by releases before native Codex plugin assets moved under
+        # $CODEX_HOME. Claude still owns these when installed for both, which
+        # the ownership consumers encode; only Codex-consumed entries go.
+        _remove_owned_plugin_assets(state, name, "codex")
 
     _remove_codex_rules(name)
     print(f"  Done: removed {name} from codex")
@@ -3202,6 +3304,14 @@ def _install_pack_locked(
             if transaction_snapshots is not None:
                 _restore_file_snapshots(transaction_snapshots)
             return False
+        if editor in ("claude", "codex"):
+            asset_ownership = _ownership_from_copied_assets(
+                name,
+                editor,
+                pack_dir,
+                _resolve_pack_hooks(pack, pack_dir),
+                _shared_asset_ownership_for(state, name),
+            )
 
         if hook_config_update is not None:
             if transaction_snapshots is not None:
@@ -3362,6 +3472,7 @@ def _remove_pack_locked(
                 pack,
                 pack_dir,
                 keep_shared_assets=keep_shared_assets,
+                state=state,
             )
         elif editor == "codex":
             ok = remove_pack_codex(
@@ -3369,6 +3480,7 @@ def _remove_pack_locked(
                 pack,
                 pack_dir,
                 keep_shared_assets=keep_shared_assets,
+                state=state,
             )
         elif editor in JSON_HOOK_RUNTIMES:
             ok = remove_pack_json_runtime(

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
 
@@ -152,16 +153,29 @@ MAX_EMITTED_SKILL_NODES = 10_000
 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")):