feat: add dbt profile init command with type-safe models

[pgoell]

Add brix dbt profile init command to initialize dbt profiles from a
bundled template. Features:

• Pydantic models for type-safe profile parsing (DbtProfiles, DuckDbOutput)
• Template loading via importlib.resources for package-bundled templates
• Default DuckDB template for local development
• BRIX_DBT_PROFILE_PATH env var to override default ~/.dbt/profiles.yml
• --force flag to overwrite existing profiles
• brix dbt profile show to display current profile configuration

Also adds comprehensive unit tests for models, service layer, and CLI.

[pgoell]

/review

[claude]

PR Review: Add dbt profile init command with type-safe models

Summary

This PR adds a comprehensive profile management system for dbt with CLI commands, type-safe Pydantic models, and both interactive and non-interactive editing modes. Overall, this is a well-structured and thoughtful implementation with good separation of concerns and comprehensive test coverage.

---

Code Quality & Best Practices ✅

Strengths

1. Excellent architecture - Clean separation between models, service layer, editor logic, and CLI commands
2. Type safety - Proper use of Pydantic models with discriminated unions for extensibility
3. Comprehensive testing - Unit tests cover models, service layer, and CLI with good edge case coverage
4. Good error handling - Custom exception classes with clear error messages
5. Documentation - Well-documented functions with Google-style docstrings per project standards
6. Follows project conventions - Adheres to CLAUDE.md guidelines (ruff formatting, type hints, etc.)

Areas for Improvement

1. Security Concern: YAML Deserialization (Medium Priority)

Location: src/brix/modules/dbt/profile/models.py:66-71

def from_yaml(cls, content: str) -> DbtProfiles:
    import yaml
    try:
        data = yaml.safe_load(content)  # Good - using safe_load

✅ Good: Using yaml.safe_load() instead of yaml.load() prevents arbitrary code execution.

However, there's a potential issue in the YAML serialization:

Location: src/brix/modules/dbt/profile/models.py:97-105

def to_yaml(self) -> str:
    import yaml
    return yaml.dump(
        self.root,
        default_flow_style=False,
        allow_unicode=True,
        sort_keys=False,
    )

Issue: The yaml.dump() doesn't use Dumper=yaml.SafeDumper. While this isn't a security vulnerability per se (dumping is generally safe), it's inconsistent and could serialize Python objects in unexpected ways.

Recommendation:

def to_yaml(self) -> str:
    import yaml
    return yaml.dump(
        self.root,
        Dumper=yaml.SafeDumper,  # Add explicit safe dumper
        default_flow_style=False,
        allow_unicode=True,
        sort_keys=False,
    )

2. Potential Bug: Missing Validation After Output Deletion

Location: src/brix/modules/dbt/profile/editor.py:279-282

if len(profiles.root[profile_name].outputs) == 1:
    msg = f"Cannot delete last output from profile '{profile_name}'. Delete the profile instead."
    raise ValueError(msg)

Issue: This prevents deleting the last output, but doesn't validate if the current target points to the output being deleted. If you delete an output that's set as the target, the profile becomes invalid.

Recommendation: Add validation:

def delete_output(profiles: DbtProfiles, profile_name: str, output_name: str) -> DbtProfiles:
    # ... existing checks ...
    
    # Check if deleting the current target
    profile = profiles.root[profile_name]
    if profile.target == output_name:
        msg = f"Cannot delete output '{output_name}' as it is the current target. Change target first."
        raise ValueError(msg)
    
    if len(profile.outputs) == 1:
        msg = f"Cannot delete last output from profile '{profile_name}'. Delete the profile instead."
        raise ValueError(msg)

3. Code Duplication in CLI Command Handler

Location: src/brix/commands/dbt/profile.py:182-234

The _dispatch_cli_action function has a long if/elif chain that could be refactored using a strategy pattern or dispatch table:

# Current approach
def _dispatch_cli_action(action, ...):
    if action == "add-profile":
        _handle_add_profile(...)
    elif action == "edit-profile":
        _handle_edit_profile(...)
    # ... etc

Recommendation:

ACTION_HANDLERS = {
    "add-profile": _handle_add_profile,
    "edit-profile": _handle_edit_profile,
    "delete-profile": _handle_delete_profile_cli,
    "add-output": _handle_add_output_cli,
    "edit-output": _handle_edit_output_cli,
    "delete-output": _handle_delete_output_cli,
}

def _dispatch_cli_action(action: ActionType, ...):
    handler = ACTION_HANDLERS.get(action)
    if handler:
        handler(profiles, target_path, profile, output, target, path_value, threads, force)

This is more maintainable and follows DRY principles.

4. Missing Input Validation

Location: src/brix/modules/dbt/profile/editor.py:240-250

def update_output(profiles, profile_name, output_name, *, path=None, threads=None):
    # ... checks ...
    if path is not None:
        output.path = path
    if threads is not None:
        output.threads = threads

Issue: No validation on threads value (should be positive integer). While Pydantic will validate when saving, it's better to fail fast with a clear error.

Recommendation:

if threads is not None:
    if threads < 1:
        msg = "threads must be a positive integer"
        raise ValueError(msg)
    output.threads = threads

5. Inconsistent Error Handling Pattern

Location: src/brix/commands/dbt/profile.py:71-80

try:
    result = init_profile(profile_path=profile_path, force=force)
    typer.echo(result.message)
except ProfileExistsError as e:
    typer.echo(str(e), err=True)
    raise typer.Exit(1) from None  # from None suppresses traceback
except FileNotFoundError as e:
    typer.echo(f"Template error: {e}", err=True)
    raise typer.Exit(1) from None

The from None pattern suppresses exception context, which can make debugging harder. Consider using from e to preserve the chain or document why context is being suppressed.

---

Performance Considerations ⚡

1. Template Loading Efficiency

Location: src/brix/modules/dbt/profile/service.py:84-91

def load_template(name: str = "default.yml") -> str:
    import importlib.resources as ir
    template_text = ir.files("brix.modules.dbt.profile.templates").joinpath(name).read_text()

✅ Good: Using importlib.resources for package-bundled templates is the correct approach for Python 3.10+.

2. File I/O Pattern

The code reads/writes YAML files synchronously, which is appropriate for CLI usage. No concerns here.

3. Pydantic Model Performance

The use of model_config = ConfigDict(extra="allow") permits extra fields, which is good for forward compatibility with dbt but adds slight overhead. This is an acceptable trade-off.

---

Security Concerns 🔒

1. Path Traversal Protection ✅

Location: src/brix/modules/dbt/profile/service.py:28-34

def get_default_profile_path() -> Path:
    profile_path_str = os.environ.get("BRIX_DBT_PROFILE_PATH")
    if profile_path_str:
        return Path(profile_path_str).expanduser().resolve()
    return Path.home() / ".dbt" / "profiles.yml"

✅ Good: Using .resolve() prevents path traversal attacks via symlinks.

2. File Permissions

Location: src/brix/modules/dbt/profile/editor.py:69

target_path.write_text(yaml_content)

Minor concern: No explicit file permissions set. dbt profiles can contain database credentials, so consider:

target_path.write_text(yaml_content)
target_path.chmod(0o600)  # Owner read/write only

3. Command Injection

No shell commands or subprocess calls detected. ✅ Safe.

---

Test Coverage 📊

Strengths

1. Comprehensive unit tests for models, service layer, and editor functions
2. Good edge case coverage - tests for errors, validation, file I/O
3. Uses pytest fixtures appropriately for test isolation
4. Integration test markers properly used

Missing Test Cases

1. Concurrent access - What happens if two processes modify profiles.yml simultaneously?
2. Large profile files - Performance/limits testing
3. Malformed YAML - More edge cases (e.g., YAML bombs, deeply nested structures)
4. Interactive mode - The questionary-based interactive editor (prompts.py) appears to lack tests
5. File permission errors - Test behavior when profile path is not writable

Recommendation

Add tests for the interactive prompts module, perhaps using questionary's testing utilities or mocking.

---

Additional Observations

1. Deleted Test Workflow ❓

The PR deletes .github/workflows/test.yml. Was this intentional? This removes CI testing on pull requests, which could lead to undetected regressions.

Recommendation: If the workflow was moved elsewhere, please clarify. Otherwise, consider restoring it.

2. questionary Dependency

A new dependency questionary>=2.1.1 was added for interactive prompts. This is a well-maintained library, but:

• Ensure it aligns with your dependency management strategy
• Consider if the interactive features are critical or could be optional

3. Whitespace-Only Change

Location: .pre-commit-config.yaml:20

-        entry: uv run pytest
+        entry: uv run pytest 

Trailing whitespace added - likely unintentional. Run uv run poe format to clean this up.

4. pyproject.toml Formatting

The reformatting of pyproject.toml appears to be automatic (ruff/formatter). Ensure this doesn't conflict with other PRs in flight.

---

Recommendations Summary

Must Fix (Before Merge)

1. ✅ Restore .github/workflows/test.yml or clarify why it was removed
2. ⚠️ Add validation in delete_output to prevent deleting the current target
3. 🔧 Remove trailing whitespace in .pre-commit-config.yaml

Should Fix (High Priority)

4. 🛡️ Use yaml.SafeDumper in to_yaml() for consistency
5. ✅ Add file permissions (0o600) when writing profiles.yml
6. ✅ Add input validation for threads parameter

Nice to Have (Medium Priority)

7. ♻️ Refactor _dispatch_cli_action to use dispatch table
8. 📝 Add tests for interactive prompts module
9. 🧪 Add tests for edge cases (concurrent access, permission errors)
10. 📚 Consider documenting the extension pattern for new adapter types (beyond DuckDB)

---

Conclusion

This is a high-quality PR with thoughtful design and good engineering practices. The code is well-structured, follows project conventions, and includes comprehensive tests. The concerns raised are mostly minor improvements and defensive programming suggestions.

Recommendation: Approve with minor revisions (address the "Must Fix" items above).

Great work! 🎉

---

Generated with Claude Code