scc-cli 1.4.0__py3-none-any.whl

scc_cli/utils/__init__.py

@@ -0,0 +1,39 @@
+"""Utility modules for SCC CLI."""
+
+from scc_cli.utils.fixit import (
+    format_block_message,
+    format_command_for_terminal,
+    generate_policy_exception_command,
+    generate_unblock_command,
+    get_terminal_width,
+)
+from scc_cli.utils.ttl import (
+    DEFAULT_TTL,
+    MAX_TTL,
+    calculate_expiration,
+    format_expiration,
+    format_relative,
+    parse_expires_at,
+    parse_ttl,
+    parse_until,
+    validate_ttl_duration,
+)
+
+__all__ = [
+    # TTL utilities
+    "DEFAULT_TTL",
+    "MAX_TTL",
+    "calculate_expiration",
+    "format_expiration",
+    "format_relative",
+    "parse_expires_at",
+    "parse_ttl",
+    "parse_until",
+    "validate_ttl_duration",
+    # Fix-it utilities
+    "format_block_message",
+    "format_command_for_terminal",
+    "generate_policy_exception_command",
+    "generate_unblock_command",
+    "get_terminal_width",
+]

scc_cli/utils/fixit.py

@@ -0,0 +1,264 @@
+"""Provide fix-it command generation utilities.
+
+Generate ready-to-copy commands for blocked or denied items,
+helping users quickly unblock themselves.
+
+Two types of fix-it commands:
+- Unblock commands: For delegation denials (local override)
+- Policy exception commands: For security blocks (requires PR)
+"""
+
+from __future__ import annotations
+
+import re
+import shutil
+from typing import Literal
+
+
+def get_terminal_width() -> int:
+    """Get current terminal width.
+
+    Returns:
+        Terminal width in columns. Defaults to 80 if not detectable.
+    """
+    try:
+        size = shutil.get_terminal_size(fallback=(80, 24))
+        return max(40, min(size.columns, 500))  # Clamp to reasonable range
+    except Exception:
+        return 80
+
+
+def _needs_quoting(value: str) -> bool:
+    """Check if a value needs shell quoting.
+
+    Args:
+        value: The string to check
+
+    Returns:
+        True if the value contains special characters requiring quoting
+    """
+    # Simple alphanumeric with dashes, underscores, dots, colons, slashes
+    safe_pattern = r"^[a-zA-Z0-9_.\-:/]+$"
+    return not re.match(safe_pattern, value)
+
+
+def _shell_quote(value: str) -> str:
+    """Quote a value for safe shell usage.
+
+    Uses single quotes to prevent variable expansion.
+
+    Args:
+        value: The string to quote
+
+    Returns:
+        Safely quoted string
+    """
+    if not _needs_quoting(value):
+        return value
+
+    # Use single quotes, escape any existing single quotes
+    escaped = value.replace("'", "'\"'\"'")
+    return f"'{escaped}'"
+
+
+def _target_type_to_flag(target_type: str) -> str:
+    """Convert target type to CLI flag name.
+
+    Args:
+        target_type: One of "plugin", "mcp_server", "base_image"
+
+    Returns:
+        CLI flag name like "--allow-plugin"
+    """
+    type_map = {
+        "plugin": "--allow-plugin",
+        "mcp_server": "--allow-mcp",
+        "base_image": "--allow-image",
+    }
+    return type_map.get(target_type, f"--allow-{target_type}")
+
+
+def generate_unblock_command(
+    target: str,
+    target_type: str,
+    ttl: str = "8h",
+) -> str:
+    """Generate an unblock command for a delegation denial.
+
+    Args:
+        target: The denied item (plugin name, server name, image ref)
+        target_type: One of "plugin", "mcp_server", "base_image"
+        ttl: Time-to-live for the override (default 8h)
+
+    Returns:
+        Ready-to-copy unblock command
+    """
+    quoted_target = _shell_quote(target)
+    return f'scc unblock {quoted_target} --ttl {ttl} --reason "..."'
+
+
+def generate_policy_exception_command(
+    target: str,
+    target_type: str,
+    ttl: str = "8h",
+) -> str:
+    """Generate a policy exception command for a security block.
+
+    Args:
+        target: The blocked item (plugin name, server name, image ref)
+        target_type: One of "plugin", "mcp_server", "base_image"
+        ttl: Time-to-live for the exception (default 8h)
+
+    Returns:
+        Ready-to-copy policy exception command
+    """
+    flag = _target_type_to_flag(target_type)
+    quoted_target = _shell_quote(target)
+
+    return f'scc exceptions create --policy --id INC-... {flag} {quoted_target} --ttl {ttl} --reason "..."'
+
+
+def format_command_for_terminal(
+    command: str,
+    max_width: int | None = None,
+    indent: str = "    ",
+) -> str:
+    """Format a command to fit within terminal width.
+
+    For very long commands, breaks at logical points with backslash continuations.
+
+    Args:
+        command: The command to format
+        max_width: Maximum line width (defaults to terminal width)
+        indent: Indentation for continuation lines
+
+    Returns:
+        Formatted command (possibly multi-line)
+    """
+    if max_width is None:
+        max_width = get_terminal_width()
+
+    # If command fits, return as-is
+    if len(command) <= max_width:
+        return command
+
+    # Try to break at flag boundaries
+    parts = []
+    current_part = ""
+
+    # Split by spaces, keeping quoted strings together
+    tokens = _tokenize_command(command)
+
+    for token in tokens:
+        test_line = current_part + (" " if current_part else "") + token
+
+        if len(test_line) > max_width - 2 and current_part:  # -2 for " \"
+            parts.append(current_part + " \\")
+            current_part = indent + token
+        else:
+            current_part = test_line
+
+    if current_part:
+        parts.append(current_part)
+
+    return "\n".join(parts)
+
+
+def _tokenize_command(command: str) -> list[str]:
+    """Split a command into tokens, respecting quoted strings.
+
+    Args:
+        command: The command string
+
+    Returns:
+        List of tokens
+    """
+    tokens = []
+    current = ""
+    in_quotes = False
+    quote_char = ""
+
+    for char in command:
+        if char in "\"'" and not in_quotes:
+            in_quotes = True
+            quote_char = char
+            current += char
+        elif char == quote_char and in_quotes:
+            in_quotes = False
+            current += char
+        elif char == " " and not in_quotes:
+            if current:
+                tokens.append(current)
+                current = ""
+        else:
+            current += char
+
+    if current:
+        tokens.append(current)
+
+    return tokens
+
+
+def format_block_message(
+    target: str,
+    target_type: str,
+    block_type: Literal["security", "delegation"],
+    blocked_by: str | None = None,
+    reason: str | None = None,
+) -> str:
+    """Format a complete block/denial message with fix-it command.
+
+    Args:
+        target: The blocked/denied item
+        target_type: One of "plugin", "mcp_server", "base_image"
+        block_type: "security" for blocks, "delegation" for denials
+        blocked_by: Pattern that caused the block (for security blocks)
+        reason: Reason for denial (for delegation denials)
+
+    Returns:
+        Formatted message with fix-it command
+    """
+    lines = []
+
+    if block_type == "security":
+        # Security block message
+        type_display = _format_target_type(target_type)
+        lines.append(f'✗ {type_display} "{target}" blocked by org security policy')
+
+        if blocked_by:
+            lines.append(f"  Blocked by: {blocked_by}")
+
+        lines.append("")
+        lines.append("  To request policy exception (requires PR approval):")
+        cmd = generate_policy_exception_command(target, target_type)
+        lines.append(f"    {cmd}")
+
+    else:  # delegation
+        # Delegation denial message
+        type_display = _format_target_type(target_type)
+        denial_reason = reason or "team not delegated for additions"
+        lines.append(f'✗ {type_display} "{target}" denied: {denial_reason}')
+
+        lines.append("")
+        lines.append("  To unblock locally for 8h:")
+        cmd = generate_unblock_command(target, target_type)
+        lines.append(f"    {cmd}")
+
+    return "\n".join(lines)
+
+
+def _format_target_type(target_type: str) -> str:
+    """Format target type for display.
+
+    Args:
+        target_type: The internal target type
+
+    Returns:
+        Human-readable display name
+    """
+    type_map = {
+        "plugin": "Plugin",
+        "mcp_server": "MCP server",
+        "base_image": "Base image",
+    }
+    return type_map.get(target_type, target_type.replace("_", " ").title())

scc_cli/utils/fuzzy.py

@@ -0,0 +1,124 @@
+"""Provide fuzzy matching utilities for DX improvements.
+
+Offer fuzzy string matching to suggest corrections when users
+make typos or partial matches in CLI commands.
+
+Use Levenshtein-based similarity for >80% threshold matching.
+"""
+
+from __future__ import annotations
+
+
+def similarity_score(s1: str, s2: str) -> float:
+    """Calculate similarity score between two strings.
+
+    Uses normalized Levenshtein distance for similarity scoring.
+    Returns value between 0.0 (completely different) and 1.0 (identical).
+
+    The comparison is case-insensitive.
+
+    Args:
+        s1: First string
+        s2: Second string
+
+    Returns:
+        Similarity score from 0.0 to 1.0
+    """
+    # Handle edge cases
+    if not s1 and not s2:
+        return 1.0  # Both empty = identical
+    if not s1 or not s2:
+        return 0.0  # One empty = no similarity
+
+    # Case-insensitive comparison
+    s1_lower = s1.lower()
+    s2_lower = s2.lower()
+
+    # Calculate Levenshtein distance
+    distance = _levenshtein_distance(s1_lower, s2_lower)
+
+    # Normalize by max length to get similarity
+    max_len = max(len(s1_lower), len(s2_lower))
+    return 1.0 - (distance / max_len)
+
+
+def _levenshtein_distance(s1: str, s2: str) -> int:
+    """Calculate Levenshtein (edit) distance between two strings.
+
+    Uses dynamic programming approach for efficiency.
+
+    Args:
+        s1: First string
+        s2: Second string
+
+    Returns:
+        Minimum number of single-character edits needed
+    """
+    if len(s1) < len(s2):
+        return _levenshtein_distance(s2, s1)
+
+    if len(s2) == 0:
+        return len(s1)
+
+    # Use only two rows for space efficiency
+    previous_row = list(range(len(s2) + 1))
+    current_row = [0] * (len(s2) + 1)
+
+    for i, c1 in enumerate(s1):
+        current_row[0] = i + 1
+        for j, c2 in enumerate(s2):
+            # Cost is 0 if characters match, 1 otherwise
+            insertions = previous_row[j + 1] + 1
+            deletions = current_row[j] + 1
+            substitutions = previous_row[j] + (0 if c1 == c2 else 1)
+            current_row[j + 1] = min(insertions, deletions, substitutions)
+
+        previous_row, current_row = current_row, previous_row
+
+    return previous_row[len(s2)]
+
+
+def find_similar(
+    query: str,
+    candidates: list[str],
+    threshold: float = 0.8,
+    max_suggestions: int = 5,
+) -> list[str]:
+    """Find similar candidates to a query string.
+
+    Returns candidates that are similar to the query (above threshold),
+    sorted by similarity (most similar first).
+
+    If the query exactly matches a candidate, returns empty list
+    (caller should use the exact match, not suggestions).
+
+    Args:
+        query: The string to match against
+        candidates: List of possible matches
+        threshold: Minimum similarity score (0.0-1.0), default 0.8
+        max_suggestions: Maximum number of suggestions to return
+
+    Returns:
+        List of similar candidates, sorted by similarity (most similar first)
+    """
+    if not candidates:
+        return []
+
+    # Check for exact match (case-insensitive)
+    query_lower = query.lower()
+    for candidate in candidates:
+        if candidate.lower() == query_lower:
+            return []  # Exact match found, no suggestions needed
+
+    # Calculate similarity scores for all candidates
+    scored: list[tuple[str, float]] = []
+    for candidate in candidates:
+        score = similarity_score(query, candidate)
+        if score >= threshold:
+            scored.append((candidate, score))
+
+    # Sort by similarity (descending), then by name (for stable ordering)
+    scored.sort(key=lambda x: (-x[1], x[0]))
+
+    # Return top suggestions
+    return [candidate for candidate, _ in scored[:max_suggestions]]

scc_cli/utils/locks.py

@@ -0,0 +1,101 @@
+"""Simple cross-platform file locking utilities."""
+
+from __future__ import annotations
+
+import errno
+import hashlib
+import os
+import time
+from contextlib import contextmanager
+from pathlib import Path
+
+try:
+    import fcntl  # type: ignore[import-not-found]
+except ImportError:  # pragma: no cover - Windows fallback
+    fcntl = None
+
+try:
+    import msvcrt  # type: ignore[import-not-found]
+except ImportError:  # pragma: no cover - non-Windows fallback
+    msvcrt = None
+
+LOCK_DIR = Path(os.environ.get("XDG_CACHE_HOME", Path.home() / ".cache")) / "scc" / "locks"
+DEFAULT_TIMEOUT = 5.0
+
+
+def _normalize_key(key: str | Path) -> str:
+    path = Path(key).expanduser()
+    try:
+        return str(path.resolve(strict=False))
+    except OSError:
+        return str(path.absolute())
+
+
+def lock_path(namespace: str, key: str | Path | None = None) -> Path:
+    """Return a stable lock file path for a namespace/key pair."""
+    LOCK_DIR.mkdir(parents=True, exist_ok=True)
+    if key is None:
+        filename = f"{namespace}.lock"
+    else:
+        digest = hashlib.sha256(_normalize_key(key).encode()).hexdigest()[:16]
+        filename = f"{namespace}-{digest}.lock"
+    return LOCK_DIR / filename
+
+
+def _acquire_lock(lock_file: os.PathLike[str] | os.PathLike[bytes] | int) -> None:
+    if fcntl is not None:
+        fcntl.flock(lock_file.fileno(), fcntl.LOCK_EX | fcntl.LOCK_NB)
+        return
+    if msvcrt is not None:
+        msvcrt.locking(lock_file.fileno(), msvcrt.LK_NBLCK, 1)
+        return
+
+
+def _release_lock(lock_file: os.PathLike[str] | os.PathLike[bytes] | int) -> None:
+    if fcntl is not None:
+        fcntl.flock(lock_file.fileno(), fcntl.LOCK_UN)
+        return
+    if msvcrt is not None:
+        try:
+            msvcrt.locking(lock_file.fileno(), msvcrt.LK_UNLCK, 1)
+        except OSError:
+            pass
+
+
+@contextmanager
+def file_lock(path: Path, *, timeout: float = DEFAULT_TIMEOUT, poll: float = 0.1):
+    """Acquire an exclusive file lock with a timeout."""
+    path.parent.mkdir(parents=True, exist_ok=True)
+    lock_file = path.open("a+")
+    acquired = False
+    start = time.monotonic()
+
+    try:
+        while True:
+            try:
+                _acquire_lock(lock_file)
+                acquired = True
+                break
+            except OSError as e:
+                if e.errno not in (errno.EACCES, errno.EAGAIN):
+                    raise
+            except BlockingIOError:
+                pass
+
+            if time.monotonic() - start >= timeout:
+                raise TimeoutError(f"Timed out waiting for lock: {path}")
+            time.sleep(poll)
+
+        try:
+            lock_file.seek(0)
+            lock_file.truncate()
+            lock_file.write(str(os.getpid()))
+            lock_file.flush()
+        except OSError:
+            pass
+
+        yield
+    finally:
+        if acquired:
+            _release_lock(lock_file)
+        lock_file.close()