library-design-patterns

Library Design Patterns Skill

Standardized architectural patterns for Python library design in the autonomous-dev plugin ecosystem. Promotes reusability, testability, security, and maintainability through proven design patterns.

When This Skill Activates

• Creating new Python libraries
• Refactoring existing libraries
• Designing reusable components
• Implementing CLI interfaces
• Validating library architecture
• Keywords: "library", "module", "two-tier", "progressive enhancement", "cli", "api"

Core Design Patterns

1. Two-Tier Design Pattern

Definition: Separate core logic (library) from user interface (CLI script) to maximize reusability and testability.

Structure:

• Tier 1 (Core Library): Pure Python module with business logic, no I/O assumptions
• Tier 2 (CLI Interface): Thin wrapper script for command-line usage, handles argparse and user interaction

Benefits:

• Reusability: Core logic can be imported and reused in other contexts
• Testability: Pure functions are easier to unit test without mocking I/O
• Separation of Concerns: Business logic separate from presentation layer
• Maintainability: Changes to CLI don't affect core logic and vice versa

Example:

plugin_updater.py       # Core library - pure logic
update_plugin.py        # CLI interface - user interaction

When to Use:

• Any library that might be used both programmatically and from command line
• Complex business logic that needs thorough testing
• Features that may be integrated into multiple workflows

See: docs/two-tier-design.md, templates/library-template.py, examples/two-tier-example.py

2. Progressive Enhancement Pattern

Definition: Start with simple validation (strings), progressively add stronger validation (Path objects, whitelists) without breaking existing code.

Progression:

1. Level 1 (Strings): Accept string paths, basic validation
2. Level 2 (Path Objects): Convert to pathlib.Path, add existence checks
3. Level 3 (Whitelist Validation): Restrict to approved directories, prevent path traversal

Benefits:

• Graceful Degradation: Works in degraded environments (missing dependencies)
• Backward Compatibility: Existing code continues to work
• Security Hardening: Stronger validation added over time without breaking changes
• Flexibility: Can operate in various security contexts

Example:

# Level 1: Accept strings
def process(file: str) -> Result:
    return _process_path(file)

# Level 2: Upgrade to Path objects
def process(file: Union[str, Path]) -> Result:
    path = Path(file) if isinstance(file, str) else file
    if not path.exists():
        raise FileNotFoundError(f"File not found: {path}")
    return _process_path(path)

# Level 3: Add whitelist validation
def process(file: Union[str, Path], *, allowed_dirs: Optional[List[Path]] = None) -> Result:
    path = Path(file) if isinstance(file, str) else file
    if allowed_dirs and not any(path.is_relative_to(d) for d in allowed_dirs):
        raise SecurityError(f"Path outside allowed directories: {path}")
    if not path.exists():
        raise FileNotFoundError(f"File not found: {path}")
    return _process_path(path)

See: docs/progressive-enhancement.md, examples/progressive-enhancement-example.py

3. Non-Blocking Enhancement Pattern

Definition: Design enhancements (features beyond core functionality) to never block core operations. If enhancement fails, core feature should still succeed.

Principles:

• Core operations must complete even if enhancements fail
• Enhancements wrapped in try/except with graceful degradation
• Log enhancement failures but don't raise exceptions
• Provide manual fallback instructions if enhancement unavailable

Benefits:

• Reliability: Core features always work
• Resilience: Graceful handling of missing dependencies or permissions
• User Experience: Clear feedback when enhancements unavailable
• Maintainability: Easier to add/remove enhancements without breaking core

Example:

def implement_feature(spec: FeatureSpec) -> Result:
    # Core operation (must succeed)
    result = _implement_core_logic(spec)

    # Enhancement: Auto-commit (may fail)
    try:
        if auto_commit_enabled():
            commit_changes(result.files)
    except Exception as e:
        logger.warning(f"Auto-commit failed: {e}")
        logger.info("Manual fallback: git add . && git commit")

    # Feature succeeded regardless of enhancement
    return result

See: docs/non-blocking-enhancements.md, examples/non-blocking-example.py

4. Security-First Design Pattern

Definition: Build security validation into library architecture from the start. Validate all inputs, sanitize outputs, audit all operations.

Core Principles:

• Input Validation: Validate all user input against expected types and ranges
• Path Traversal Prevention (CWE-22): Use whitelists, resolve paths, check boundaries
• Command Injection Prevention (CWE-78): Use subprocess arrays, avoid shell=True
• Log Injection Prevention (CWE-117): Sanitize all log messages, escape newlines
• Audit Logging: Log security-relevant operations to audit trail

Security Layers:

1. Input Validation: Type checking, range validation, format verification
2. Path Validation: Whitelist checking, symlink resolution, boundary verification
3. Command Validation: Argument array construction, shell prevention
4. Output Sanitization: Log message escaping, error message filtering
5. Audit Trail: Security operations logged to logs/security_audit.log

Example:

from plugins.autonomous_dev.lib.security_utils import validate_path, audit_log

def process_file(filepath: str, *, allowed_dirs: List[Path]) -> None:
    """Process file with security validation.

    Security:
        - CWE-22 Prevention: Path traversal validation
        - CWE-117 Prevention: Sanitized audit logging
    """
    # Validate path (CWE-22 prevention)
    safe_path = validate_path(
        filepath,
        must_exist=True,
        allowed_dirs=allowed_dirs
    )

    # Audit security operation (CWE-117 safe)
    audit_log("file_processed", filepath=str(safe_path))

    # Process file
    return _process(safe_path)

See: docs/security-patterns.md, examples/security-validation-example.py

5. Docstring Standards Pattern

Definition: Consistent Google-style docstrings with comprehensive documentation for all public APIs.

Structure:

def function(arg1: Type1, arg2: Type2, *, kwarg: Type3 = default) -> ReturnType:
    """One-line summary (imperative mood).

    Optional detailed description explaining behavior, edge cases,
    and important implementation details.

    Args:
        arg1: Description of first argument
        arg2: Description of second argument
        kwarg: Description of keyword argument (default: value)

    Returns:
        Description of return value and its structure

    Raises:
        ExceptionType: When and why this exception is raised
        AnotherException: Another error condition

    Example:
        >>> result = function("value1", "value2", kwarg="custom")
        >>> print(result.status)
        'success'

    Security:
        - CWE-XX: How this function prevents security issue
        - Validation: What input validation is performed

    See:
        - Related function or documentation
        - External reference or skill
    """

Required Sections:

• Summary line (one line, imperative mood)
• Args section (all parameters documented)
• Returns section (return value structure)
• Raises section (all exceptions)
• Security section (for security-sensitive functions)

See: docs/docstring-standards.md, templates/docstring-template.py

Usage Guidelines

For Library Authors

When creating or refactoring libraries:

1. Use two-tier design for any library with CLI in