@softspark/ai-toolkit 1.7.0 → 1.8.0

package/scripts/install.py

@@ -58,6 +58,16 @@ from install_steps.install_state import (
 )
 from install_steps.detect_language import detect_languages
 
+# Config inheritance (extends system)
+from config_resolver import (
+    ConfigResolverError,
+    load_project_config,
+    resolve_extends,
+)
+from config_merger import ConfigMergeError, merge_config_chain
+from config_validator import validate_project_config
+from config_lock import save_lock_file
+
 
 # ---------------------------------------------------------------------------
 # Manifest helpers
@@ -199,6 +209,8 @@ def parse_args(argv: list[str]) -> dict:
         "status": False,
         "lang": "",
         "editors": "",
+        "config": "",
+        "refresh_base": False,
     }
     i = 0
     while i < len(argv):
@@ -248,6 +260,13 @@ def parse_args(argv: list[str]) -> dict:
         elif arg == "--editors":
             i += 1
             cfg["editors"] = argv[i] if i < len(argv) else ""
+        elif arg.startswith("--config="):
+            cfg["config"] = arg.split("=", 1)[1]
+        elif arg == "--config":
+            i += 1
+            cfg["config"] = argv[i] if i < len(argv) else ""
+        elif arg == "--refresh-base":
+            cfg["refresh_base"] = True
         elif arg.startswith("-"):
             print(f"Unknown option: {arg}")
             sys.exit(1)
@@ -442,6 +461,117 @@ def install_strict_git_hooks(profile: str, local: bool, dry_run: bool) -> None:
 # Version helper
 # ---------------------------------------------------------------------------
 
+def resolve_extends_config(
+    project_dir: Path,
+    config_path: str = "",
+    refresh: bool = False,
+) -> dict | None:
+    """Resolve .ai-toolkit.json extends and return merged config.
+
+    Returns None if no .ai-toolkit.json or no extends field.
+    Prints warnings/errors and exits on fatal errors.
+    """
+    if config_path:
+        config_file = Path(config_path)
+        if not config_file.is_file():
+            print(f"  Error: config file not found: {config_path}")
+            sys.exit(1)
+        import json as _json
+        with open(config_file, encoding="utf-8") as f:
+            project_config = _json.load(f)
+        config_root = config_file.parent
+    else:
+        project_config = load_project_config(project_dir)
+        config_root = project_dir
+
+    if project_config is None:
+        return None
+
+    # Validate project config schema
+    errors = validate_project_config(project_config, config_root)
+    if errors:
+        print("  Config validation errors:")
+        for e in errors:
+            print(f"    ✗ {e}")
+        sys.exit(1)
+
+    extends = project_config.get("extends")
+    if not extends:
+        # Config without extends — just use its settings directly
+        return project_config
+
+    print(f"  Resolving extends: {extends}...")
+
+    try:
+        result = resolve_extends(extends, config_root, refresh=refresh)
+    except ConfigResolverError as e:
+        print(f"  ✗ Resolution failed: {e}")
+        sys.exit(1)
+
+    for w in result.warnings:
+        print(f"  ⚠ {w}")
+
+    # Merge
+    try:
+        base_datas = [c.data for c in result.configs]
+        merge_result = merge_config_chain(base_datas, project_config)
+    except ConfigMergeError as e:
+        print(f"  ✗ Merge failed: {e}")
+        sys.exit(1)
+
+    for c in result.configs:
+        version_str = f" v{c.version}" if c.version else ""
+        print(f"  ✓ Resolved: {c.name}{version_str}")
+
+    # Attach resolution metadata for state.json recording
+    config_metas = [
+        {
+            "source": c.source,
+            "name": c.name,
+            "version": c.version,
+            "integrity": c.integrity,
+            "root": str(c.root),
+        }
+        for c in result.configs
+    ]
+    merge_result.merged["_extends_meta"] = {
+        "source": extends,
+        "configs": config_metas,
+        "overrides_applied": merge_result.overrides_applied,
+    }
+
+    # Generate lock file
+    lock_path = save_lock_file(
+        config_root,
+        config_metas,
+        ai_toolkit_version=_get_toolkit_version(),
+    )
+    print(f"  Saved: {lock_path.name}")
+
+    return merge_result.merged
+
+
+def _apply_merged_config(
+    merged: dict,
+    cfg: dict,
+) -> dict:
+    """Apply merged config settings back into the install cfg dict.
+
+    Overrides profile and modules based on merged config.
+    Returns the modified cfg.
+    """
+    # Profile from merged config
+    merged_profile = merged.get("profile")
+    if merged_profile and not cfg["profile"]:
+        cfg["profile"] = merged_profile
+
+    # Agents: filter based on merged enabled/disabled lists
+    # (stored for use by install_local_project)
+    cfg["_merged_config"] = merged
+
+    return cfg
+
+
 def _get_toolkit_version() -> str:
     """Read version from package.json."""
     pkg = toolkit_dir / "package.json"
@@ -522,10 +652,21 @@ def main() -> None:
 
     if local:
         # --local: project-local only, no global install
+        # Check for .ai-toolkit.json extends system
+        config_path_arg: str = cfg["config"]
+        refresh_base: bool = cfg["refresh_base"]
+        merged_config = resolve_extends_config(
+            project_dir, config_path=config_path_arg, refresh=refresh_base,
+        )
+        if merged_config:
+            cfg = _apply_merged_config(merged_config, cfg)
+            profile = cfg["profile"]
+
         lang_modules = [m for m in (resolved_modules or []) if m.startswith("rules-")]
         editors_arg: str = cfg["editors"]
         install_local_project(rules_dir, dry_run, reset, lang_modules or None,
-                              editors=editors_arg)
+                              editors=editors_arg,
+                              merged_config=merged_config)
         install_strict_git_hooks(profile, local, dry_run)
     else:
         # Global install
@@ -549,11 +690,18 @@ def main() -> None:
             # 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,
         )
 
     print_summary(local=local)

package/scripts/install_steps/ai_tools.py

@@ -172,7 +172,8 @@ def _resolve_editors(editors_arg: str, cwd: Path) -> list[str]:
 
 def install_local_project(rules_dir: Path, dry_run: bool, reset: bool,
                           language_modules: list[str] | None = None,
-                          editors: str = "") -> None:
+                          editors: str = "",
+                          merged_config: dict | None = None) -> None:
     """Install project-local configs.
 
     Claude Code configs (CLAUDE.md, settings, constitution) are always installed.
@@ -180,12 +181,18 @@ def install_local_project(rules_dir: Path, dry_run: bool, reset: bool,
     - ``--editors all``: install all editors
     - ``--editors cursor,aider``: install only these
     - (empty): auto-detect from existing project files, install only those
+
+    If ``merged_config`` is provided (from .ai-toolkit.json extends resolution),
+    additional rules and constitution amendments from the base config are injected.
     """
     cwd = Path.cwd()
     resolved_editors = _resolve_editors(editors, cwd)
 
     print()
     print(f"## Project-local ({cwd})")
+    if merged_config and merged_config.get("_extends_meta"):
+        meta = merged_config["_extends_meta"]
+        print(f"   Config: .ai-toolkit.json (extends: {meta['source']})")
     if reset:
         print("   Mode: RESET (all local configs will be wiped and recreated)")
     if resolved_editors:
@@ -198,6 +205,8 @@ def install_local_project(rules_dir: Path, dry_run: bool, reset: bool,
         _install_local_dry_run(reset, resolved_editors)
         if language_modules:
             print(f"  Would inject language rules: {', '.join(language_modules)}")
+        if merged_config:
+            print(f"  Would apply merged config from extends")
         return
 
     (cwd / ".claude").mkdir(parents=True, exist_ok=True)
@@ -223,6 +232,10 @@ def install_local_project(rules_dir: Path, dry_run: bool, reset: bool,
         )
         print("  Injected: .claude/constitution.md")
 
+    # Apply extends: inject base rules and constitution amendments
+    if merged_config:
+        _apply_extends_config(cwd, merged_config)
+
     # Inject language-specific rules into project CLAUDE.md
     _inject_language_rules(cwd, language_modules)
 
@@ -231,6 +244,93 @@ def install_local_project(rules_dir: Path, dry_run: bool, reset: bool,
                                   language_modules=language_modules)
 
 
+def _apply_extends_config(cwd: Path, merged: dict) -> None:
+    """Apply merged extends config — inject base rules and constitution amendments."""
+    import json as _json
+
+    # Inject base rules into CLAUDE.md
+    rules = merged.get("rules", {})
+    inject_rules = rules.get("inject", [])
+    if inject_rules:
+        claude_md = cwd / ".claude" / "CLAUDE.md"
+        if claude_md.is_file():
+            content = claude_md.read_text(encoding="utf-8")
+        else:
+            content = ""
+
+        # Add extends rules section if not already present
+        marker_start = "<!-- TOOLKIT:extends-rules START -->"
+        marker_end = "<!-- TOOLKIT:extends-rules END -->"
+
+        rules_block = f"\n{marker_start}\n"
+        rules_block += "# Inherited Rules (from base config)\n\n"
+        for rule_path in inject_rules:
+            rules_block += f"- Rule: `{rule_path}`\n"
+        rules_block += f"{marker_end}\n"
+
+        if marker_start in content:
+            # Replace existing section
+            import re
+            content = re.sub(
+                f"{re.escape(marker_start)}.*?{re.escape(marker_end)}",
+                f"{marker_start}\n# Inherited Rules (from base config)\n\n"
+                + "".join(f"- Rule: `{r}`\n" for r in inject_rules)
+                + marker_end,
+                content,
+                flags=re.DOTALL,
+            )
+        else:
+            content += rules_block
+
+        claude_md.write_text(content, encoding="utf-8")
+        print(f"  Injected: {len(inject_rules)} rule(s) from base config")
+
+    # Inject constitution amendments
+    amendments = merged.get("constitution", {}).get("amendments", [])
+    # Filter to non-toolkit articles (6+)
+    custom_amendments = [a for a in amendments if a.get("article", 0) >= 6]
+    if custom_amendments:
+        constitution_file = cwd / ".claude" / "constitution.md"
+        if constitution_file.is_file():
+            content = constitution_file.read_text(encoding="utf-8")
+        else:
+            content = ""
+
+        marker_start = "<!-- TOOLKIT:extends-constitution START -->"
+        marker_end = "<!-- TOOLKIT:extends-constitution END -->"
+
+        amendments_block = f"\n{marker_start}\n"
+        for a in custom_amendments:
+            amendments_block += f"\n## Article {a['article']}: {a['title']}\n\n"
+            amendments_block += f"{a['text']}\n"
+        amendments_block += f"\n{marker_end}\n"
+
+        if marker_start in content:
+            import re
+            new_inner = ""
+            for a in custom_amendments:
+                new_inner += f"\n## Article {a['article']}: {a['title']}\n\n"
+                new_inner += f"{a['text']}\n"
+            content = re.sub(
+                f"{re.escape(marker_start)}.*?{re.escape(marker_end)}",
+                f"{marker_start}{new_inner}\n{marker_end}",
+                content,
+                flags=re.DOTALL,
+            )
+        else:
+            content += amendments_block
+
+        constitution_file.write_text(content, encoding="utf-8")
+        print(f"  Injected: {len(custom_amendments)} constitution amendment(s) from base config")
+
+    # Record merged config summary
+    meta = merged.get("_extends_meta")
+    if meta:
+        state_file = cwd / ".ai-toolkit-extends.json"
+        state_file.write_text(_json.dumps(meta, indent=2) + "\n", encoding="utf-8")
+        print(f"  Saved: .ai-toolkit-extends.json (resolution metadata)")
+
+
 def _inject_language_rules(cwd: Path, language_modules: list[str] | None) -> None:
     """Inject language-specific rule summary into project's .claude/CLAUDE.md.
 

package/scripts/install_steps/install_state.py

@@ -68,11 +68,15 @@ def record_install(
     modules: list[str],
     profile: str,
     auto_detected: list[str] | None = None,
+    extends_info: dict | None = None,
 ) -> None:
     """Record a successful install in state.json.
 
     If state already exists, preserves ``installed_at`` and updates
     ``last_updated``. Otherwise sets both timestamps.
+
+    ``extends_info`` (optional) records config inheritance metadata:
+    source, version, resolved_at, hash, overrides_applied.
     """
     state = load_state()
     now = _now_iso()
@@ -86,6 +90,17 @@ def record_install(
     if auto_detected is not None:
         state["auto_detected_languages"] = sorted(auto_detected)
 
+    if extends_info is not None:
+        state["extends"] = {
+            "source": extends_info.get("source", ""),
+            "configs": extends_info.get("configs", []),
+            "resolved_at": now,
+            "overrides_applied": extends_info.get("overrides_applied", []),
+        }
+    elif "extends" in state:
+        # Clear extends if no longer using it
+        del state["extends"]
+
     save_state(state)
 
     # Clear version check cache (version may have changed)
@@ -121,6 +136,15 @@ def print_status() -> None:
         langs = [m.replace("rules-", "") for m in detected]
         print(f"  Detected:   {', '.join(langs)}")
 
+    extends = state.get("extends")
+    if extends:
+        print(f"  Extends:    {extends.get('source', 'unknown')}")
+        for cfg in extends.get("configs", []):
+            version_str = f" v{cfg['version']}" if cfg.get("version") else ""
+            print(f"              → {cfg.get('name', cfg.get('source', '?'))}{version_str}")
+        if extends.get("resolved_at"):
+            print(f"  Resolved:   {extends['resolved_at']}")
+
     # Check for updates
     try:
         import sys as _sys

package/scripts/schemas/ai-toolkit-config.schema.json

@@ -0,0 +1,163 @@
+{
+  "$schema": "https://json-schema.org/draft-07/schema#",
+  "$id": "https://softspark.github.io/ai-toolkit/schemas/ai-toolkit-config.json",
+  "title": "ai-toolkit project configuration",
+  "description": "Project-level configuration for ai-toolkit with optional inheritance via extends.",
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "$schema": {
+      "type": "string",
+      "description": "JSON Schema reference (ignored at runtime)."
+    },
+    "extends": {
+      "type": "string",
+      "description": "Base config to inherit from. npm package name (@scope/pkg or @scope/pkg@version), git URL (git+https://...), or local path (./path or ../path).",
+      "examples": [
+        "@mycompany/ai-toolkit-config",
+        "@mycompany/ai-toolkit-config@^2.0.0",
+        "git+https://github.com/myco/ai-config.git",
+        "../shared-config"
+      ]
+    },
+    "name": {
+      "type": "string",
+      "description": "Config identity (required for base configs published as npm packages)."
+    },
+    "version": {
+      "type": "string",
+      "description": "Semantic version (required for base configs).",
+      "pattern": "^\\d+\\.\\d+\\.\\d+(-[a-zA-Z0-9.]+)?(\\+[a-zA-Z0-9.]+)?$"
+    },
+    "description": {
+      "type": "string",
+      "description": "Human-readable description of this configuration."
+    },
+    "profile": {
+      "type": "string",
+      "enum": ["minimal", "standard", "strict", "full", "offline-slm"],
+      "default": "standard",
+      "description": "Installation profile controlling which modules are installed."
+    },
+    "agents": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Agent configuration — enable, disable, or add custom agents.",
+      "properties": {
+        "enabled": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Agent names to enable (merged with base)."
+        },
+        "disabled": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Agent names to disable (blocked if base enforces them)."
+        },
+        "custom": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Paths to custom agent .md files (relative to config root)."
+        }
+      }
+    },
+    "rules": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Rule injection configuration.",
+      "properties": {
+        "inject": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Paths to rule .md files to inject into CLAUDE.md."
+        },
+        "remove": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Rule names to remove from base config."
+        }
+      }
+    },
+    "constitution": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Constitution amendments. Articles I-V are immutable. Base articles are immutable. Projects can only ADD new articles.",
+      "properties": {
+        "amendments": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["article", "title", "text"],
+            "additionalProperties": false,
+            "properties": {
+              "article": {
+                "type": "integer",
+                "minimum": 1,
+                "description": "Article number. 1-5 are reserved (immutable). Base articles are also immutable."
+              },
+              "title": {
+                "type": "string",
+                "description": "Article title."
+              },
+              "text": {
+                "type": "string",
+                "description": "Article text."
+              }
+            }
+          }
+        }
+      }
+    },
+    "enforce": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Non-overridable constraints (base configs only). Projects inheriting this config must comply.",
+      "properties": {
+        "minHookProfile": {
+          "type": "string",
+          "enum": ["minimal", "standard", "strict"],
+          "description": "Minimum hook profile — projects cannot go below this."
+        },
+        "requiredPlugins": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Plugins that must be installed in all inheriting projects."
+        },
+        "forbidOverride": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Components that cannot be overridden by inheriting projects."
+        },
+        "requiredAgents": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Agents that must be enabled in all inheriting projects."
+        }
+      }
+    },
+    "overrides": {
+      "type": "object",
+      "additionalProperties": {
+        "type": "object",
+        "required": ["override", "justification"],
+        "properties": {
+          "override": {
+            "type": "boolean",
+            "const": true,
+            "description": "Must be true to confirm intentional override."
+          },
+          "justification": {
+            "type": "string",
+            "minLength": 20,
+            "description": "Explanation for why this override is needed (min 20 chars)."
+          },
+          "replacement": {
+            "type": "string",
+            "description": "Replacement value or 'skip' to disable."
+          }
+        }
+      },
+      "description": "Explicit overrides of base config components. Each override requires override:true + justification."
+    }
+  }
+}