Skip to content

Add global banner for top-level dev-tools execution with orchestration-safe suppression #277

@coisa

Description

@coisa

Problem

dev-tools currently shows the ASCII logo only through DevTools::getHelp(), which means it appears on help paths (help/list) but not on normal command execution.

When attempting to print the logo in the execution path, orchestrator commands that spawn nested dev-tools processes (for example dev-tools:standards) duplicate the logo across internal subprocesses.

Proposal

Show the ASCII logo in top-level CLI runs only, without using environment variables, and keep nested orchestrated dev-tools runs silent regarding the logo.

Goals

  • Print the ASCII header at application startup for direct user-invoked dev-tools commands.
  • Avoid per-command edits in orchestrators and nested command implementations.
  • Keep list/help behavior unchanged or intentionally improved with no regressions.
  • Ensure no repeated header when internal ProcessQueue spawns dev-tools subprocesses.

Expected Behavior

  • Running vendor/bin/dev-tools <command> prints the logo once, before command output.
  • Running vendor/bin/dev-tools:standards (or dev-tools:standards) also prints the logo once at the top-level invocation.
  • Orchestrated sub-invocations of vendor/bin/dev-tools <subcommand> do not print the logo.
  • Non-dev-tools subprocesses remain unaffected.

Implementation Strategy

  1. Add a internal option on DevTools input definition (example: --no-logo) to indicate an orchestrated child invocation.
  2. In DevTools::run() or doRun(), print the logo only when this flag is not present.
  3. Centralize flag injection in ProcessBuilder (or another shared process-construction layer), so when building commands that target the dev-tools binary and a process is being prepared for nested execution, the internal flag is automatically appended.
  4. Keep getHelp() behavior intact for help rendering.
  5. Add focused tests that assert:
    • top-level execution prints exactly one logo;
    • nested orchestrated dev-tools execution does not print the logo;
    • existing outputs/exit codes remain stable in JSON and non-JSON modes.

Non-goals

  • No orchestrator business logic refactor.
  • No broad command signature redesign.
  • No changes to non-CLI output surfaces.

Benefits

  • Provides consistent branding on all direct command invocations.
  • Prevents duplicated headers in orchestration workflows.
  • Centralizes orchestration-safe behavior, reducing future maintenance.

Requirements

  • Header output must remain deterministic and not depend on specific command names.
  • The suppression mechanism must be internal-only and not user-facing in docs.
  • list/help command output should remain available and readable.

Acceptance Criteria

Functional Criteria

  • Running a top-level dev-tools command renders the ASCII logo before normal command output.
  • Running help/list still behaves as expected.
  • Orchestrated nested dev-tools subprocesses do not emit the logo.
  • No duplicated logo output appears during dev-tools:standards or other queue-based orchestrations.

Regression Criteria

  • Existing dev-tools behavior remains unchanged for non-orchestrated commands.
  • Exit codes and logging remain unchanged outside logo output.

Architectural / Isolation Criteria

  • MUST: The core logic MUST be isolated into dedicated classes or services instead of living inside command or controller entrypoints.
  • MUST: Responsibilities MUST be separated across input resolution, domain logic, processing or transformation, and output rendering when the change is non-trivial.
  • MUST: The command or controller layer MUST act only as an orchestrator.
  • MUST: The implementation MUST avoid tight coupling between core behavior and CLI or framework-specific I/O.
  • MUST: The design MUST allow future extraction or reuse with minimal changes.
  • MUST: The solution MUST remain extensible without requiring major refactoring for adjacent use cases.
  • MUST: Argument and option resolution MUST be validated separately from command execution logic.
  • MUST: Console formatting and rendering MUST stay separate from domain processing.
  • MUST: Exit behavior, error messaging, and generated output MUST remain deterministic and testable.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    Status

    In progress

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions