Skip to content

Bootstrap CLI and structured logging #3

Description

@RaioViajante

Objective

Add the minimal command-line and structured-diagnostics bootstrap needed by the
native executable, without introducing product commands or TUI behavior.

Relevant specification

Dependencies

In scope

  • Introduce clap at the executable / composition boundary; provide a minimal
    root CLI with functional --help and --version behavior.
  • Introduce tracing and tracing-subscriber. Add another logging helper crate
    only if concrete implementation evidence requires it, and explain that
    dependency in the issue result.
  • Initialize normal application logging at the composition boundary.
  • Route ordinary interactive/application diagnostics to the documented
    application state/log location (obtained from the hum-platform resolver from
    Add platform application path resolution #2), not to a future full-screen TUI surface.
  • Preserve stdout/stderr for appropriate CLI / pre-TUI behavior.
  • Make initialization return meaningful errors rather than panic.
  • Ensure informational CLI operations (--help, --version) do not create
    persistent hum directories merely to print output.
  • Use application paths supplied by the platform resolver rather than
    recomputing them.

Do not create user-facing subcommands for future functionality.

Out of scope

  • TUI, terminal raw mode
  • media playback
  • library commands, config subcommands, config parser
  • self-update, release commands
  • remote/network behavior, telemetry
  • finalized log rotation/retention policy
  • platform support claims

Implementation constraints

  • Logging uses tracing; there is no ordinary println!-based application
    logging architecture.
  • CLI/user-facing output and logs are different concepts.
  • Logging must not require network access; no telemetry.
  • Errors at the composition root may use anyhow where appropriate; library
    crates are not converted wholesale to anyhow.
  • Do not initialize persistent state for --help/--version.
  • Do not introduce speculative CLI commands.
  • Do not introduce Tokio.

Acceptance criteria

  • hum --help works.
  • hum --version works.
  • Both informational paths are side-effect-free with respect to persistent
    hum-owned directories.
  • Normal executable initialization can configure structured logging.
  • Logging uses the platform-resolved state/log path.
  • Initialization errors are contextual and do not panic.
  • No product commands/features are falsely exposed.
  • No network or telemetry behavior exists.
  • Workspace validation (fmt, Clippy, tests) passes.

The exact visible help text beyond normal clap-generated behavior is not
frozen unless tests require stable product semantics.

Testing and validation

  • CLI parsing / --help / --version tests where meaningful.
  • Explicit regression test or evidence that informational invocations do not
    create persistent application directories.
  • Logging/bootstrap tests at the smallest practical boundary.
  • Workspace cargo fmt --all -- --check, Clippy, cargo test --workspace.

Do not assert full log message text when only initialization behavior matters.

Expected commit

chore: bootstrap cli and logging

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    priority: highImportant work that should be addressed before normal-priority items in the same milestone.type: maintenanceRepository, dependency, tooling, build, CI, or other maintenance work.

    Projects

    No projects

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions