[subtask] [Subtask 4/4] Add comprehensive tests and documentation for OCI authentication

[github-actions]

Parent Issue: #559

Objective

Complete the OCI authentication feature by adding comprehensive tests and updating all relevant documentation.

Context

Subtasks 1-3 implemented the core OCI authentication functionality across CLI, loader, and MCP tools. This final subtask ensures the feature is production-ready with proper testing, documentation, and examples.

Implementation Details

Testing Tasks

1. Add comprehensive unit tests:

   • File: crates/wassette/src/oci_auth.rs

     • Test Docker config parsing with various config formats
     • Test registry matching (exact match, wildcards)
     • Test base64 credential decoding
     • Test fallback to Anonymous
     • Test error handling for malformed configs

   • File: tests/oci_auth_test.rs (new file)

     • Test authentication with mock registry
     • Test precedence: explicit > Docker config > Anonymous
     • Test environment variable reading
     • Test CLI flag combinations

2. Add integration tests:

   • File: tests/oci_integration_test.rs (extend existing)
     • Add test for loading from authenticated registry
     • Test Docker config authentication flow
     • Test explicit credentials flow
     • Test MCP tool with authentication
     • Note: May use mock/test registry or skip if external registry unavailable

3. Add OCI authentication section to existing tests:

   • Update tests/cli_integration_test.rs to test new CLI flags
   • Verify --help output includes new authentication options

Documentation Tasks

1. Update docs/cookbook/publishing-to-oci-registries.md:

   • Add section "Loading Private Components"
   • Document Docker config authentication (recommended method)
   • Document CLI flag authentication
   • Document environment variable authentication
   • Add security best practices section
   • Add troubleshooting guide for auth errors

2. Update docs/reference/cli.md (if exists):

   • Document --registry-user, --registry-password, --registry-password-stdin flags
   • Document OCI_REGISTRY_USER and OCI_REGISTRY_PASSWORD environment variables
   • Add examples of loading private components

3. Update README.md (if appropriate):

   • Add note about private registry support in features section

4. Add new documentation file docs/cookbook/private-registries.md:

   • Comprehensive guide on using private registries
   • Authentication methods comparison table
   • CI/CD integration examples
   • Security considerations
   • Common issues and solutions

Example Code Updates

1. Update examples/ if necessary:
   • Consider adding an example showing private component loading
   • Add comments explaining authentication options

Documentation Content Outline

docs/cookbook/private-registries.md:

# Using Private OCI Registries

## Authentication Methods

Wassette supports three authentication methods for private OCI registries:

1. **Docker Config (Recommended)**
2. **CLI Flags**
3. **Environment Variables**

[Details for each method with examples]

## Setting Up Authentication

### Method 1: Docker Config (Recommended)
[How to configure Docker config]

### Method 2: CLI Flags
[Examples with CLI flags]

### Method 3: Environment Variables
[Examples with env vars]

## Security Best Practices

- Use Docker config for local development
- Use environment variables in CI/CD
- Use `--registry-password-stdin` to avoid shell history
- Never commit credentials to version control
- Rotate credentials regularly

## Troubleshooting

### Common Issues
[Error messages and solutions]

## CI/CD Integration

[Examples for GitHub Actions, GitLab CI, etc.]

Acceptance Criteria

Testing

• Unit tests for oci_auth.rs with >80% coverage
• Integration tests for all authentication methods
• CLI flag tests pass
• MCP tool authentication tests pass
• All existing tests continue to pass
• Test coverage for error cases

Documentation

• docs/cookbook/publishing-to-oci-registries.md updated with private registry section
• docs/cookbook/private-registries.md created with comprehensive guide
• CLI --help output documents new flags
• README.md mentions private registry support (if appropriate)
• Code examples include authentication usage
• Security best practices documented

Code Quality

• All code has proper doc comments
• Error messages are clear and actionable
• No clippy warnings
• Code formatted with cargo +nightly fmt
• Copyright headers on all new files

Testing Strategy

1. Automated tests:

   # Run all tests
   just test
   
   # Run specific auth tests
   cargo test oci_auth
   cargo test --test oci_integration_test

2. Manual testing with MCP inspector:

   # Test with Docker config
   just run
   npx `@modelcontextprotocol/inspector` --cli (redacted) \
     --method tools/call --tool-name load-component \
     --tool-arg path=(redacted)
   
   # Test with explicit credentials
   npx `@modelcontextprotocol/inspector` --cli (redacted) \
     --method tools/call --tool-name load-component \
     --tool-arg path=(redacted) \
     --tool-arg registry_user=user \
     --tool-arg registry_password=pass

3. Documentation validation:

   # Build and serve docs locally
   just docs-serve
   # Verify all links work and examples are correct

Dependencies

Depends on Subtasks 1, 2, and 3 being completed.

Validation Checklist

Before closing this subtask, verify:

• Can load private component using Docker config
• Can load private component using CLI flags
• Can load private component using environment variables
• Can load private component via MCP tool
• Error messages are helpful when authentication fails
• Documentation is clear and comprehensive
• All tests pass in CI
• No regressions in existing functionality
  Related to OCI auth in Wassette component subcommand #559

AI generated by Plan for #559

[asw101]

Closing [subtask]s of parent issues.