@softspark/ai-toolkit 1.7.0 → 1.9.0

package/scripts/install.py

@@ -57,6 +57,17 @@ from install_steps.install_state import (
     print_status,
 )
 from install_steps.detect_language import detect_languages
+from install_steps.project_registry import register_project
+
+# 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
 
 
 # ---------------------------------------------------------------------------
@@ -199,6 +210,8 @@ def parse_args(argv: list[str]) -> dict:
         "status": False,
         "lang": "",
         "editors": "",
+        "config": "",
+        "refresh_base": False,
     }
     i = 0
     while i < len(argv):
@@ -248,6 +261,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 +462,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 +653,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,13 +691,33 @@ 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,
         )
 
+        # Register project in global registry (for `ai-toolkit update` propagation)
+        if local:
+            extends_source = ""
+            if extends_info:
+                extends_source = extends_info.get("source", "")
+            is_new = register_project(
+                project_dir,
+                profile=profile or "standard",
+                extends=extends_source,
+            )
+            if is_new:
+                print(f"  Registered project in ~/.ai-toolkit/projects.json")
+
     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/install_steps/project_registry.py

@@ -0,0 +1,142 @@
+"""Project registry — tracks which directories have ai-toolkit installed locally.
+
+Stores registry in ~/.ai-toolkit/projects.json.
+Used by `ai-toolkit update` to propagate updates to all registered projects,
+and by `ai-toolkit projects` to list/manage them.
+
+Stdlib-only — no external dependencies.
+"""
+from __future__ import annotations
+
+import json
+import os
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+
+REGISTRY_FILENAME = "projects.json"
+
+
+def _registry_path() -> Path:
+    """Return the canonical path to projects.json."""
+    return Path(os.environ.get("AI_TOOLKIT_HOME", Path.home() / ".ai-toolkit")) / REGISTRY_FILENAME
+
+
+def _now_iso() -> str:
+    return datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+
+# ---------------------------------------------------------------------------
+# Load / Save
+# ---------------------------------------------------------------------------
+
+def load_registry() -> list[dict[str, Any]]:
+    """Load project registry. Returns empty list if missing/corrupt."""
+    path = _registry_path()
+    if not path.is_file():
+        return []
+    try:
+        with open(path, encoding="utf-8") as f:
+            data = json.load(f)
+        if isinstance(data, dict):
+            projects = data.get("projects", [])
+            return projects if isinstance(projects, list) else []
+        return []
+    except (json.JSONDecodeError, OSError):
+        return []
+
+
+def save_registry(projects: list[dict[str, Any]]) -> None:
+    """Save project registry."""
+    path = _registry_path()
+    path.parent.mkdir(parents=True, exist_ok=True)
+    with open(path, "w", encoding="utf-8") as f:
+        json.dump({"projects": projects}, f, indent=2)
+        f.write("\n")
+
+
+# ---------------------------------------------------------------------------
+# CRUD
+# ---------------------------------------------------------------------------
+
+def register_project(
+    project_path: str | Path,
+    profile: str = "",
+    extends: str = "",
+) -> bool:
+    """Register a project directory. Returns True if newly added, False if updated.
+
+    Idempotent — updates existing entry if path already registered.
+    """
+    project_path = str(Path(project_path).resolve())
+    projects = load_registry()
+    now = _now_iso()
+
+    for p in projects:
+        if p.get("path") == project_path:
+            # Update existing
+            p["last_updated"] = now
+            if profile:
+                p["profile"] = profile
+            if extends:
+                p["extends"] = extends
+            elif "extends" in p and not extends:
+                # Clear extends if project no longer uses it
+                pass
+            save_registry(projects)
+            return False
+
+    # New registration
+    projects.append({
+        "path": project_path,
+        "registered_at": now,
+        "last_updated": now,
+        "profile": profile or "standard",
+        "extends": extends or "",
+    })
+    save_registry(projects)
+    return True
+
+
+def unregister_project(project_path: str | Path) -> bool:
+    """Unregister a project. Returns True if found and removed."""
+    project_path = str(Path(project_path).resolve())
+    projects = load_registry()
+    original_len = len(projects)
+    projects = [p for p in projects if p.get("path") != project_path]
+    if len(projects) < original_len:
+        save_registry(projects)
+        return True
+    return False
+
+
+def list_projects() -> list[dict[str, Any]]:
+    """List all registered projects with existence status."""
+    projects = load_registry()
+    for p in projects:
+        p["exists"] = Path(p["path"]).is_dir()
+    return projects
+
+
+def prune_stale() -> list[str]:
+    """Remove projects whose directories no longer exist. Returns pruned paths."""
+    projects = load_registry()
+    pruned: list[str] = []
+    kept: list[dict[str, Any]] = []
+
+    for p in projects:
+        if Path(p["path"]).is_dir():
+            kept.append(p)
+        else:
+            pruned.append(p["path"])
+
+    if pruned:
+        save_registry(kept)
+
+    return pruned
+
+
+def get_active_projects() -> list[dict[str, Any]]:
+    """Get registered projects that still exist on disk."""
+    return [p for p in load_registry() if Path(p["path"]).is_dir()]

package/scripts/projects_cli.py

@@ -0,0 +1,110 @@
+#!/usr/bin/env python3
+"""CLI for managing the ai-toolkit project registry.
+
+Usage:
+    ai-toolkit projects                — List all registered projects
+    ai-toolkit projects --prune        — Remove stale (deleted) projects
+    ai-toolkit projects remove <path>  — Unregister a specific project
+
+Stdlib-only — no external dependencies.
+"""
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+from install_steps.project_registry import (
+    list_projects,
+    prune_stale,
+    unregister_project,
+)
+
+
+def main() -> None:
+    args = sys.argv[1:]
+
+    if not args or args == []:
+        cmd_list()
+    elif args[0] == "--prune":
+        cmd_prune()
+    elif args[0] == "remove" and len(args) >= 2:
+        cmd_remove(args[1])
+    elif args[0] in ("--help", "-h", "help"):
+        cmd_help()
+    else:
+        print(f"Unknown: {' '.join(args)}", file=sys.stderr)
+        cmd_help()
+        sys.exit(1)
+
+
+def cmd_list() -> None:
+    """List all registered projects."""
+    projects = list_projects()
+
+    if not projects:
+        print("  No registered projects.")
+        print("  Run 'ai-toolkit install --local' in a project to register it.")
+        return
+
+    print(f"  Registered projects ({len(projects)}):")
+    print()
+
+    for p in projects:
+        path_short = p["path"].replace(str(Path.home()), "~")
+        status = "✓" if p["exists"] else "✗ MISSING"
+        profile = p.get("profile", "")
+        extends = p.get("extends", "")
+        updated = p.get("last_updated", "")
+
+        print(f"  {status}  {path_short}")
+        details = []
+        if profile:
+            details.append(f"profile: {profile}")
+        if extends:
+            details.append(f"extends: {extends}")
+        if updated:
+            details.append(f"updated: {updated}")
+        if details:
+            print(f"        {' | '.join(details)}")
+
+    stale = [p for p in projects if not p["exists"]]
+    if stale:
+        print()
+        print(f"  {len(stale)} stale project(s). Run 'ai-toolkit projects --prune' to clean up.")
+
+
+def cmd_prune() -> None:
+    """Remove stale projects."""
+    pruned = prune_stale()
+    if pruned:
+        for p in pruned:
+            path_short = p.replace(str(Path.home()), "~")
+            print(f"  Pruned: {path_short}")
+        print(f"  Removed {len(pruned)} stale project(s).")
+    else:
+        print("  No stale projects found.")
+
+
+def cmd_remove(project_path: str) -> None:
+    """Unregister a specific project."""
+    resolved = Path(project_path).resolve()
+    if unregister_project(resolved):
+        path_short = str(resolved).replace(str(Path.home()), "~")
+        print(f"  Removed: {path_short}")
+    else:
+        print(f"  Not found in registry: {project_path}")
+        sys.exit(1)
+
+
+def cmd_help() -> None:
+    print("Usage: ai-toolkit projects [command]")
+    print()
+    print("Commands:")
+    print("  (none)          List all registered projects")
+    print("  --prune         Remove projects whose directories no longer exist")
+    print("  remove <path>   Unregister a specific project")
+
+
+if __name__ == "__main__":
+    main()