/library-design-patterns

name: library-design-patterns
description: "Two-tier design, progressive enhancement, non-blocking patterns, and security-first architecture for Python libraries. Use when creating or refactoring Python libraries. TRIGGER when: library design, module architecture, reusable component, two-tier. DO NOT TRIGGER when: simple scripts, config files, documentation-only changes."
allowed-tools: [Read]

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. **Audi