@softspark/ai-toolkit 1.7.0 → 1.9.0

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."
+    }
+  }
+}

package/scripts/update_projects.py

@@ -0,0 +1,141 @@
+#!/usr/bin/env python3
+"""Update all registered projects in parallel.
+
+Reads ~/.ai-toolkit/projects.json and runs install.py --local in each
+project directory concurrently using a thread pool.
+
+Stdlib-only — no external dependencies.
+"""
+from __future__ import annotations
+
+import json
+import subprocess
+import sys
+import time
+from concurrent.futures import ThreadPoolExecutor, as_completed
+from pathlib import Path
+from typing import Any
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+from install_steps.project_registry import get_active_projects, prune_stale
+
+
+def _update_project(project: dict[str, Any], install_script: str, extra_args: list[str]) -> dict:
+    """Run install --local in a single project. Returns result dict."""
+    project_path = project["path"]
+    start = time.monotonic()
+
+    try:
+        proc = subprocess.run(
+            ["python3", install_script, "--local"] + extra_args,
+            cwd=project_path,
+            capture_output=True,
+            text=True,
+            timeout=120,
+        )
+        elapsed = time.monotonic() - start
+        return {
+            "path": project_path,
+            "profile": project.get("profile", ""),
+            "extends": project.get("extends", ""),
+            "success": proc.returncode == 0,
+            "elapsed": round(elapsed, 1),
+            "output": proc.stdout,
+            "error": proc.stderr if proc.returncode != 0 else "",
+        }
+    except subprocess.TimeoutExpired:
+        return {
+            "path": project_path,
+            "success": False,
+            "elapsed": 120.0,
+            "output": "",
+            "error": "Timed out after 120s",
+        }
+    except OSError as e:
+        return {
+            "path": project_path,
+            "success": False,
+            "elapsed": 0,
+            "output": "",
+            "error": str(e),
+        }
+
+
+def main() -> None:
+    """Update all registered projects."""
+    # Parse args
+    verbose = "--verbose" in sys.argv or "-v" in sys.argv
+    json_output = "--json" in sys.argv
+    extra_args = [a for a in sys.argv[1:] if a not in ("--verbose", "-v", "--json")]
+
+    # Prune stale projects first
+    pruned = prune_stale()
+    if pruned and not json_output:
+        for p in pruned:
+            print(f"  Pruned stale project: {p}")
+
+    # Get active projects
+    projects = get_active_projects()
+
+    if not projects:
+        if json_output:
+            print(json.dumps({"projects": [], "summary": "No registered projects"}))
+        else:
+            print("  No registered projects.")
+            print("  Run 'ai-toolkit install --local' in a project to register it.")
+        sys.exit(0)
+
+    install_script = str(Path(__file__).resolve().parent / "install.py")
+
+    if not json_output:
+        print(f"  Updating {len(projects)} registered project(s)...")
+        print()
+
+    # Run in parallel (max 8 workers — don't overwhelm the system)
+    max_workers = min(len(projects), 8)
+    results: list[dict] = []
+
+    with ThreadPoolExecutor(max_workers=max_workers) as pool:
+        futures = {
+            pool.submit(_update_project, p, install_script, extra_args): p
+            for p in projects
+        }
+        for future in as_completed(futures):
+            result = future.result()
+            results.append(result)
+
+            if not json_output:
+                status = "✓" if result["success"] else "✗"
+                path_short = result["path"].replace(str(Path.home()), "~")
+                extends_info = f" (extends: {result.get('extends', '')})" if result.get("extends") else ""
+                print(f"  {status} {path_short}{extends_info} ({result['elapsed']}s)")
+
+                if verbose and result["output"]:
+                    for line in result["output"].strip().split("\n"):
+                        print(f"      {line}")
+
+                if result.get("error"):
+                    for line in result["error"].strip().split("\n"):
+                        print(f"      ERROR: {line}")
+
+    # Summary
+    passed = sum(1 for r in results if r["success"])
+    failed = len(results) - passed
+
+    if json_output:
+        print(json.dumps({
+            "projects": results,
+            "total": len(results),
+            "passed": passed,
+            "failed": failed,
+        }, indent=2))
+    else:
+        print()
+        print(f"  Updated: {passed}/{len(results)} projects" +
+              (f" ({failed} failed)" if failed else ""))
+
+    sys.exit(1 if failed else 0)
+
+
+if __name__ == "__main__":
+    main()