Skip to content

Initialize the Rust workspace and toolchain #1

Description

@RaioViajante

Objective

Establish the smallest valid Rust/Cargo project structure that reflects hum's
documented crate boundaries and provides the foundation for every later
implementation issue.

This issue creates project structure only. It does not implement any
music-player functionality (no decoding, playback, library, TUI, configuration
parsing, or artwork).

Relevant specification

Dependencies

None. This is the first implementation issue in the repository.

In scope

  • Initialize the root Cargo workspace.
  • Create the root hum executable / composition package.
  • Create the planned internal crates: hum-core, hum-audio, hum-library,
    hum-config, hum-ui, hum-platform.
  • Establish an acyclic workspace dependency structure consistent with
    docs/architecture.md (infrastructure crates may depend on hum-core; the
    executable may depend on all; hum-core depends on no other hum crate).
  • Ensure hum-core has no infrastructure dependencies.
  • Select the Rust edition for the new workspace based on the current stable
    toolchain.
  • Establish the repository's stable Rust toolchain policy; create
    rust-toolchain.toml if that is the clean implementation of the policy, and
    include the rustfmt and clippy components if such a file is used.
  • Generate and commit the root Cargo.lock.
  • Provide only the minimal source modules required for all workspace members to
    compile.
  • Establish only the workspace/package metadata that is genuinely required.
  • Ensure the workspace has a usable baseline for cargo check, cargo test,
    cargo fmt, and Clippy.

Do not add dependencies (CPAL, Ratatui, Symphonia, rusqlite, Lofty, etc.) to
crates that do not use them yet. Dependencies are added by the issue that needs
them.

Out of scope

  • Symphonia decoding, CPAL, audio playback
  • SQLite, library scanning
  • TUI, Ratatui, terminal raw mode
  • configuration parser/language, config filename
  • terminal artwork
  • application path resolution
  • logging initialization
  • finished CLI behavior
  • CI workflow
  • plugin/network architecture
  • any user-facing music-player behavior

Implementation constraints

  • Rust is the application language; stable Rust is the default. Do not introduce
    nightly without an explicit documented requirement.
  • The workspace is a modular monolith.
  • hum-core remains infrastructure-independent.
  • Do not introduce Tokio.
  • Do not add speculative abstractions or fake implementations of future
    subsystems.
  • Keep all crate dependencies acyclic; use the narrowest practical crate APIs.
  • Cargo.lock must be tracked (not .gitignored).
  • Do not choose or modify the software license.
  • Do not change the roadmap merely because implementation has started.
  • Preserve any unrelated working-tree changes.

The exact Rust version and edition were intentionally deferred until this issue;
this issue is authorized to resolve them using current stable Rust evidence. If
the chosen version/edition becomes a durable project rule, keep the repository
configuration and docs/development.md consistent as required by that document.

Acceptance criteria

  • Root Cargo workspace exists.
  • Root hum executable package exists.
  • All six planned internal crates exist (hum-core, hum-audio,
    hum-library, hum-config, hum-ui, hum-platform).
  • The workspace dependency graph is acyclic and matches
    docs/architecture.md direction.
  • hum-core imports no infrastructure crate.
  • The stable Rust toolchain policy is explicit.
  • The Rust edition is explicit.
  • Cargo.lock exists and is tracked.
  • The workspace compiles.
  • The workspace test baseline succeeds.
  • rustfmt check succeeds.
  • Clippy baseline succeeds.
  • Building/running the workspace does not claim player functionality.
  • No later-milestone dependencies or features were added.
  • LICENSE remains untouched.

Testing and validation

Run, using the final valid command forms selected during implementation:

  • cargo check --workspace
  • cargo fmt --all -- --check
  • cargo clippy --workspace --all-targets -- -D warnings
  • cargo test --workspace

If workspace configuration makes a slightly different Clippy invocation
necessary, follow docs/development.md and report the actual command used.

Also inspect cargo metadata (or an equivalent) as evidence that the internal
dependency graph is acyclic and correctly directed.

Expected commit

chore: initialize cargo workspace

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

    area: coreCore domain, application state, commands, events, and shared abstractions.priority: criticalRelease-blocking, data-loss, security-critical, or otherwise immediately blocking work.type: maintenanceRepository, dependency, tooling, build, CI, or other maintenance work.

    Projects

    No projects

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions