@softspark/ai-toolkit 1.0.0

package/scripts/install_steps/ai_tools.py

@@ -0,0 +1,261 @@
+"""Install AI tool configs (Cursor, Windsurf, Gemini) and local project setup."""
+from __future__ import annotations
+
+import shutil
+import subprocess
+from pathlib import Path
+
+from _common import app_dir, inject_section, should_install, toolkit_dir
+from injection import (
+    collapse_blank_runs as _collapse_blank_runs,
+    strip_section as _strip_section,
+    trim_trailing_blanks as _trim_trailing_blanks,
+)
+
+
+def install_ai_tools(target_dir: Path, rules_dir: Path,
+                     only: str, skip: str, dry_run: bool) -> None:
+    """Install Cursor, Windsurf, Gemini global configs."""
+    print()
+    print("## Other AI Tools (global)")
+    print()
+
+    if should_install("cursor", only, skip):
+        cursor_file = target_dir / ".cursor" / "rules"
+        if dry_run:
+            print("  Would inject: ~/.cursor/rules")
+        else:
+            inject_with_rules("generate-cursor-rules.sh", cursor_file, rules_dir)
+    else:
+        print("  Skipped: cursor")
+
+    if should_install("windsurf", only, skip):
+        windsurf_file = target_dir / ".codeium" / "windsurf" / "memories" / "global_rules.md"
+        if dry_run:
+            print("  Would inject: ~/.codeium/windsurf/memories/global_rules.md")
+        else:
+            inject_with_rules("generate-windsurf.sh", windsurf_file, rules_dir)
+    else:
+        print("  Skipped: windsurf")
+
+    if should_install("gemini", only, skip):
+        gemini_file = target_dir / ".gemini" / "GEMINI.md"
+        if dry_run:
+            print("  Would inject: ~/.gemini/GEMINI.md")
+        else:
+            inject_with_rules("generate-gemini.sh", gemini_file, rules_dir)
+    else:
+        print("  Skipped: gemini")
+
+    print()
+    print("  Note: Copilot, Cline, Roo Code, and Aider have no global config -- use 'ai-toolkit install --local' per project")
+
+
+def inject_with_rules(
+    generator_script: str,
+    target_file: Path,
+    rules_dir: Path,
+) -> None:
+    """Run a generator script, write output, then inject registered rules."""
+    scripts_dir = toolkit_dir / "scripts"
+    py_name = generator_script.replace(".sh", ".py").replace("-", "_")
+    if (scripts_dir / py_name).is_file():
+        cmd = ["python3", str(scripts_dir / py_name)]
+    else:
+        cmd = ["bash", str(scripts_dir / generator_script)]
+
+    result = subprocess.run(cmd, capture_output=True, text=True)
+    if result.returncode != 0:
+        print(f"  ERROR: {generator_script} failed: {result.stderr.strip()}")
+        return
+
+    generated = result.stdout
+    start_marker = "<!-- TOOLKIT:ai-toolkit START -->"
+
+    target_file = Path(target_file)
+    target_file.parent.mkdir(parents=True, exist_ok=True)
+    if not target_file.exists():
+        target_file.touch()
+
+    existing = target_file.read_text(encoding="utf-8")
+    if start_marker in existing:
+        existing = _strip_section(existing, "ai-toolkit")
+    existing = _trim_trailing_blanks(existing)
+
+    parts: list[str] = []
+    if existing.strip():
+        parts.append(existing)
+        parts.append("")
+    parts.append(generated.rstrip("\n"))
+
+    output = "\n".join(parts) + "\n"
+    output = _collapse_blank_runs(output)
+    target_file.write_text(output, encoding="utf-8")
+
+    if rules_dir.is_dir():
+        for rule_file in sorted(rules_dir.glob("*.md")):
+            inject_section(rule_file, target_file, rule_file.stem)
+
+    print(f"  Updated: {target_file}")
+
+
+def run_script(script_name: str, *args: str, capture: bool = False) -> str:
+    """Run a script from the scripts/ directory (prefers .py over .sh)."""
+    scripts_dir = toolkit_dir / "scripts"
+    py_name = script_name.replace(".sh", ".py").replace("-", "_")
+    if (scripts_dir / py_name).is_file():
+        cmd = ["python3", str(scripts_dir / py_name), *args]
+    else:
+        cmd = ["bash", str(scripts_dir / script_name), *args]
+    result = subprocess.run(cmd, capture_output=capture, text=True)
+    return result.stdout if capture else ""
+
+
+def install_local_project(rules_dir: Path, dry_run: bool, reset: bool) -> None:
+    """Install project-local configs."""
+    cwd = Path.cwd()
+    print()
+    print(f"## Project-local ({cwd})")
+    if reset:
+        print("   Mode: RESET (all local configs will be wiped and recreated)")
+    print()
+
+    if dry_run:
+        _install_local_dry_run(reset)
+        return
+
+    (cwd / ".claude").mkdir(parents=True, exist_ok=True)
+
+    if reset:
+        _reset_local_configs(cwd)
+
+    _create_local_claude_md(cwd, reset)
+    _create_local_settings(cwd, reset)
+
+    legacy_local_hooks = cwd / ".claude" / "hooks.json"
+    if legacy_local_hooks.is_file():
+        legacy_local_hooks.unlink()
+        print("  Removed: .claude/hooks.json (legacy)")
+    print("  Note: hooks are merged into global ~/.claude/settings.json only (not project-local)")
+
+    constitution_src = app_dir / "constitution.md"
+    if constitution_src.is_file():
+        inject_section(
+            constitution_src,
+            cwd / ".claude" / "constitution.md",
+            "constitution",
+        )
+        print("  Injected: .claude/constitution.md")
+
+    _create_local_ai_tool_configs(cwd, rules_dir)
+
+
+def _install_local_dry_run(reset: bool) -> None:
+    if reset:
+        print("  Would remove: CLAUDE.md, .claude/settings.local.json")
+        print("  Would remove: .claude/constitution.md, .github/copilot-instructions.md, .clinerules, .roomodes, .aider.conf.yml")
+        print("  Would recreate all from templates (clean slate)")
+        print("  Would install git hooks (if .git/hooks exists)")
+    else:
+        print("  Would create: CLAUDE.md (if missing)")
+        print("  Would create: .claude/settings.local.json (if missing)")
+        print("  Would inject: .claude/constitution.md")
+        print("  Would inject: .github/copilot-instructions.md")
+        print("  Would inject: .clinerules")
+        print("  Would inject: .roomodes")
+        print("  Would inject: .aider.conf.yml")
+        print("  Would install: .git/hooks/pre-commit")
+
+
+def _reset_local_configs(cwd: Path) -> None:
+    for rel in (
+        "CLAUDE.md",
+        ".claude/settings.local.json",
+        ".claude/constitution.md",
+        ".github/copilot-instructions.md",
+        ".clinerules",
+        ".roomodes",
+        ".aider.conf.yml",
+    ):
+        p = cwd / rel
+        if p.is_file():
+            p.unlink()
+            print(f"  Removed: {rel}")
+
+
+def _create_local_claude_md(cwd: Path, reset: bool) -> None:
+    claude_local = cwd / "CLAUDE.md"
+    if reset or not claude_local.is_file():
+        template = app_dir / "CLAUDE.md.template"
+        if template.is_file():
+            shutil.copy2(template, claude_local)
+            print("  Created: CLAUDE.md (from template)")
+        else:
+            claude_local.write_text(
+                """\
+# [Project Name]
+
+## Overview
+
+## Tech Stack
+- **Language**:
+- **Framework**:
+- **Database**:
+
+## Commands
+```bash
+# Dev:
+# Test:
+# Lint:
+# Build:
+```
+
+## Key Conventions
+
+## MCP Servers
+""",
+                encoding="utf-8",
+            )
+            print("  Created: CLAUDE.md (default template)")
+    else:
+        print("  Kept: CLAUDE.md (already exists)")
+
+
+def _create_local_settings(cwd: Path, reset: bool) -> None:
+    settings_local = cwd / ".claude" / "settings.local.json"
+    if reset or not settings_local.is_file():
+        mcp_defaults = app_dir / "mcp-defaults.json"
+        if mcp_defaults.is_file():
+            shutil.copy2(mcp_defaults, settings_local)
+            print("  Created: .claude/settings.local.json (from mcp-defaults)")
+        else:
+            settings_local.write_text(
+                '{\n  "mcpServers": {},\n  "env": {}\n}\n',
+                encoding="utf-8",
+            )
+            print("  Created: .claude/settings.local.json")
+    else:
+        print("  Kept: .claude/settings.local.json (already exists)")
+
+
+def _create_local_ai_tool_configs(cwd: Path, rules_dir: Path) -> None:
+    inject_with_rules(
+        "generate-copilot.sh",
+        cwd / ".github" / "copilot-instructions.md",
+        rules_dir,
+    )
+    inject_with_rules(
+        "generate-cline.sh",
+        cwd / ".clinerules",
+        rules_dir,
+    )
+
+    roo_output = run_script("generate-roo-modes.sh", capture=True)
+    (cwd / ".roomodes").write_text(roo_output, encoding="utf-8")
+    print("  Created: .roomodes")
+
+    aider_output = run_script("generate-aider-conf.sh", capture=True)
+    (cwd / ".aider.conf.yml").write_text(aider_output, encoding="utf-8")
+    print("  Created: .aider.conf.yml")
+
+    run_script("install-git-hooks.sh", str(cwd))

package/scripts/install_steps/hooks.py

@@ -0,0 +1,90 @@
+"""Hook installation: copy scripts, merge JSON, output styles."""
+from __future__ import annotations
+
+import json
+import shutil
+import subprocess
+from pathlib import Path
+
+from _common import app_dir, should_install, toolkit_dir
+
+
+def install_hooks(claude_dir: Path, hooks_scripts_dir: Path,
+                  only: str, skip: str, dry_run: bool) -> None:
+    """Install hooks: copy scripts, merge JSON, install output styles."""
+    if not should_install("hooks", only, skip):
+        print("  Skipped: hooks")
+        return
+
+    hooks_json = app_dir / "hooks.json"
+    if not hooks_json.is_file():
+        return
+
+    if dry_run:
+        print("  Would merge: .claude/settings.json hooks (toolkit entries into user settings)")
+        output_styles_dir = app_dir / "output-styles"
+        if output_styles_dir.is_dir():
+            print("  Would install: output styles to ~/.claude/output-styles/ + set outputStyle in settings.json")
+        return
+
+    _copy_hook_scripts(claude_dir, hooks_scripts_dir)
+    _run_merge_hooks(
+        "inject",
+        str(hooks_json),
+        str(claude_dir / "settings.json"),
+    )
+    print("  Merged: .claude/settings.json (hooks)")
+
+    legacy_hooks_json = claude_dir / "hooks.json"
+    if legacy_hooks_json.is_file():
+        legacy_hooks_json.unlink()
+        print("  Removed: .claude/hooks.json (legacy)")
+
+    _install_output_styles(claude_dir)
+
+
+def _copy_hook_scripts(claude_dir: Path, hooks_scripts_dir: Path) -> None:
+    hooks_src = app_dir / "hooks"
+    if not hooks_src.is_dir():
+        return
+    copied = 0
+    for hook_file in sorted(hooks_src.glob("*.sh")):
+        dst = hooks_scripts_dir / hook_file.name
+        shutil.copy2(hook_file, dst)
+        dst.chmod(dst.stat().st_mode | 0o111)
+        copied += 1
+    print(f"  Copied: {copied} hook scripts to ~/.ai-toolkit/hooks/")
+    legacy_hooks = claude_dir / "hooks"
+    if legacy_hooks.is_symlink():
+        legacy_hooks.unlink()
+        print("  Removed: .claude/hooks (legacy symlink)")
+
+
+def _run_merge_hooks(action: str, *args: str) -> None:
+    cmd = ["python3", str(toolkit_dir / "scripts" / "merge-hooks.py"), action, *args]
+    subprocess.run(cmd, check=True)
+
+
+def _install_output_styles(claude_dir: Path) -> None:
+    output_styles_src = app_dir / "output-styles"
+    if not output_styles_src.is_dir():
+        return
+    output_styles_dst = claude_dir / "output-styles"
+    output_styles_dst.mkdir(parents=True, exist_ok=True)
+    styles_copied = 0
+    for style_file in sorted(output_styles_src.glob("*.md")):
+        shutil.copy2(style_file, output_styles_dst / style_file.name)
+        styles_copied += 1
+    if styles_copied > 0:
+        print(f"  Copied: {styles_copied} output style(s) to ~/.claude/output-styles/")
+        settings_path = claude_dir / "settings.json"
+        if settings_path.is_file():
+            with open(settings_path, encoding="utf-8") as f:
+                settings_data = json.load(f)
+        else:
+            settings_data = {}
+        if "outputStyle" not in settings_data:
+            settings_data["outputStyle"] = "Golden Rules"
+            with open(settings_path, "w", encoding="utf-8") as f:
+                json.dump(settings_data, f, indent=4)
+            print("  Set: outputStyle = 'Golden Rules' in settings.json")

package/scripts/install_steps/markers.py

@@ -0,0 +1,79 @@
+"""Marker file injection and rule injection."""
+from __future__ import annotations
+
+from pathlib import Path
+
+from _common import app_dir, inject_rule, inject_section, should_install
+
+
+def install_marker_files(claude_dir: Path, only: str, skip: str,
+                         dry_run: bool) -> None:
+    """Inject constitution.md, ARCHITECTURE.md via markers."""
+    marker_files = [
+        ("constitution.md", "constitution", "constitution"),
+        ("ARCHITECTURE.md", "architecture", "architecture"),
+    ]
+    for filename, component, section in marker_files:
+        if not should_install(component, only, skip):
+            print(f"  Skipped: .claude/{filename}")
+            continue
+        src = app_dir / filename
+        if not src.is_file():
+            continue
+        if dry_run:
+            print(f"  Would inject: .claude/{filename} (marker-based, preserves user content)")
+            continue
+        dst = claude_dir / filename
+        if dst.is_symlink():
+            dst.unlink()
+            print(f"  Upgraded: .claude/{filename} (symlink -> marker injection)")
+        inject_section(src, dst, section)
+        print(f"  Injected: .claude/{filename}")
+
+
+def inject_rules(claude_dir: Path, target_dir: Path, rules_dir: Path,
+                 only: str, skip: str, dry_run: bool) -> None:
+    """Inject rules into CLAUDE.md."""
+    claude_md = claude_dir / "CLAUDE.md"
+
+    if dry_run:
+        _inject_rules_dry_run(rules_dir)
+        return
+
+    if not claude_md.is_file():
+        claude_md.touch()
+        print("  Created: ~/.claude/CLAUDE.md")
+
+    if not should_install("rules", only, skip):
+        print("  Skipped: rules injection")
+
+    rules_injected: list[str] = []
+
+    if rules_dir.is_dir():
+        for rule_file in sorted(rules_dir.glob("*.md")):
+            rule_name = rule_file.stem
+            inject_rule(rule_file, target_dir)
+            rules_injected.append(rule_name)
+
+    if should_install("rules", only, skip):
+        rules_src = app_dir / "rules"
+        if rules_src.is_dir():
+            for source_file in sorted(rules_src.glob("*.md")):
+                rule_name = source_file.stem
+                inject_rule(source_file, target_dir)
+                rules_injected.append(rule_name)
+
+    print(f"  Rules injected: {' '.join(rules_injected)}")
+
+
+def _inject_rules_dry_run(rules_dir: Path) -> None:
+    rules_src = app_dir / "rules"
+    rule_names = " ".join(
+        f.stem for f in sorted(rules_src.glob("*.md"))
+    ) if rules_src.is_dir() else ""
+    print(f"  Would inject rules: {rule_names}")
+    if rules_dir.is_dir():
+        registered = list(rules_dir.glob("*.md"))
+        if registered:
+            reg_names = " ".join(f.stem for f in sorted(registered))
+            print(f"  Would inject registered rules: {reg_names}")

package/scripts/install_steps/symlinks.py

@@ -0,0 +1,87 @@
+"""Agent and skill symlink management."""
+from __future__ import annotations
+
+from pathlib import Path
+
+from _common import app_dir, should_install
+
+
+def install_agents(claude_dir: Path, only: str, skip: str, dry_run: bool) -> None:
+    """Create per-file symlinks for agents."""
+    if not should_install("agents", only, skip):
+        print("  Skipped: .claude/agents")
+        return
+
+    agents_src = app_dir / "agents"
+    if not agents_src.is_dir():
+        return
+
+    if dry_run:
+        print("  Would link: .claude/agents/*.md (per-file merge)")
+        return
+
+    agents_dst = claude_dir / "agents"
+    if agents_dst.is_symlink():
+        agents_dst.unlink()
+        print("  Upgraded: .claude/agents (directory symlink -> per-file)")
+    agents_dst.mkdir(parents=True, exist_ok=True)
+    linked = 0
+    skipped = 0
+    for agent_file in sorted(agents_src.glob("*.md")):
+        target = agents_dst / agent_file.name
+        if target.is_symlink():
+            target.unlink()
+        if target.is_file():
+            skipped += 1
+            continue
+        target.symlink_to(agent_file)
+        linked += 1
+    print(f"  Linked: .claude/agents/ ({linked} files)")
+    if skipped > 0:
+        print(f"  Kept: {skipped} user agent(s) (name conflict)")
+
+
+def install_skills(claude_dir: Path, only: str, skip: str, dry_run: bool) -> None:
+    """Create per-directory symlinks for skills."""
+    if not should_install("skills", only, skip):
+        print("  Skipped: .claude/skills")
+        return
+
+    skills_src = app_dir / "skills"
+    if not skills_src.is_dir():
+        return
+
+    if dry_run:
+        print("  Would link: .claude/skills/*/ (per-directory merge)")
+        return
+
+    skills_dst = claude_dir / "skills"
+    if skills_dst.is_symlink():
+        skills_dst.unlink()
+        print("  Upgraded: .claude/skills (directory symlink -> per-directory)")
+    skills_dst.mkdir(parents=True, exist_ok=True)
+    linked = 0
+    skipped = 0
+    for skill_dir in sorted(skills_src.iterdir()):
+        if not skill_dir.is_dir() or skill_dir.name.startswith("_"):
+            continue
+        target = skills_dst / skill_dir.name
+        if target.is_symlink():
+            target.unlink()
+        if target.is_dir():
+            skipped += 1
+            continue
+        target.symlink_to(skill_dir)
+        linked += 1
+    print(f"  Linked: .claude/skills/ ({linked} directories)")
+    if skipped > 0:
+        print(f"  Kept: {skipped} user skill(s) (name conflict)")
+
+
+def clean_legacy_commands(claude_dir: Path, dry_run: bool) -> None:
+    """Remove legacy commands symlink."""
+    legacy_commands = claude_dir / "commands"
+    if legacy_commands.is_symlink():
+        if not dry_run:
+            legacy_commands.unlink()
+        print("  Removed: .claude/commands (legacy)")