Add pipe-delimited usecase filtering for Cloud Run deployments

[dandye]

Summary

• Implement LOGSTORY_USECASES environment variable for filtering usecases in 'replay all' command
• Use pipe separator to avoid gcloud argument parsing issues with commas
• Add validation for requested usecases with helpful error messages
• Maintain backward compatibility - no filtering when LOGSTORY_USECASES not set

Changes

• Add pipe-delimited parsing in replay_all_usecases function
• Update documentation across README, configuration guides, and testing docs
• Add comprehensive testing guide for pipe-delimited functionality
• Environment variable filtering avoids Cloud Run gcloud argument parsing issues

Test plan

• Local testing with pipe-separated usecases works correctly
• Cloud Run deployment successfully filters usecases using environment variables
• Backward compatibility maintained when LOGSTORY_USECASES not set
• Error handling provides helpful messages for invalid usecases

Resolves Cloud Run deployment issues with comma-separated usecase arguments by implementing a clean environment variable-based filtering approach.

[dandye]

@claude pls review

[claude]

Claude finished @dandye's task —— View job

---

Code Review Complete ✅

I've completed the review of the pipe-delimited usecase filtering implementation. This is a well-designed solution that effectively addresses Cloud Run deployment issues with comma-separated arguments.

Todo List:

• Read and understand the PR changes
• Analyze core implementation in logstory.py
• Review documentation updates
• Check for bugs, security issues, and best practices
• Post comprehensive code review feedback

Summary

This PR implements a clean environment variable-based approach to filtering usecases in the replay all command, using pipe-delimited values to avoid gcloud argument parsing issues. The implementation maintains backward compatibility while providing clear error handling and user feedback.

✅ Strengths

1. Smart separator choice: Using pipes (|) instead of commas avoids gcloud parsing issues while being intuitive for users
2. Robust validation: Comprehensive validation of requested usecases with helpful error messages
3. Backward compatibility: No filtering when LOGSTORY_USECASES is unset preserves existing behavior
4. Clear user feedback: Logs clearly indicate whether filtering is active and which usecases are being processed
5. Consistent code style: Implementation follows existing patterns and adheres to the 2-space indentation standard
6. Comprehensive documentation: Excellent documentation with testing guides, examples, and troubleshooting

🔍 Implementation Analysis

Core Logic (src/logstory/logstory.py:898-914)

The implementation is clean and follows good practices:

# Filter usecases if LOGSTORY_USECASES environment variable is set
filter_usecases = os.getenv("LOGSTORY_USECASES")
if filter_usecases:
  # Parse pipe-separated list and filter
  requested_usecases = [uc.strip() for uc in filter_usecases.split("|") if uc.strip()]
  # Validate that requested usecases exist
  invalid_usecases = [uc for uc in requested_usecases if uc not in all_usecases]
  if invalid_usecases:
    typer.echo(f"Error: Invalid usecases: {', '.join(invalid_usecases)}")
    typer.echo(f"Available usecases: {', '.join(sorted(all_usecases))}")
    raise typer.Exit(1)
  usecases = requested_usecases
  typer.echo(f"Processing filtered usecases: {', '.join(usecases)}")
else:
  usecases = all_usecases
  typer.echo(f"Processing all usecases: {', '.join(usecases)}")

Positive aspects:

• Proper input sanitization with .strip() and filtering empty strings
• Comprehensive validation against available usecases
• Clear error messages showing both invalid and available usecases
• Informative logging for both filtered and unfiltered scenarios

Documentation Updates

The documentation updates are thorough and well-structured:

• README.md: Added clear examples and usage patterns
• docs/configuration.md: Comprehensive integration with existing config docs
• docs/env-file.md: Proper inclusion in environment variable reference
• docs/testing-pipe-delimited-usecases.md: Excellent standalone testing guide

🛡️ Security & Best Practices

• ✅ Input validation: Proper sanitization and validation of environment variable input
• ✅ Error handling: Graceful handling of invalid usecases with helpful messages
• ✅ No injection risks: Simple string splitting with no dynamic execution
• ✅ Fail-safe design: Defaults to processing all usecases when variable is unset

🔧 Minor Suggestions

1. Consider case sensitivity: The current implementation is case-sensitive. Consider whether case-insensitive matching would be more user-friendly:

   # Current
   invalid_usecases = [uc for uc in requested_usecases if uc not in all_usecases]
   
   # Potential improvement
   all_usecases_lower = {uc.lower(): uc for uc in all_usecases}
   normalized_requested = []
   invalid_usecases = []
   for uc in requested_usecases:
       if uc.lower() in all_usecases_lower:
           normalized_requested.append(all_usecases_lower[uc.lower()])
       else:
           invalid_usecases.append(uc)

2. Empty filter handling: Consider explicit handling of empty environment variable:

   filter_usecases = os.getenv("LOGSTORY_USECASES", "").strip()
   if filter_usecases:  # This would handle whitespace-only values

✅ Testing & Verification

The testing guide in docs/testing-pipe-delimited-usecases.md is comprehensive and covers:

• Local testing scenarios
• Cloud Run deployment testing
• Error handling validation
• Success indicators and log analysis

🎯 Recommendation

APPROVE - This is a well-implemented solution that:

• Effectively solves the Cloud Run gcloud parsing issues
• Maintains full backward compatibility
• Includes comprehensive documentation and testing guidance
• Follows project coding standards
• Provides excellent user experience with clear feedback

The minor suggestions above are purely optional enhancements and don't impact the core functionality or correctness of the implementation.

---