Improve Run Command Output with Service URLs

[josecelano]

Overview

Enhance the run command output to display service URLs immediately after services start, plus a hint about the show command for full details. This improves actionability by giving users immediate access to their services without requiring a separate command.

Specification

See detailed specification: docs/issues/334-improve-run-command-output-with-service-urls.md

🏗️ Architecture Requirements

DDD Layer: Presentation
Module Path: src/presentation/controllers/run/ and src/presentation/views/commands/shared/
Pattern: View composition with shared service URL views

Module Structure Requirements

• Create shared view module: src/presentation/views/commands/shared/service_urls/
• Extract URL rendering logic from show command views
• Reuse shared views in both run and show commands
• Follow DDD layer separation (see docs/codebase-architecture.md)

Architectural Constraints

• Reuse service URL rendering logic from show command
• Show subset of information: only service URLs (no SSH, internal ports)
• Include DNS note for TLS environments
• Error handling follows project conventions (see docs/contributing/error-handling.md)
• Output handling follows project conventions (see docs/contributing/output-handling.md)

Anti-Patterns to Avoid

• ❌ Duplicating URL rendering logic between commands
• ❌ Mixing business logic with presentation formatting
• ❌ Using println! or eprintln! instead of UserOutput
• ❌ Showing internal-only services (localhost addresses) without context

Implementation Plan

Phase 1: Extract Shared View Components

Goal: Create reusable view components for service URL rendering

• Create src/presentation/views/commands/shared/ directory
• Create src/presentation/views/commands/shared/service_urls/ module
• Extract URL formatting logic from existing views
• Add unit tests for shared views
• Update show command to use shared views

Phase 2: Enhance Run Command Output

Goal: Add service URLs to run command completion message

• Modify RunCommandController::complete_workflow()
• Load environment info after services start
• Render service URLs using shared views
• Add DNS hint for TLS environments
• Add tip about show command

Phase 3: Testing & Documentation

Goal: Ensure quality and document the changes

• Add unit tests for new shared views
• Add integration tests for run command output
• Update E2E tests
• Update user documentation

Time Estimate: 4-6 hours

Acceptance Criteria

Note for Contributors: These criteria define what the PR reviewer will check. Use this as your pre-review checklist before submitting the PR to minimize back-and-forth iterations.

Quality Checks:

• Pre-commit checks pass: ./scripts/pre-commit.sh

Task-Specific Criteria:

Output Requirements:

• Run command displays service URLs after success message
• Output includes all publicly accessible services
• Health Check URL included only if publicly exposed (not localhost)
• Prometheus not shown (internal only)
• TLS environments show DNS configuration note
• Tip about show command always displayed

Code Quality:

• Shared view module created in src/presentation/views/commands/shared/service_urls/
• URL rendering logic extracted and reused from show command
• No duplication between run and show command views
• Uses UserOutput methods (no println! or eprintln!)
• Output goes to stdout via ProgressReporter::result()

Testing:

• Unit tests for shared views
• Integration tests for run command output
• E2E tests verify service URLs in output
• Tests cover both HTTP and HTTPS scenarios

Documentation:

• User guide updated with new output examples
• Console commands documentation updated
• Reference outputs updated

Related

• Roadmap: Roadmap #1 (Section 10 - Improve usability)
• Specification: docs/issues/334-improve-run-command-output-with-service-urls.md