ai-agent-rules 0.11.0__py3-none-any.whl → 0.15.8__py3-none-any.whl

ai_rules/cli.py

@@ -22,6 +22,7 @@ from rich.table import Table
 
 from ai_rules.agents.base import Agent
 from ai_rules.agents.claude import ClaudeAgent
+from ai_rules.agents.cursor import CursorAgent
 from ai_rules.agents.goose import GooseAgent
 from ai_rules.agents.shared import SharedAgent
 from ai_rules.config import (
@@ -115,6 +116,7 @@ def get_agents(config_dir: Path, config: Config) -> list[Agent]:
     """
     return [
         ClaudeAgent(config_dir, config),
+        CursorAgent(config_dir, config),
         GooseAgent(config_dir, config),
         SharedAgent(config_dir, config),
     ]
@@ -132,6 +134,18 @@ def complete_agents(
     return [CompletionItem(aid) for aid in agent_ids if aid.startswith(incomplete)]
 
 
+def complete_profiles(
+    ctx: click.Context, param: click.Parameter, incomplete: str
+) -> list[CompletionItem]:
+    """Dynamically complete profile names for --profile option."""
+    from ai_rules.profiles import ProfileLoader
+
+    loader = ProfileLoader()
+    profiles = loader.list_profiles()
+
+    return [CompletionItem(p) for p in profiles if p.startswith(incomplete)]
+
+
 def detect_old_config_symlinks() -> list[tuple[Path, Path]]:
     """Detect symlinks pointing to old config/ location.
 
@@ -438,6 +452,20 @@ def version_callback(ctx: click.Context, param: click.Parameter, value: bool) ->
 
     console.print(f"ai-rules, version {__version__}")
 
+    try:
+        from ai_rules.bootstrap import get_tool_version, is_command_available
+
+        if is_command_available("claude-statusline"):
+            statusline_version = get_tool_version("claude-code-statusline")
+            if statusline_version:
+                console.print(f"statusline, version {statusline_version}")
+            else:
+                console.print(
+                    "statusline, version [dim](installed, version unknown)[/dim]"
+                )
+    except Exception as e:
+        logger.debug(f"Failed to get statusline version: {e}")
+
     try:
         from ai_rules.bootstrap import check_tool_updates, get_tool_by_id
 
@@ -592,17 +620,26 @@ def install_user_symlinks(
 
 
 @main.command()
+@click.option("--github", is_flag=True, help="Install from GitHub instead of PyPI")
 @click.option("--force", is_flag=True, help="Skip confirmation prompts")
 @click.option("--dry-run", is_flag=True, help="Show what would be done")
 @click.option("--skip-symlinks", is_flag=True, help="Skip symlink installation step")
 @click.option("--skip-completions", is_flag=True, help="Skip shell completion setup")
+@click.option(
+    "--profile",
+    default=None,
+    shell_complete=complete_profiles,
+    help="Profile to use (default: 'default')",
+)
 @click.pass_context
 def setup(
     ctx: click.Context,
+    github: bool,
     force: bool,
     dry_run: bool,
     skip_symlinks: bool,
     skip_completions: bool,
+    profile: str | None,
 ) -> None:
     """One-time setup: install symlinks and make ai-rules available system-wide.
 
@@ -616,43 +653,96 @@ def setup(
         get_tool_config_dir,
         install_tool,
     )
+    from ai_rules.bootstrap.updater import (
+        check_tool_updates,
+        get_tool_by_id,
+        perform_tool_upgrade,
+    )
 
-    statusline_result = ensure_statusline_installed(dry_run=dry_run)
+    console.print("[bold cyan]Step 1/3: Install ai-rules system-wide[/bold cyan]")
+    console.print("This allows you to run 'ai-rules' from any directory.\n")
+
+    statusline_result, statusline_message = ensure_statusline_installed(
+        dry_run=dry_run, from_github=github
+    )
     if statusline_result == "installed":
-        console.print("[green]✓[/green] Installed claude-statusline\n")
+        if dry_run and statusline_message:
+            console.print(f"[dim]{statusline_message}[/dim]")
+        else:
+            console.print("[green]✓[/green] Installed claude-statusline")
+    elif statusline_result == "upgraded":
+        console.print(
+            f"[green]✓[/green] Upgraded claude-statusline ({statusline_message})"
+        )
+    elif statusline_result == "upgrade_available":
+        console.print(f"[dim]{statusline_message}[/dim]")
     elif statusline_result == "failed":
         console.print(
-            "[yellow]⚠[/yellow] Failed to install claude-statusline (continuing anyway)\n"
+            "[yellow]⚠[/yellow] Failed to install claude-statusline (continuing anyway)"
         )
 
-    console.print("[bold cyan]Step 1/3: Install ai-rules system-wide[/bold cyan]")
-    console.print("This allows you to run 'ai-rules' from any directory.\n")
+    ai_rules_tool = get_tool_by_id("ai-rules")
+    tool_install_success = False
 
-    if not force:
-        if not Confirm.ask("Install ai-rules permanently?", default=True):
-            console.print(
-                "\n[yellow]Skipped.[/yellow] You can still run via: uvx ai-rules <command>"
+    if ai_rules_tool and ai_rules_tool.is_installed():
+        try:
+            update_info = check_tool_updates(ai_rules_tool, timeout=10)
+            if update_info and update_info.has_update:
+                if dry_run:
+                    console.print(
+                        f"[dim]Would upgrade ai-rules {update_info.current_version} → {update_info.latest_version}[/dim]"
+                    )
+                    tool_install_success = True
+                else:
+                    if not force and not Confirm.ask(
+                        f"Upgrade ai-rules {update_info.current_version} → {update_info.latest_version}?",
+                        default=True,
+                    ):
+                        console.print("[yellow]Skipped ai-rules upgrade[/yellow]")
+                        tool_install_success = True
+                    else:
+                        success, msg, _ = perform_tool_upgrade(ai_rules_tool)
+                        if success:
+                            console.print(
+                                f"[green]✓[/green] Upgraded ai-rules ({update_info.current_version} → {update_info.latest_version})"
+                            )
+                            tool_install_success = True
+                        else:
+                            console.print(
+                                "[red]Error:[/red] Failed to upgrade ai-rules"
+                            )
+            else:
+                tool_install_success = True
+        except Exception:
+            pass
+
+    if not tool_install_success:
+        if not force and not dry_run:
+            if not Confirm.ask("Install ai-rules permanently?", default=True):
+                console.print(
+                    "\n[yellow]Skipped.[/yellow] You can still run via: uvx ai-rules <command>"
+                )
+                return
+
+        try:
+            success, message = install_tool(
+                "ai-agent-rules", from_github=github, force=force, dry_run=dry_run
             )
-            return
 
-    tool_install_success = False
-    try:
-        success, message = install_tool("ai-agent-rules", force=force, dry_run=dry_run)
-
-        if dry_run:
-            console.print(f"\n[dim]{message}[/dim]")
-            tool_install_success = True
-        elif success:
-            console.print("[green]✓ Tool installed successfully[/green]\n")
-            tool_install_success = True
-        else:
-            console.print(f"\n[red]Error:[/red] {message}")
-            console.print("\n[yellow]Manual installation:[/yellow]")
-            console.print("  uv tool install ai-agent-rules")
+            if dry_run:
+                console.print(f"[dim]{message}[/dim]")
+                tool_install_success = True
+            elif success:
+                console.print("[green]✓[/green] Tool installed successfully")
+                tool_install_success = True
+            else:
+                console.print(f"\n[red]Error:[/red] {message}")
+                console.print("\n[yellow]Manual installation:[/yellow]")
+                console.print("  uv tool install ai-agent-rules")
+                return
+        except Exception as e:
+            console.print(f"\n[red]Error:[/red] {e}")
             return
-    except Exception as e:
-        console.print(f"\n[red]Error:[/red] {e}")
-        return
 
     if not skip_symlinks:
         console.print(
@@ -685,21 +775,31 @@ def setup(
             rebuild_cache=False,
             agents=None,
             skip_completions=True,
+            profile=profile,
             config_dir_override=config_dir_override,
         )
 
     if not skip_completions:
         from ai_rules.completions import (
             detect_shell,
+            find_config_file,
             get_supported_shells,
             install_completion,
+            is_completion_installed,
         )
 
         console.print("\n[bold cyan]Step 3/3: Shell completion setup[/bold cyan]\n")
 
         shell = detect_shell()
         if shell:
-            if force or Confirm.ask(f"Install {shell} tab completion?", default=True):
+            config_path = find_config_file(shell)
+            if config_path and is_completion_installed(config_path):
+                console.print(f"[green]✓[/green] {shell} completion already installed")
+            elif (
+                force
+                or dry_run
+                or Confirm.ask(f"Install {shell} tab completion?", default=True)
+            ):
                 success, msg = install_completion(shell, dry_run=dry_run)
                 if success:
                     console.print(f"[green]✓[/green] {msg}")
@@ -711,8 +811,11 @@ def setup(
                 f"[dim]Shell completion not available for your shell (only {supported} supported)[/dim]"
             )
 
-    console.print("\n[green]✓ Setup complete![/green]")
-    console.print("You can now run [bold]ai-rules[/bold] from anywhere.")
+    if dry_run:
+        console.print("\n[dim]Dry run complete - no changes were made.[/dim]")
+    else:
+        console.print("\n[green]✓ Setup complete![/green]")
+        console.print("You can now run [bold]ai-rules[/bold] from anywhere.")
 
 
 @main.command()
@@ -733,6 +836,12 @@ def setup(
     is_flag=True,
     help="Skip shell completion installation",
 )
+@click.option(
+    "--profile",
+    default=None,
+    shell_complete=complete_profiles,
+    help="Profile to use (default: 'default' for backward compatibility)",
+)
 @click.option(
     "--config-dir",
     "config_dir_override",
@@ -745,14 +854,18 @@ def install(
     rebuild_cache: bool,
     agents: str | None,
     skip_completions: bool,
+    profile: str | None,
     config_dir_override: str | None = None,
 ) -> None:
     """Install AI agent configs via symlinks."""
     from ai_rules.bootstrap import ensure_statusline_installed
 
-    statusline_result = ensure_statusline_installed(dry_run=dry_run)
+    statusline_result, statusline_message = ensure_statusline_installed(dry_run=dry_run)
     if statusline_result == "installed":
-        console.print("[green]✓[/green] Installed claude-statusline\n")
+        if dry_run and statusline_message:
+            console.print(f"[dim]{statusline_message}[/dim]\n")
+        else:
+            console.print("[green]✓[/green] Installed claude-statusline\n")
     elif statusline_result == "failed":
         console.print(
             "[yellow]⚠[/yellow] Failed to install claude-statusline (continuing anyway)\n"
@@ -766,7 +879,20 @@ def install(
     else:
         config_dir = get_config_dir()
 
-    config = Config.load()
+    from ai_rules.profiles import ProfileNotFoundError
+    from ai_rules.state import set_active_profile
+
+    try:
+        config = Config.load(profile=profile)
+    except ProfileNotFoundError as e:
+        console.print(f"[red]Error:[/red] {e}")
+        sys.exit(1)
+
+    if not dry_run:
+        set_active_profile(profile or "default")
+
+    if profile and profile != "default":
+        console.print(f"[dim]Using profile: {profile}[/dim]\n")
 
     if rebuild_cache and not dry_run:
         import shutil
@@ -783,6 +909,12 @@ def install(
                 "claude", claude_settings, force_rebuild=rebuild_cache
             )
 
+        cursor_settings = config_dir / "cursor" / "settings.json"
+        if cursor_settings.exists():
+            config.build_merged_settings(
+                "cursor", cursor_settings, force_rebuild=rebuild_cache
+            )
+
         goose_settings = config_dir / "goose" / "config.yaml"
         if goose_settings.exists():
             config.build_merged_settings(
@@ -985,6 +1117,8 @@ def _display_symlink_status(
 )
 def status(agents: str | None) -> None:
     """Check status of AI agent symlinks."""
+    from ai_rules.state import get_active_profile
+
     config_dir = get_config_dir()
     config = Config.load()
     all_agents = get_agents(config_dir, config)
@@ -992,6 +1126,10 @@ def status(agents: str | None) -> None:
 
     console.print("[bold]AI Rules Status[/bold]\n")
 
+    active_profile = get_active_profile()
+    if active_profile:
+        console.print(f"[dim]Profile: {active_profile}[/dim]\n")
+
     all_correct = True
 
     console.print("[bold cyan]User-Level Configuration[/bold cyan]\n")
@@ -1299,7 +1437,7 @@ def upgrade(check: bool, force: bool, skip_install: bool, only: str | None) -> N
     from ai_rules.bootstrap import (
         UPDATABLE_TOOLS,
         check_tool_updates,
-        perform_pypi_update,
+        perform_tool_upgrade,
     )
 
     tools = [t for t in UPDATABLE_TOOLS if only is None or t.tool_id == only]
@@ -1348,13 +1486,12 @@ def upgrade(check: bool, force: bool, skip_install: bool, only: str | None) -> N
         console.print("[green]✓[/green] All tools are up to date!")
         return
 
-    if not check:
-        for tool, update_info in tool_updates:
-            if update_info.has_update:
-                console.print(
-                    f"[cyan]Update available for {tool.display_name}:[/cyan] "
-                    f"{update_info.current_version} → {update_info.latest_version}"
-                )
+    for tool, update_info in tool_updates:
+        if update_info.has_update:
+            console.print(
+                f"[cyan]Update available for {tool.display_name}:[/cyan] "
+                f"{update_info.current_version} → {update_info.latest_version}"
+            )
 
     if check:
         if tool_updates:
@@ -1374,7 +1511,7 @@ def upgrade(check: bool, force: bool, skip_install: bool, only: str | None) -> N
     for tool, update_info in tool_updates:
         with console.status(f"Upgrading {tool.display_name}..."):
             try:
-                success, msg, was_upgraded = perform_pypi_update(tool.package_name)
+                success, msg, was_upgraded = perform_tool_upgrade(tool)
             except Exception as e:
                 console.print(
                     f"\n[red]Error:[/red] {tool.display_name} upgrade failed: {e}"
@@ -1453,6 +1590,59 @@ def upgrade(check: bool, force: bool, skip_install: bool, only: str | None) -> N
         console.print("[dim]Restart your terminal if the command doesn't work[/dim]")
 
 
+@main.command()
+def info() -> None:
+    """Show installation method and version info for ai-rules tools.
+
+    Displays how each tool was installed (PyPI, GitHub, or local development)
+    along with current versions and update availability.
+    """
+    from rich.table import Table
+
+    from ai_rules.bootstrap import (
+        UPDATABLE_TOOLS,
+        check_tool_updates,
+        get_tool_source,
+    )
+
+    table = Table(title="AI Rules Installation Info", show_header=True)
+    table.add_column("Tool", style="cyan")
+    table.add_column("Source", style="bold")
+    table.add_column("Version")
+    table.add_column("Update")
+
+    has_updates = False
+
+    for tool in UPDATABLE_TOOLS:
+        tool_name = tool.display_name
+
+        if not tool.is_installed():
+            table.add_row(tool_name, "-", "-", "[dim](not installed)[/dim]")
+            continue
+
+        source = get_tool_source(tool.package_name)
+        source_display = source.name.lower() if source else "[dim]unknown[/dim]"
+
+        version = tool.get_version()
+        version_display = version if version else "[dim]unknown[/dim]"
+
+        update_display = "-"
+        try:
+            update_info = check_tool_updates(tool, timeout=5)
+            if update_info and update_info.has_update:
+                update_display = f"[cyan]{update_info.latest_version} available[/cyan]"
+                has_updates = True
+        except Exception:
+            update_display = "[dim](check failed)[/dim]"
+
+        table.add_row(tool_name, source_display, version_display, update_display)
+
+    console.print(table)
+
+    if has_updates:
+        console.print("\n[dim]Run 'ai-rules upgrade' to install updates.[/dim]")
+
+
 @main.command()
 @click.option(
     "--agents",
@@ -2181,6 +2371,134 @@ def config_init() -> None:
         console.print("[dim]Configuration not saved[/dim]")
 
 
+@main.group()
+def profile() -> None:
+    """Manage configuration profiles."""
+    pass
+
+
+@profile.command("list")
+def profile_list() -> None:
+    """List available profiles."""
+    from rich.table import Table
+
+    from ai_rules.profiles import ProfileLoader
+
+    loader = ProfileLoader()
+    profiles = loader.list_profiles()
+
+    table = Table(title="Available Profiles", show_header=True)
+    table.add_column("Name", style="cyan")
+    table.add_column("Description")
+    table.add_column("Extends")
+
+    for name in profiles:
+        try:
+            info = loader.get_profile_info(name)
+            desc = info.get("description", "")
+            extends = info.get("extends") or "-"
+            table.add_row(name, desc, extends)
+        except Exception:
+            table.add_row(name, "[dim]Error loading[/dim]", "-")
+
+    console.print(table)
+
+
+@profile.command("show")
+@click.argument("name")
+@click.option(
+    "--resolved", is_flag=True, help="Show resolved profile with inheritance applied"
+)
+def profile_show(name: str, resolved: bool) -> None:
+    """Show profile details."""
+    from ai_rules.profiles import (
+        CircularInheritanceError,
+        ProfileLoader,
+        ProfileNotFoundError,
+    )
+
+    loader = ProfileLoader()
+
+    try:
+        if resolved:
+            profile = loader.load_profile(name)
+            console.print(f"[bold]Profile: {profile.name}[/bold] (resolved)")
+            console.print(f"[dim]Description:[/dim] {profile.description}")
+            if profile.extends:
+                console.print(f"[dim]Extends:[/dim] {profile.extends}")
+
+            if profile.settings_overrides:
+                console.print("\n[bold]Settings Overrides:[/bold]")
+                for agent, overrides in sorted(profile.settings_overrides.items()):
+                    console.print(f"  [cyan]{agent}:[/cyan]")
+                    for key, value in sorted(overrides.items()):
+                        console.print(f"    {key}: {value}")
+
+            if profile.exclude_symlinks:
+                console.print("\n[bold]Exclude Symlinks:[/bold]")
+                for pattern in sorted(profile.exclude_symlinks):
+                    console.print(f"  - {pattern}")
+
+            if profile.mcp_overrides:
+                console.print("\n[bold]MCP Overrides:[/bold]")
+                for mcp, overrides in sorted(profile.mcp_overrides.items()):
+                    console.print(f"  [cyan]{mcp}:[/cyan]")
+                    for key, value in sorted(overrides.items()):
+                        console.print(f"    {key}: {value}")
+        else:
+            import yaml
+
+            info = loader.get_profile_info(name)
+            console.print(f"[bold]Profile: {info.get('name', name)}[/bold]")
+            console.print(yaml.dump(info, default_flow_style=False, sort_keys=False))
+
+    except ProfileNotFoundError as e:
+        console.print(f"[red]Error:[/red] {e}")
+        sys.exit(1)
+    except CircularInheritanceError as e:
+        console.print(f"[red]Error:[/red] {e}")
+        sys.exit(1)
+
+
+@profile.command("current")
+def profile_current() -> None:
+    """Show currently active profile."""
+    from ai_rules.state import get_active_profile
+
+    active = get_active_profile()
+    if active:
+        console.print(f"Active profile: [cyan]{active}[/cyan]")
+    else:
+        console.print("[dim]No profile set (using default)[/dim]")
+
+
+@profile.command("switch")
+@click.argument("name", shell_complete=complete_profiles)
+@click.pass_context
+def profile_switch(ctx: click.Context, name: str) -> None:
+    """Switch to a different profile."""
+    from ai_rules.profiles import ProfileLoader, ProfileNotFoundError
+
+    loader = ProfileLoader()
+    try:
+        loader.load_profile(name)
+    except ProfileNotFoundError as e:
+        console.print(f"[red]Error:[/red] {e}")
+        sys.exit(1)
+
+    console.print(f"Switching to profile: [cyan]{name}[/cyan]")
+    ctx.invoke(
+        install,
+        profile=name,
+        rebuild_cache=True,
+        force=True,
+        skip_completions=True,
+        agents=None,
+        dry_run=False,
+        config_dir_override=None,
+    )
+
+
 @main.group()
 def completions() -> None:
     """Manage shell tab completion."""

ai_rules/config/AGENTS.md

@@ -187,15 +187,16 @@ def test_register_user_calls_hash_password():
 ## Priority 3: Style & Formatting Guidelines
 
 ### Code Comment Standards
-**Rule:** ONLY add comments explaining WHY, NOT WHAT.
+**Rule:** ONLY add comments explaining WHY, NOT WHAT. Never add code comments that simply restate what the code does.
 
-**Prohibited (WHAT):**
+**Prohibited - Comments that restate code behavior (WHAT):**
 ```python
 counter += 1  # Increment counter by 1
 for user in users:  # Loop through users
+result = calculate_total(items)  # Calculate the total from items
 ```
 
-**Required (WHY):**
+**Required - Comments that explain reasoning or context (WHY):**
 ```python
 # Use exponential backoff to avoid Stripe API rate limiting
 delay = 2 ** retry_count
@@ -207,7 +208,7 @@ results.sort(key=lambda x: x.timestamp, reverse=True)
 sanitized = validate_and_sanitize(user_input)
 ```
 
-**Why:** Code should be self-explanatory via naming. Comments explaining WHAT become outdated. Comments explaining WHY preserve critical context not visible in code.
+**Why:** Code should be self-explanatory via naming. Comments that restate what code does become outdated and add noise. Comments explaining WHY preserve critical context (business rules, security requirements, performance considerations) not visible in the code itself.
 
 ### Whitespace Standards
 **Rule:** Remove ALL trailing whitespace | Ensure blank lines have NO whitespace | Preserve existing newlines | All files end with single newline

ai_rules/config/claude/CLAUDE.md

@@ -0,0 +1 @@
+@~/AGENTS.md