scc-cli 1.4.0__py3-none-any.whl

scc_cli/cli_helpers.py

@@ -0,0 +1,244 @@
+"""Provide centralized CLI helpers for confirmation and safety patterns.
+
+Provide standardized helpers for:
+- Destructive operation confirmation (prune, worktree remove, etc.)
+- Governance command validation (unblock, exceptions)
+- Non-interactive mode detection (CI environments)
+- JSON mode compatibility
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+from dataclasses import dataclass
+from datetime import datetime, timezone
+
+import typer
+from rich.console import Console
+
+from .exit_codes import EXIT_USAGE
+from .output_mode import is_json_mode
+
+console = Console()
+stderr_console = Console(stderr=True)
+
+
+@dataclass(frozen=True)
+class ConfirmItems:
+    """Hold items to display before a confirmation prompt.
+
+    Attributes:
+        title: Header text shown above the item list.
+        items: List of item descriptions to display.
+        max_display: Maximum items to show before truncating with count.
+    """
+
+    title: str
+    items: list[str]
+    max_display: int = 10
+
+
+def is_interactive() -> bool:
+    """Check if running in interactive mode.
+
+    Return False if:
+    - stdin is not a TTY (piped input, redirected)
+    - CI environment variable is set to truthy value
+    - JSON output mode is active
+
+    Returns:
+        True if interactive prompts are safe to use.
+    """
+    if is_json_mode():
+        return False
+
+    is_tty = sys.stdin.isatty()
+    is_ci = os.getenv("CI", "").lower() in ("1", "true", "yes")
+
+    return is_tty and not is_ci
+
+
+def confirm_action(
+    *,
+    yes: bool,
+    prompt: str,
+    dry_run: bool = False,
+    items: ConfirmItems | None = None,
+    non_interactive_requires_yes: bool = True,
+) -> bool:
+    """Standard confirmation behavior for destructive operations.
+
+    Args:
+        yes: If True, skip confirmation prompt.
+        prompt: The confirmation question to ask.
+        dry_run: If True, return False (caller should not mutate state).
+        items: Optional list of affected items to display before prompting.
+        non_interactive_requires_yes: If True, exit with EXIT_USAGE when
+            running non-interactively without --yes.
+
+    Returns:
+        True if action should proceed, False if dry-run mode.
+
+    Raises:
+        typer.Exit(EXIT_USAGE): If non-interactive and would prompt without --yes.
+        typer.Abort: If user declines confirmation.
+
+    Behavior:
+        - If dry_run: return False (caller should not mutate state)
+        - If yes: return True (skip prompt)
+        - If JSON mode: exit EXIT_USAGE (never prompt in JSON mode)
+        - If non-interactive and would prompt: exit EXIT_USAGE
+        - Otherwise: print affected resources (if provided) and prompt
+    """
+    if dry_run:
+        return False
+
+    if yes:
+        return True
+
+    # JSON mode must never prompt
+    if is_json_mode():
+        stderr_console.print(
+            "[red]Error:[/red] Cannot prompt in JSON mode. Use --yes to confirm.",
+            style="bold",
+        )
+        raise typer.Exit(EXIT_USAGE)
+
+    # Non-interactive mode detection
+    if not is_interactive() and non_interactive_requires_yes:
+        console.print(
+            "[red]Error:[/red] This operation requires confirmation. "
+            "Use --yes to skip in non-interactive mode.",
+            style="bold",
+        )
+        raise typer.Exit(EXIT_USAGE)
+
+    # Display affected items
+    if items:
+        console.print(f"\n[bold]{items.title}[/bold]")
+        shown = items.items[: items.max_display]
+        for item in shown:
+            console.print(f"  [dim]•[/dim] {item}")
+        if len(items.items) > items.max_display:
+            remaining = len(items.items) - items.max_display
+            console.print(f"  [dim](+ {remaining} more)[/dim]")
+        console.print()
+
+    # Prompt for confirmation
+    return typer.confirm(prompt, abort=True)
+
+
+def require_reason_for_governance(
+    *,
+    yes: bool,
+    reason: str | None,
+    command_name: str = "unblock",
+) -> str:
+    """Require --reason when --yes is used for governance commands.
+
+    Args:
+        yes: Whether --yes flag was provided.
+        reason: The reason string if provided via --reason.
+        command_name: Name of the command for error messages.
+
+    Returns:
+        The reason string (either provided or collected interactively).
+
+    Raises:
+        typer.Exit(EXIT_USAGE): If --yes used without --reason.
+    """
+    if yes and not reason:
+        console.print(
+            f"[red]Error:[/red] --reason is required when using --yes with {command_name}.",
+            style="bold",
+        )
+        raise typer.Exit(EXIT_USAGE)
+
+    if reason:
+        return reason
+
+    # Interactive mode: prompt for reason
+    if is_json_mode():
+        stderr_console.print(
+            "[red]Error:[/red] Cannot prompt for reason in JSON mode. Use --reason.",
+            style="bold",
+        )
+        raise typer.Exit(EXIT_USAGE)
+
+    if not is_interactive():
+        console.print(
+            "[red]Error:[/red] Cannot prompt for reason in non-interactive mode. Use --reason.",
+            style="bold",
+        )
+        raise typer.Exit(EXIT_USAGE)
+
+    prompted_reason: str = typer.prompt("Reason for this exception")
+    return prompted_reason
+
+
+@dataclass(frozen=True)
+class AuditRecord:
+    """Audit record for governance operations."""
+
+    timestamp: datetime
+    command: str
+    actor: str
+    target: str
+    reason: str
+    ticket: str | None = None
+    expires_in: str | None = None
+
+    def to_dict(self) -> dict[str, str | None]:
+        """Convert to dictionary for JSON serialization."""
+        result: dict[str, str | None] = {
+            "timestamp": self.timestamp.isoformat(),
+            "command": self.command,
+            "actor": self.actor,
+            "target": self.target,
+            "reason": self.reason,
+        }
+        if self.ticket:
+            result["ticket"] = self.ticket
+        if self.expires_in:
+            result["expires_in"] = self.expires_in
+        return result
+
+
+def get_current_user() -> str:
+    """Get the current user for audit purposes."""
+    return os.getenv("USER", os.getenv("USERNAME", "unknown"))
+
+
+def create_audit_record(
+    *,
+    command: str,
+    target: str,
+    reason: str,
+    ticket: str | None = None,
+    expires_in: str | None = None,
+) -> AuditRecord:
+    """Create an audit record for governance operations.
+
+    This is mandatory for governance commands (unblock, exception creation).
+    For other destructive operations, use only if SCC_AUDIT_LOG is enabled.
+
+    Args:
+        command: The governance command being executed.
+        target: The resource being affected (e.g., plugin name, policy).
+        reason: Justification for the operation.
+        ticket: Optional issue/ticket reference for traceability.
+        expires_in: Optional duration string for temporary exceptions.
+
+    Returns:
+        A timestamped audit record with actor information.
+    """
+    return AuditRecord(
+        timestamp=datetime.now(timezone.utc),
+        command=command,
+        actor=get_current_user(),
+        target=target,
+        reason=reason,
+        ticket=ticket,
+        expires_in=expires_in,
+    )

scc_cli/cli_init.py

@@ -0,0 +1,272 @@
+"""
+Define the SCC init command for project configuration initialization.
+
+Create a .scc.yaml configuration file in a project directory with
+sensible defaults and helpful comments.
+"""
+
+from pathlib import Path
+from typing import Any
+
+import typer
+from rich.panel import Panel
+
+from .cli_common import console, handle_errors
+from .cli_helpers import confirm_action, is_interactive
+from .exit_codes import EXIT_CONFIG, EXIT_SUCCESS, EXIT_USAGE
+from .json_output import build_envelope
+from .kinds import Kind
+from .output_mode import print_json, set_pretty_mode
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Pure Functions (No I/O)
+# ─────────────────────────────────────────────────────────────────────────────
+
+
+def is_git_repo(path: Path) -> bool:
+    """Check if path is a git repository.
+
+    Args:
+        path: Directory path to check.
+
+    Returns:
+        True if .git directory exists, False otherwise.
+    """
+    git_dir = path / ".git"
+    return git_dir.exists() and git_dir.is_dir()
+
+
+def build_init_data(
+    file_path: str,
+    created: bool,
+    overwritten: bool,
+    is_git_repo: bool,
+) -> dict[str, Any]:
+    """Build init result data for JSON output.
+
+    Args:
+        file_path: Path to created .scc.yaml file.
+        created: Whether the file was created.
+        overwritten: Whether an existing file was overwritten.
+        is_git_repo: Whether the target is a git repository.
+
+    Returns:
+        Dictionary with init result data.
+    """
+    return {
+        "file_path": file_path,
+        "created": created,
+        "overwritten": overwritten,
+        "is_git_repo": is_git_repo,
+    }
+
+
+def generate_template_content() -> str:
+    """Generate .scc.yaml template content with helpful comments.
+
+    Returns:
+        YAML template string with comments.
+    """
+    return """\
+# SCC Project Configuration
+# ─────────────────────────────────────────────────────────────────────────────
+# This file configures SCC (Sandboxed Claude CLI) for this project.
+# Place this file in your repository root.
+#
+# For full documentation, see: https://github.com/sundsvall/scc-cli#configuration
+# ─────────────────────────────────────────────────────────────────────────────
+
+# Additional plugins to enable for this project
+# These plugins are loaded on top of your team profile's plugins.
+# Only plugins allowed by your organization can be added here.
+additional_plugins: []
+  # - "project-specific-linter"
+  # - "custom-formatter"
+
+# Session configuration
+session:
+  # Session timeout in hours (default: 8)
+  timeout_hours: 8
+
+# Optional: MCP servers specific to this project
+# mcp_servers: []
+#   - name: "project-db"
+#     command: "npx"
+#     args: ["@project/mcp-server"]
+
+# Optional: Environment variables for the sandbox
+# env: {}
+#   PROJECT_NAME: "my-project"
+"""
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# CLI Command
+# ─────────────────────────────────────────────────────────────────────────────
+
+
+@handle_errors
+def init_cmd(
+    path: str | None = typer.Argument(
+        None,
+        help="Target directory (default: current directory).",
+    ),
+    force: bool = typer.Option(
+        False,
+        "--force",
+        "-f",
+        help="Overwrite existing .scc.yaml file without prompting.",
+    ),
+    yes: bool = typer.Option(
+        False,
+        "-y",
+        "--yes",
+        help="Skip confirmation prompts (still requires --force to overwrite).",
+    ),
+    json_output: bool = typer.Option(
+        False,
+        "--json",
+        help="Output as JSON.",
+    ),
+    pretty: bool = typer.Option(
+        False,
+        "--pretty",
+        help="Pretty-print JSON (implies --json).",
+    ),
+) -> None:
+    """Initialize SCC project configuration.
+
+    Creates a .scc.yaml file in the target directory with sensible defaults
+    and helpful comments explaining each configuration option.
+
+    Three-tier overwrite logic:
+      - If file doesn't exist: create it
+      - If file exists + --force: overwrite without prompting
+      - If file exists + no --force: prompt in interactive mode, or hint to use --force
+    """
+    # --pretty implies --json
+    if pretty:
+        json_output = True
+        set_pretty_mode(True)
+
+    # Resolve target path
+    if path is None:
+        target_dir = Path.cwd()
+    else:
+        target_dir = Path(path).resolve()
+
+    # Validate target directory
+    if not target_dir.exists():
+        if json_output:
+            envelope = build_envelope(
+                Kind.INIT_RESULT,
+                ok=False,
+                errors=[f"Directory does not exist: {target_dir}"],
+            )
+            print_json(envelope)
+            raise typer.Exit(EXIT_CONFIG)
+        else:
+            console.print(f"[red]Error:[/red] Directory does not exist: {target_dir}")
+            raise typer.Exit(EXIT_CONFIG)
+
+    if not target_dir.is_dir():
+        if json_output:
+            envelope = build_envelope(
+                Kind.INIT_RESULT,
+                ok=False,
+                errors=[f"Path is not a directory: {target_dir}"],
+            )
+            print_json(envelope)
+            raise typer.Exit(EXIT_CONFIG)
+        else:
+            console.print(f"[red]Error:[/red] Path is not a directory: {target_dir}")
+            raise typer.Exit(EXIT_CONFIG)
+
+    # Check for existing file - three-tier overwrite logic
+    scc_yaml = target_dir / ".scc.yaml"
+    overwritten = False
+
+    if scc_yaml.exists():
+        if force:
+            # Tier 3: --force → overwrite without prompting
+            overwritten = True
+        elif json_output:
+            # JSON mode: never prompt, just tell user to use --force
+            envelope = build_envelope(
+                Kind.INIT_RESULT,
+                ok=False,
+                errors=[f"File already exists: {scc_yaml}. Use --force to overwrite."],
+            )
+            print_json(envelope)
+            raise typer.Exit(EXIT_CONFIG)
+        elif yes:
+            # Tier 4: --yes without --force → hint that --force is required
+            console.print(
+                f"[yellow]Warning:[/yellow] File already exists: [cyan]{scc_yaml}[/cyan]\n"
+                "[dim]--yes skips prompts but does not allow overwriting.[/dim]\n"
+                "Use [yellow]--force[/yellow] to overwrite existing file."
+            )
+            raise typer.Exit(EXIT_USAGE)
+        elif is_interactive():
+            # Tier 2: Interactive without --force → prompt for confirmation
+            console.print(f"[yellow]Warning:[/yellow] File already exists: [cyan]{scc_yaml}[/cyan]")
+            try:
+                confirm_action(
+                    yes=False,
+                    prompt="Overwrite existing .scc.yaml?",
+                    non_interactive_requires_yes=False,
+                )
+                overwritten = True
+            except typer.Abort:
+                console.print("[dim]Aborted.[/dim]")
+                raise typer.Exit(EXIT_SUCCESS)
+        else:
+            # Tier 3: Non-interactive without --force → exit with usage error
+            console.print(
+                f"[red]Error:[/red] File already exists: [cyan]{scc_yaml}[/cyan]\n"
+                "Use [yellow]--force[/yellow] to overwrite in non-interactive mode."
+            )
+            raise typer.Exit(EXIT_USAGE)
+
+    # Check if git repo and warn if not
+    is_git = is_git_repo(target_dir)
+    if not is_git and not json_output:
+        console.print(
+            "[yellow]Warning:[/yellow] Target directory is not a git repository.\n"
+            "SCC works best with git-tracked projects for branch safety and worktree features."
+        )
+
+    # Generate and write template
+    template_content = generate_template_content()
+    scc_yaml.write_text(template_content)
+
+    # Build result data
+    result_data = build_init_data(
+        file_path=str(scc_yaml),
+        created=True,
+        overwritten=overwritten,
+        is_git_repo=is_git,
+    )
+
+    # Output
+    if json_output:
+        envelope = build_envelope(Kind.INIT_RESULT, data=result_data)
+        print_json(envelope)
+        raise typer.Exit(EXIT_SUCCESS)
+    else:
+        action = "Overwrote" if overwritten else "Created"
+        console.print(
+            Panel(
+                f"{action} [cyan]{scc_yaml}[/cyan]\n\n"
+                "Edit this file to configure project-specific settings.\n"
+                "See the comments in the file for available options.",
+                title="[green]SCC Initialized[/green]",
+                border_style="green",
+            )
+        )
+        if not is_git:
+            console.print(
+                "\n[dim]Tip: Initialize a git repository with [cyan]git init[/cyan] "
+                "to enable branch safety and worktree features.[/dim]"
+            )
+        raise typer.Exit(EXIT_SUCCESS)