@softspark/ai-toolkit 4.15.0 → 4.16.0

package/scripts/config_lock.py

@@ -8,6 +8,7 @@ Stdlib-only — no external dependencies.
 """
 from __future__ import annotations
 
+import hashlib
 import json
 import sys
 from datetime import datetime, timezone
@@ -41,9 +42,10 @@ def load_lock_file(project_dir: Path) -> dict[str, Any] | None:
             return None
     try:
         with open(lock_path, encoding="utf-8") as f:
-            return json.load(f)
-    except (json.JSONDecodeError, OSError):
+            lock = json.load(f)
+    except (json.JSONDecodeError, OSError, UnicodeDecodeError):
         return None
+    return lock if isinstance(lock, dict) else None
 
 
 def save_lock_file(
@@ -66,7 +68,7 @@ def save_lock_file(
         "lockfileVersion": LOCK_VERSION,
         "resolved": {},
         "generated_at": _now_iso(),
-        "ai_toolkit_version": ai_toolkit_version,
+        "ai_toolkit_version": ai_toolkit_version or _current_toolkit_version(),
     }
 
     for config in resolved_configs:
@@ -105,16 +107,11 @@ def check_lock_staleness(project_dir: Path) -> str:
     if lock is None:
         return "missing"
 
-    # Check lock version
-    if lock.get("lockfileVersion") != LOCK_VERSION:
-        return f"stale: lock version {lock.get('lockfileVersion')} != {LOCK_VERSION}"
-
-    # Check if resolved entries exist
-    resolved = lock.get("resolved", {})
-    if not resolved:
-        return "stale: no resolved entries"
-
-    return "ok"
+    header_error = _check_lock_header(lock)
+    if header_error:
+        return header_error
+    resolved = lock["resolved"]
+    return _check_resolved_chain(config["extends"], resolved)
 
 
 def get_locked_version(project_dir: Path, config_name: str) -> str | None:
@@ -126,8 +123,13 @@ def get_locked_version(project_dir: Path, config_name: str) -> str | None:
     if lock is None:
         return None
     resolved = lock.get("resolved", {})
+    if not isinstance(resolved, dict):
+        return None
     entry = resolved.get(config_name, {})
-    return entry.get("version") or None
+    if not isinstance(entry, dict):
+        return None
+    version = entry.get("version")
+    return version if isinstance(version, str) and version else None
 
 
 # ---------------------------------------------------------------------------
@@ -139,6 +141,110 @@ def _now_iso() -> str:
     return datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
 
 
+def _check_lock_header(lock: dict[str, Any]) -> str:
+    """Validate lock format and toolkit version."""
+    if lock.get("lockfileVersion") != LOCK_VERSION:
+        return f"stale: lock version {lock.get('lockfileVersion')} != {LOCK_VERSION}"
+    locked_version = lock.get("ai_toolkit_version")
+    current_version = _current_toolkit_version()
+    if current_version and (
+        not isinstance(locked_version, str)
+        or not locked_version
+    ):
+        return "stale: ai-toolkit version metadata is missing or invalid"
+    if current_version and locked_version != current_version:
+        return (
+            f"stale: ai-toolkit version '{locked_version}' "
+            f"!= current '{current_version}'"
+        )
+    resolved = lock.get("resolved")
+    if not isinstance(resolved, dict) or not resolved:
+        return "stale: no resolved entries"
+    if not all(isinstance(entry, dict) for entry in resolved.values()):
+        return "stale: invalid resolved entries"
+    return ""
+
+
+def _check_resolved_chain(
+    current_source: str,
+    resolved: dict[str, dict[str, Any]],
+) -> str:
+    """Compare every locked config against its current cached snapshot."""
+    if not isinstance(current_source, str) or not current_source:
+        return "stale: invalid project extends source"
+    for name, entry in reversed(list(resolved.items())):
+        locked_source = entry.get("source", "")
+        if current_source != locked_source:
+            return (
+                f"stale: extends source '{current_source}' "
+                f"!= locked '{locked_source}'"
+            )
+        error, current_config = _check_resolved_entry(name, entry)
+        if error:
+            return error
+        assert current_config is not None
+        current_source = current_config.get("extends", "")
+        if not isinstance(current_source, str):
+            return f"stale: invalid extends source in resolved config {name}"
+    if current_source:
+        return f"stale: unresolved extends source '{current_source}'"
+    return "ok"
+
+
+def _check_resolved_entry(
+    name: str,
+    entry: dict[str, Any],
+) -> tuple[str, dict[str, Any] | None]:
+    """Compare version and integrity for one locked config."""
+    cached = entry.get("cached")
+    locked_source = entry.get("source")
+    locked_version = entry.get("version")
+    locked_integrity = entry.get("integrity")
+    if (
+        not isinstance(cached, str)
+        or not cached
+        or not isinstance(locked_source, str)
+        or not locked_source
+        or not isinstance(locked_version, str)
+        or not isinstance(locked_integrity, str)
+        or not locked_integrity.startswith("sha256:")
+    ):
+        return f"stale: invalid resolved config metadata for {name}", None
+    config_path = Path(cached).expanduser() / "ai-toolkit.config.json"
+    try:
+        raw_config = config_path.read_bytes()
+        current_config = json.loads(raw_config.decode("utf-8"))
+    except (json.JSONDecodeError, OSError, UnicodeDecodeError):
+        return f"stale: cannot read resolved config for {name}", None
+    if not isinstance(current_config, dict):
+        return f"stale: invalid resolved config content for {name}", None
+    current_version = current_config.get("version", "")
+    if current_version != locked_version:
+        return (
+            f"stale: {name} version '{current_version}' "
+            f"!= locked '{locked_version}'"
+        ), None
+    current_integrity = f"sha256:{hashlib.sha256(raw_config).hexdigest()}"
+    if current_integrity != locked_integrity:
+        return (
+            f"stale: {name} integrity '{current_integrity}' "
+            f"!= locked '{locked_integrity}'"
+        ), None
+    return "", current_config
+
+
+def _current_toolkit_version() -> str:
+    """Read the version of the toolkit owning this lock implementation."""
+    package_path = Path(__file__).resolve().parent.parent / "package.json"
+    try:
+        with open(package_path, encoding="utf-8") as handle:
+            package = json.load(handle)
+    except (json.JSONDecodeError, OSError):
+        return ""
+    version = package.get("version", "")
+    return version if isinstance(version, str) else ""
+
+
 # ---------------------------------------------------------------------------
 # CLI entry point (for testing)
 # ---------------------------------------------------------------------------

package/scripts/config_merger.py

@@ -2,7 +2,7 @@
 """Config merger for ai-toolkit extends system.
 
 Implements layered deep merge with:
-- Constitution immutability (Articles I-VI absolute, base articles immutable)
+- Constitution immutability (Articles I-VII absolute, base articles immutable)
 - Agent merge with requiredAgents enforcement
 - Override validation (override:true + justification required)
 - enforce block constraints (minHookProfile, requiredPlugins, forbidOverride, requiredAgents)
@@ -22,17 +22,10 @@ from typing import Any
 # Constants
 # ---------------------------------------------------------------------------
 
-IMMUTABLE_ARTICLES = frozenset({1, 2, 3, 4, 5, 6})
+IMMUTABLE_ARTICLES = frozenset({1, 2, 3, 4, 5, 6, 7})
 
 HOOK_PROFILE_ORDER = {"minimal": 0, "standard": 1, "strict": 2}
 
-# v1 schema fields that participate in merge
-V1_FIELDS = frozenset({
-    "$schema", "extends", "name", "version", "description",
-    "profile", "agents", "rules", "constitution", "enforce", "overrides",
-})
-
-
 # ---------------------------------------------------------------------------
 # Exceptions
 # ---------------------------------------------------------------------------
@@ -84,6 +77,13 @@ def merge_config_chain(
     # Merge project over accumulated base
     result.merged = _merge_project_over_base(accumulated_base, project_config, result)
 
+    if "toolOutputFilter" in accumulated_base or "toolOutputFilter" in project_config:
+        configured = result.merged.get("toolOutputFilter", {})
+        result.merged["toolOutputFilter"] = _deep_merge(
+            _load_default_output_filter_policy(),
+            configured,
+        )
+
     # Validate enforce constraints
     _validate_enforce(accumulated_base, result.merged)
 
@@ -95,6 +95,16 @@ def merge_two(base: dict[str, Any], overlay: dict[str, Any]) -> dict[str, Any]:
     return _deep_merge(base, overlay)
 
 
+def _load_default_output_filter_policy() -> dict[str, Any]:
+    """Load the canonical disabled output-filter policy."""
+    policy_path = Path(__file__).resolve().parent.parent / "app" / "output-filter-policy.json"
+    with open(policy_path, encoding="utf-8") as handle:
+        policy = json.load(handle)
+    if not isinstance(policy, dict):
+        raise ConfigMergeError(f"Invalid output-filter policy: {policy_path}")
+    return policy
+
+
 # ---------------------------------------------------------------------------
 # Internal: project-over-base merge (with enforcement)
 # ---------------------------------------------------------------------------
@@ -108,6 +118,8 @@ def _merge_project_over_base(
     merged: dict[str, Any] = {}
 
     all_keys = set(base.keys()) | set(project.keys())
+    if base.get("enforce", {}).get("requiredPlugins"):
+        all_keys.add("plugins")
 
     for key in all_keys:
         # Skip meta fields that don't participate in merge output
@@ -119,23 +131,21 @@ def _merge_project_over_base(
         base_val = base.get(key)
         proj_val = project.get(key)
 
-        if proj_val is None:
+        if key == "plugins":
+            merged[key] = _merge_plugins(base_val or {}, proj_val or {}, base)
+        elif proj_val is None:
             merged[key] = base_val
         elif key == "overrides":
             # Always validate overrides against base enforce, even if base has no overrides
             merged[key] = _validate_overrides(base, proj_val, result)
-        elif key == "constitution" and base_val is not None:
-            merged[key] = _merge_constitution(base_val, proj_val, base)
+        elif key == "constitution":
+            merged[key] = _merge_constitution(base_val or {}, proj_val, base)
         elif base_val is None:
             merged[key] = proj_val
-        elif key == "constitution":
-            merged[key] = _merge_constitution(base_val, proj_val, base)
         elif key == "agents":
             merged[key] = _merge_agents(base_val, proj_val, base)
         elif key == "rules":
             merged[key] = _merge_rules(base_val, proj_val)
-        elif key == "overrides":
-            merged[key] = _validate_overrides(base, proj_val, result)
         elif key == "enforce":
             # enforce blocks merge: base wins (projects cannot weaken enforcement)
             merged[key] = _merge_enforce(base_val, proj_val)
@@ -163,7 +173,7 @@ def _merge_constitution(
     """Merge constitution — additions only, no modifications.
 
     Rules:
-    1. Articles I-VI (1-6) are ABSOLUTELY immutable — toolkit core.
+    1. Articles I-VII (1-7) are ABSOLUTELY immutable — toolkit core.
     2. Articles defined by base configs are immutable — projects cannot modify.
     3. Projects can ADD new articles with article numbers not in base.
     """
@@ -177,8 +187,8 @@ def _merge_constitution(
         if article_num in IMMUTABLE_ARTICLES:
             raise ConfigMergeError(
                 f"Cannot modify Constitution Article {article_num} — immutable.\n"
-                f"Articles I-VI are defined by ai-toolkit and cannot be overridden.\n"
-                f"You can ADD new articles (article 7+)."
+                f"Articles I-VII are defined by ai-toolkit and cannot be overridden.\n"
+                f"You can ADD new articles (article 8+)."
             )
         if article_num in base_amendments:
             raise ConfigMergeError(
@@ -226,6 +236,71 @@ def _merge_agents(
     }
 
 
+def _merge_plugins(
+    base: dict[str, Any],
+    project: dict[str, Any],
+    full_base: dict[str, Any],
+) -> dict[str, list[str]]:
+    """Merge plugin intent while preserving inherited requirements."""
+    base_enabled = _plugin_names(base, "enabled", "base plugins")
+    base_disabled = _plugin_names(base, "disabled", "base plugins")
+    project_enabled = _plugin_names(project, "enabled", "project plugins")
+    project_disabled = _plugin_names(project, "disabled", "project plugins")
+    required = _plugin_names(
+        full_base.get("enforce", {}),
+        "requiredPlugins",
+        "base enforce",
+    )
+    for label, enabled, disabled in (
+        ("base", base_enabled, base_disabled),
+        ("project", project_enabled, project_disabled),
+    ):
+        overlap = enabled & disabled
+        if overlap:
+            raise ConfigMergeError(
+                f"{label.capitalize()} plugins cannot be both enabled and "
+                f"disabled: {', '.join(sorted(overlap))}."
+            )
+    blocked = required & project_disabled
+    if blocked:
+        plugin = sorted(blocked)[0]
+        raise ConfigMergeError(
+            f"Cannot disable plugin '{plugin}' — required by base config "
+            f"'{full_base.get('name', 'unknown')}'."
+        )
+
+    enabled = set(base_enabled)
+    enabled.update(project_enabled)
+    enabled.difference_update(project_disabled)
+    enabled.update(required)
+    disabled = (base_disabled | project_disabled) - enabled
+    return {
+        "enabled": sorted(enabled),
+        "disabled": sorted(disabled),
+    }
+
+
+def _plugin_names(
+    block: Any,
+    key: str,
+    label: str,
+) -> set[str]:
+    """Return validated plugin names for a merge boundary."""
+    if not isinstance(block, dict):
+        raise ConfigMergeError(f"{label} must be an object.")
+    value = block.get(key, [])
+    if not isinstance(value, list) or not all(
+        isinstance(item, str) and item.strip()
+        for item in value
+    ):
+        raise ConfigMergeError(
+            f"{label}.{key} must be an array of non-empty strings."
+        )
+    if len(value) != len(set(value)):
+        raise ConfigMergeError(f"{label}.{key} must not contain duplicates.")
+    return set(value)
+
+
 # ---------------------------------------------------------------------------
 # Merge: rules
 # ---------------------------------------------------------------------------
@@ -363,7 +438,15 @@ def _validate_enforce(
                 f"is below minimum '{min_profile}' required by base config."
             )
 
-    # requiredPlugins — deferred to v2 (plugins field not in v1)
+    required_plugins = set(enforce.get("requiredPlugins", []))
+    if required_plugins:
+        enabled_plugins = set(merged.get("plugins", {}).get("enabled", []))
+        missing_plugins = required_plugins - enabled_plugins
+        if missing_plugins:
+            errors.append(
+                "Required plugins missing from enabled intent: "
+                f"{', '.join(sorted(missing_plugins))}."
+            )
 
     # requiredAgents
     required_agents = set(enforce.get("requiredAgents", []))

package/scripts/config_resolver.py

@@ -10,7 +10,6 @@ from __future__ import annotations
 
 import hashlib
 import json
-import os
 import shutil
 import subprocess
 import sys
@@ -167,6 +166,7 @@ def _resolve_chain(
 
     # Resolve this source
     base_config = _resolve_source(extends_value, project_root, result, refresh=refresh)
+    _validate_resolved_base(base_config)
 
     # Recurse if this base also extends something
     if base_config.extends:
@@ -182,6 +182,19 @@ def _resolve_chain(
     result.configs.append(base_config)
 
 
+def _validate_resolved_base(base_config: BaseConfig) -> None:
+    """Reject an invalid base before consumers merge or inspect it."""
+    from config_validator import validate_base_config
+
+    errors = validate_base_config(base_config.data, base_config.root)
+    if not errors:
+        return
+    details = "\n".join(f"  - {error}" for error in errors)
+    raise ConfigResolverError(
+        f"Invalid base config '{base_config.source}':\n{details}"
+    )
+
+
 def _resolve_source(
     source: str,
     project_root: Path,
@@ -470,11 +483,18 @@ def _load_json(path: Path) -> dict[str, Any]:
     """Load and parse a JSON file."""
     try:
         with open(path, encoding="utf-8") as f:
-            return json.load(f)
+            config = json.load(f)
     except json.JSONDecodeError as e:
         raise ConfigResolverError(f"Invalid JSON in {path}: {e}") from e
+    except UnicodeDecodeError as e:
+        raise ConfigResolverError(
+            f"Cannot decode {path} as UTF-8: {e}"
+        ) from e
     except OSError as e:
         raise ConfigResolverError(f"Cannot read {path}: {e}") from e
+    if not isinstance(config, dict):
+        raise ConfigResolverError(f"{path} must contain a JSON object.")
+    return config
 
 
 def _file_hash(path: Path) -> str: