@softspark/ai-toolkit 1.0.0

package/scripts/inject_rule_cli.py

@@ -0,0 +1,101 @@
+#!/usr/bin/env python3
+"""CLI wrapper around inject_rule() and remove_rule_section() from _common.
+
+Injects a rule file into CLAUDE.md using idempotent marker-based injection.
+Re-running updates only the marked section. Content outside markers is
+never touched.
+
+Usage:
+  inject_rule_cli.py <rule-file> [target-dir]
+  inject_rule_cli.py --remove <rule-name> [target-dir]
+
+Arguments:
+  rule-file   Path to a .md file with the rule content
+  target-dir  Directory containing .claude/CLAUDE.md (default: $HOME)
+
+Flags:
+  --remove    Remove a rule section instead of injecting
+"""
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+from _common import inject_rule, remove_rule_section
+
+
+def _parse_args(argv: list[str]) -> dict:
+    """Parse CLI arguments."""
+    result: dict = {
+        "remove_mode": False,
+        "remove_name": "",
+        "source_file": "",
+        "target_dir": str(Path.home()),
+    }
+
+    i = 0
+    while i < len(argv):
+        arg = argv[i]
+        if arg == "--remove":
+            result["remove_mode"] = True
+            i += 1
+            if i >= len(argv):
+                print("--remove requires a rule name", file=sys.stderr)
+                sys.exit(1)
+            result["remove_name"] = argv[i]
+        elif arg.startswith("-"):
+            print(f"Unknown option: {arg}", file=sys.stderr)
+            sys.exit(1)
+        elif not result["source_file"] and not result["remove_mode"]:
+            result["source_file"] = arg
+        else:
+            result["target_dir"] = arg
+        i += 1
+
+    return result
+
+
+def main() -> None:
+    """Inject or remove a rule in CLAUDE.md."""
+    args = _parse_args(sys.argv[1:])
+    target_dir = Path(args["target_dir"])
+    claude_md = target_dir / ".claude" / "CLAUDE.md"
+
+    # -- remove mode ---------------------------------------------------------
+    if args["remove_mode"]:
+        rule_name = args["remove_name"]
+        if not claude_md.is_file():
+            print(f"No CLAUDE.md found at {target_dir}", file=sys.stderr)
+            sys.exit(1)
+
+        found = remove_rule_section(rule_name, target_dir)
+        if found:
+            print(f"Removed rule '{rule_name}' from {claude_md}")
+        else:
+            print(f"Rule '{rule_name}' not found in {claude_md}")
+        return
+
+    # -- inject mode ---------------------------------------------------------
+    source_file = args["source_file"]
+    if not source_file:
+        print("Usage: inject_rule_cli.py <rule-file> [target-dir]", file=sys.stderr)
+        print("       inject_rule_cli.py --remove <rule-name> [target-dir]", file=sys.stderr)
+        sys.exit(1)
+
+    source_path = Path(source_file)
+    if not source_path.is_file():
+        print(f"Rule file not found: {source_path}", file=sys.stderr)
+        sys.exit(1)
+
+    # Ensure .claude/ directory and CLAUDE.md exist
+    claude_md.parent.mkdir(parents=True, exist_ok=True)
+    if not claude_md.is_file():
+        print(f"Created: {claude_md}")
+
+    action = inject_rule(source_path, target_dir)
+    print(f"  {action}: {claude_md}")
+
+
+if __name__ == "__main__":
+    main()

package/scripts/inject_section_cli.py

@@ -0,0 +1,47 @@
+#!/usr/bin/env python3
+"""CLI wrapper around inject_section() from _common.
+
+Injects content between TOOLKIT markers into any file.
+Existing content outside the markers is preserved -- never overwritten.
+Re-running updates only the marked section (idempotent).
+
+Usage:
+  inject_section_cli.py <content-file> <target-file> [section-name]
+
+Arguments:
+  content-file  Path to file with content to inject
+  target-file   Path to target file (created if missing)
+  section-name  Marker label (default: ai-toolkit)
+"""
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+from _common import inject_section
+
+
+def main() -> None:
+    """Inject a content file into a target file between TOOLKIT markers."""
+    if len(sys.argv) < 3:
+        print(
+            "Usage: inject_section_cli.py <content-file> <target-file> [section-name]",
+            file=sys.stderr,
+        )
+        sys.exit(1)
+
+    content_file = Path(sys.argv[1])
+    target_file = Path(sys.argv[2])
+    section = sys.argv[3] if len(sys.argv) > 3 else "ai-toolkit"
+
+    if not content_file.is_file():
+        print(f"Content file not found: {content_file}", file=sys.stderr)
+        sys.exit(1)
+
+    action = inject_section(content_file, target_file, section)
+    print(f"  {action}: {target_file}")
+
+
+if __name__ == "__main__":
+    main()

package/scripts/injection.py

@@ -0,0 +1,180 @@
+"""Marker-based section injection and rule management.
+
+Handles idempotent injection of content between TOOLKIT markers
+into target files. Also manages rule injection into CLAUDE.md.
+
+Stdlib-only.
+
+Usage::
+
+    from injection import inject_section, inject_rule, remove_rule_section
+"""
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+
+# ---------------------------------------------------------------------------
+# Markers
+# ---------------------------------------------------------------------------
+
+def markers_start(section: str = "ai-toolkit") -> str:
+    """Return the TOOLKIT start marker block."""
+    return (
+        f"<!-- TOOLKIT:{section} START -->\n"
+        f"<!-- Auto-injected by ai-toolkit. Re-run to update. -->\n"
+    )
+
+
+def markers_end(section: str = "ai-toolkit") -> str:
+    """Return the TOOLKIT end marker."""
+    return f"\n<!-- TOOLKIT:{section} END -->"
+
+
+# ---------------------------------------------------------------------------
+# Internal helpers
+# ---------------------------------------------------------------------------
+
+def strip_section(content: str, section: str) -> str:
+    """Remove a TOOLKIT marker section from content."""
+    start = f"<!-- TOOLKIT:{section} START -->"
+    end = f"<!-- TOOLKIT:{section} END -->"
+    lines: list[str] = []
+    skip = False
+    for line in content.splitlines(keepends=True):
+        stripped = line.rstrip("\n")
+        if stripped == start:
+            skip = True
+            continue
+        if stripped == end:
+            skip = False
+            continue
+        if not skip:
+            lines.append(line)
+    return "".join(lines)
+
+
+def trim_trailing_blanks(text: str) -> str:
+    """Remove trailing blank lines from text."""
+    lines = text.splitlines()
+    while lines and not lines[-1].strip():
+        lines.pop()
+    return "\n".join(lines)
+
+
+def collapse_blank_runs(text: str, max_blanks: int = 2) -> str:
+    """Collapse runs of more than max_blanks consecutive blank lines."""
+    lines = text.splitlines(keepends=True)
+    result: list[str] = []
+    blanks = 0
+    for line in lines:
+        if not line.strip():
+            blanks += 1
+            if blanks <= max_blanks:
+                result.append(line)
+        else:
+            blanks = 0
+            result.append(line)
+    return "".join(result)
+
+
+# ---------------------------------------------------------------------------
+# Public API
+# ---------------------------------------------------------------------------
+
+def inject_section(
+    content_file: str | Path,
+    target_file: str | Path,
+    section: str = "ai-toolkit",
+) -> str:
+    """Inject content between TOOLKIT markers into target file.
+
+    Existing content outside markers is preserved. Re-running updates
+    only the marked section (idempotent).
+
+    Returns action taken: "Created" or "Updated".
+    """
+    content_file = Path(content_file)
+    target_file = Path(target_file)
+
+    # Sanitize section name
+    section = re.sub(r"[^a-zA-Z0-9_-]", "", section)
+
+    # Create parent dir and target if missing
+    target_file.parent.mkdir(parents=True, exist_ok=True)
+    if not target_file.exists():
+        target_file.touch()
+        action = "Created"
+    else:
+        action = "Updated"
+
+    # Read existing content
+    existing = target_file.read_text(encoding="utf-8")
+
+    # Strip existing section
+    existing = strip_section(existing, section)
+    existing = trim_trailing_blanks(existing)
+
+    # Read content to inject
+    new_content = content_file.read_text(encoding="utf-8")
+
+    # Build output
+    parts: list[str] = []
+    if existing.strip():
+        parts.append(existing)
+        parts.append("")
+
+    parts.append(f"<!-- TOOLKIT:{section} START -->")
+    parts.append("<!-- Auto-injected by ai-toolkit. Re-run to update. -->")
+    parts.append("")
+    parts.append(new_content.rstrip("\n"))
+    parts.append("")
+    parts.append(f"<!-- TOOLKIT:{section} END -->")
+
+    output = "\n".join(parts) + "\n"
+    output = collapse_blank_runs(output)
+
+    target_file.write_text(output, encoding="utf-8")
+    return action
+
+
+def inject_rule(rule_file: str | Path, target_dir: str | Path) -> str:
+    """Inject a rule file into target_dir/.claude/CLAUDE.md.
+
+    Returns action taken.
+    """
+    rule_file = Path(rule_file)
+    target_dir = Path(target_dir)
+
+    if not rule_file.is_file():
+        raise FileNotFoundError(f"Rule file not found: {rule_file}")
+
+    rule_name = re.sub(r"[^a-zA-Z0-9_-]", "", rule_file.stem)
+    claude_md = target_dir / ".claude" / "CLAUDE.md"
+    claude_md.parent.mkdir(parents=True, exist_ok=True)
+
+    return inject_section(rule_file, claude_md, rule_name)
+
+
+def remove_rule_section(rule_name: str, target_dir: str | Path) -> bool:
+    """Remove a rule section from target_dir/.claude/CLAUDE.md.
+
+    Returns True if section was found and removed.
+    """
+    target_dir = Path(target_dir)
+    claude_md = target_dir / ".claude" / "CLAUDE.md"
+
+    if not claude_md.is_file():
+        return False
+
+    content = claude_md.read_text(encoding="utf-8")
+    start_marker = f"<!-- TOOLKIT:{rule_name} START -->"
+
+    if start_marker not in content:
+        return False
+
+    content = strip_section(content, rule_name)
+    content = trim_trailing_blanks(content) + "\n"
+    claude_md.write_text(content, encoding="utf-8")
+    return True

package/scripts/install.py

@@ -0,0 +1,236 @@
+#!/usr/bin/env python3
+"""AI Toolkit Installer.
+
+Installs toolkit GLOBALLY -- Claude Code + all supported AI tools.
+Re-running is idempotent: updates only marker-delimited sections,
+never touching user content outside the markers.
+
+Claude Code (~/.claude/):
+  - Per-file symlinks: agents/*.md, skills/*/  (merges with user files)
+  - Merged JSON: hooks.json (toolkit entries tagged with _source)
+  - Marker injection: constitution.md, ARCHITECTURE.md (preserves user content)
+  - Rules injected into ~/.claude/CLAUDE.md
+
+Other tools (global config locations):
+  - Cursor:   ~/.cursor/rules
+  - Windsurf: ~/.codeium/windsurf/memories/global_rules.md
+  - Gemini:   ~/.gemini/GEMINI.md
+
+Registered rules (~/.ai-toolkit/rules/*.md) are also injected into
+all of the above. Add rules with: ai-toolkit add-rule <rule.md>
+
+Usage:
+  python3 scripts/install.py [target-dir] [options]
+
+Options:
+  --only agents,hooks     Install only listed components
+  --skip skills           Skip listed components
+  --local                 Also inject into project-local configs
+  --list, --dry-run       Dry-run: show what would be installed
+  --reset                 Wipe and recreate local configs
+  --profile <p>           minimal|standard|strict
+
+Components: agents, skills, hooks, constitution, architecture, rules,
+            cursor, windsurf, gemini
+"""
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+from _common import toolkit_dir
+from emission import agent_count as count_agents, skill_count as count_skills
+
+# Step modules
+from install_steps.symlinks import install_agents, install_skills, clean_legacy_commands
+from install_steps.hooks import install_hooks
+from install_steps.markers import install_marker_files, inject_rules
+from install_steps.ai_tools import install_ai_tools, install_local_project, run_script
+
+
+# ---------------------------------------------------------------------------
+# Argument parsing
+# ---------------------------------------------------------------------------
+
+def parse_args(argv: list[str]) -> dict:
+    """Parse CLI arguments into a config dict."""
+    cfg: dict = {
+        "target_dir": Path.home(),
+        "only": "",
+        "skip": "",
+        "dry_run": False,
+        "local": False,
+        "reset": False,
+        "profile": "",
+    }
+    i = 0
+    while i < len(argv):
+        arg = argv[i]
+        if arg in ("--list", "--dry-run"):
+            cfg["dry_run"] = True
+        elif arg == "--local":
+            cfg["local"] = True
+        elif arg == "--reset":
+            cfg["reset"] = True
+        elif arg.startswith("--only="):
+            cfg["only"] = arg.split("=", 1)[1]
+        elif arg == "--only":
+            i += 1
+            cfg["only"] = argv[i] if i < len(argv) else ""
+        elif arg.startswith("--skip="):
+            cfg["skip"] = arg.split("=", 1)[1]
+        elif arg == "--skip":
+            i += 1
+            cfg["skip"] = argv[i] if i < len(argv) else ""
+        elif arg.startswith("--profile="):
+            cfg["profile"] = arg.split("=", 1)[1]
+        elif arg == "--profile":
+            i += 1
+            cfg["profile"] = argv[i] if i < len(argv) else ""
+        elif arg.startswith("-"):
+            print(f"Unknown option: {arg}")
+            sys.exit(1)
+        else:
+            cfg["target_dir"] = Path(arg)
+        i += 1
+    return cfg
+
+
+# ---------------------------------------------------------------------------
+# Dependency check
+# ---------------------------------------------------------------------------
+
+def check_dependencies() -> None:
+    """Run check_deps and abort if any required dep is missing."""
+    from check_deps import check_deps
+
+    results = check_deps(verbose=False)
+    if not results["all_ok"]:
+        from check_deps import print_report
+        print_report(results)
+        print("Aborting install: missing required dependencies.")
+        sys.exit(1)
+
+
+# ---------------------------------------------------------------------------
+# Profile / Banner / Summary
+# ---------------------------------------------------------------------------
+
+def resolve_profile(profile: str, only: str) -> str:
+    if profile == "minimal":
+        if not only:
+            return "agents,skills"
+    elif profile in ("standard", ""):
+        pass
+    elif profile == "strict":
+        pass
+    else:
+        print(f"Unknown profile: {profile} (valid: minimal, standard, strict)")
+        sys.exit(1)
+    return only
+
+
+def print_banner(target_dir: Path, rules_dir: Path, profile: str,
+                 only: str, skip: str, dry_run: bool) -> None:
+    print("AI Toolkit Installer")
+    print("========================")
+    print(f"Toolkit:   {toolkit_dir}")
+    print(f"Target:    {target_dir.resolve()}")
+    print(f"Rules:     {rules_dir}")
+    if profile:
+        print(f"Profile:   {profile}")
+    if only:
+        print(f"Only:      {only}")
+    if skip:
+        print(f"Skip:      {skip}")
+    if dry_run:
+        print("Mode:      DRY-RUN (no changes)")
+    print()
+
+
+def print_summary() -> None:
+    print()
+    print("Done.")
+    print()
+    print("Next steps:")
+    print("  1. Edit ~/.claude/CLAUDE.md -- add your global rules above the toolkit sections")
+    print("  2. Per project: ai-toolkit install --local (or: ai-toolkit update --local)")
+    print("  3. To update: npm install -g @softspark/ai-toolkit@latest && ai-toolkit update")
+    print("  4. To register rules from other tools: ai-toolkit add-rule <rule.md>")
+
+
+# ---------------------------------------------------------------------------
+# Install Claude Code (orchestrator)
+# ---------------------------------------------------------------------------
+
+def install_claude_code(target_dir: Path, hooks_scripts_dir: Path,
+                        rules_dir: Path, only: str, skip: str,
+                        dry_run: bool) -> None:
+    print("## Claude Code (~/.claude/)")
+    print()
+
+    claude_dir = target_dir / ".claude"
+    claude_dir.mkdir(parents=True, exist_ok=True)
+
+    install_agents(claude_dir, only, skip, dry_run)
+    install_skills(claude_dir, only, skip, dry_run)
+    clean_legacy_commands(claude_dir, dry_run)
+    install_hooks(claude_dir, hooks_scripts_dir, only, skip, dry_run)
+    install_marker_files(claude_dir, only, skip, dry_run)
+
+    if not dry_run:
+        print("  Note: settings.local.json is project-specific -- use 'ai-toolkit install --local' per project")
+
+    print()
+    print(f"  Available: {count_agents()} agents, {count_skills()} skills")
+
+    inject_rules(claude_dir, target_dir, rules_dir, only, skip, dry_run)
+
+
+def install_strict_git_hooks(profile: str, local: bool, dry_run: bool) -> None:
+    if profile == "strict" and not local and not dry_run:
+        cwd = Path.cwd()
+        if (cwd / ".git").is_dir():
+            run_script("install-git-hooks.sh", str(cwd))
+            print(f"  Strict profile: git hooks installed in {cwd}")
+
+
+# ---------------------------------------------------------------------------
+# Main
+# ---------------------------------------------------------------------------
+
+def main() -> None:
+    cfg = parse_args(sys.argv[1:])
+
+    target_dir: Path = cfg["target_dir"]
+    only: str = cfg["only"]
+    skip: str = cfg["skip"]
+    dry_run: bool = cfg["dry_run"]
+    local: bool = cfg["local"]
+    reset: bool = cfg["reset"]
+    profile: str = cfg["profile"]
+
+    rules_dir = Path.home() / ".ai-toolkit" / "rules"
+    hooks_scripts_dir = Path.home() / ".ai-toolkit" / "hooks"
+
+    only = resolve_profile(profile, only)
+    check_dependencies()
+    print_banner(target_dir, rules_dir, profile, only, skip, dry_run)
+
+    if not dry_run:
+        rules_dir.mkdir(parents=True, exist_ok=True)
+        hooks_scripts_dir.mkdir(parents=True, exist_ok=True)
+
+    install_claude_code(target_dir, hooks_scripts_dir, rules_dir, only, skip, dry_run)
+    install_ai_tools(target_dir, rules_dir, only, skip, dry_run)
+
+    if local:
+        install_local_project(rules_dir, dry_run, reset)
+
+    install_strict_git_hooks(profile, local, dry_run)
+    print_summary()
+
+
+if __name__ == "__main__":
+    main()

package/scripts/install_git_hooks.py

@@ -0,0 +1,71 @@
+#!/usr/bin/env python3
+"""Install a fallback pre-commit hook for the ai-toolkit.
+
+Used for non-Claude editors to enforce the constitution and quality gates.
+
+Usage: python3 install_git_hooks.py [target-dir]
+"""
+from __future__ import annotations
+
+import os
+import sys
+from pathlib import Path
+
+PRE_COMMIT_CONTENT = """\
+#!/usr/bin/env bash
+# ai-toolkit fallback pre-commit hook
+# Auto-generated by ai-toolkit.
+
+# This hook acts as a safety fallback to ensure AI-generated commits
+# aren't bypassing standard quality checks (like unresolved conflicts or missing tests)
+# when using editors without native bash process hooks (like Cursor or Windsurf).
+
+echo "[ai-toolkit] Running pre-commit quality gate..."
+
+# 1. Check for unresolved merge conflicts
+if git diff --cached -S'<<<<<<<' --name-only | grep -q '.*'; then
+    echo "ERROR: Unresolved merge conflicts found in staged files."
+    echo "   Please resolve conflicts and remove '<<<<<<<' markers before committing."
+    exit 1
+fi
+
+# 2. Call the global quality-check if it exists
+QUALITY_CHECK="$HOME/.ai-toolkit/hooks/quality-check.sh"
+if [ -x "$QUALITY_CHECK" ]; then
+    if ! "$QUALITY_CHECK"; then
+        echo "ERROR: Linter or type checks failed."
+        echo "   Use 'git commit --no-verify' if you absolutely must bypass this."
+        exit 1
+    fi
+fi
+
+echo "[ai-toolkit] Pre-commit checks passed."
+exit 0
+"""
+
+
+def main() -> None:
+    target_dir = Path(sys.argv[1]) if len(sys.argv) > 1 else Path.cwd()
+    git_hooks_dir = target_dir / ".git" / "hooks"
+
+    if not git_hooks_dir.is_dir():
+        print("  Skipped: git hooks (not a git repository)")
+        return
+
+    pre_commit = git_hooks_dir / "pre-commit"
+
+    # Back up existing pre-commit hook if not ours
+    if pre_commit.is_file():
+        content = pre_commit.read_text(encoding="utf-8", errors="replace")
+        if "ai-toolkit fallback pre-commit hook" not in content:
+            backup = git_hooks_dir / "pre-commit.backup"
+            pre_commit.rename(backup)
+            print("  Backed up existing pre-commit hook to pre-commit.backup")
+
+    pre_commit.write_text(PRE_COMMIT_CONTENT, encoding="utf-8")
+    pre_commit.chmod(pre_commit.stat().st_mode | 0o111)
+    print("  Installed: .git/hooks/pre-commit (ai-toolkit safety fallback)")
+
+
+if __name__ == "__main__":
+    main()

package/scripts/install_steps/__init__.py

@@ -0,0 +1,5 @@
+"""Install step modules.
+
+Each module handles one installation concern.
+Imported by install.py as the orchestrator.
+"""