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
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
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
direction, modular monolith,
hum-coreinfrastructure independenceCargo.lockpolicy, formatting/lint/test baseline, dependency discipline
Cargo.lockis committed forthe application
Dependencies
None. This is the first implementation issue in the repository.
In scope
humexecutable / composition package.hum-core,hum-audio,hum-library,hum-config,hum-ui,hum-platform.docs/architecture.md(infrastructure crates may depend onhum-core; theexecutable may depend on all;
hum-coredepends on no otherhumcrate).hum-corehas no infrastructure dependencies.toolchain.
rust-toolchain.tomlif that is the clean implementation of the policy, andinclude the
rustfmtandclippycomponents if such a file is used.Cargo.lock.compile.
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
Implementation constraints
nightly without an explicit documented requirement.
hum-coreremains infrastructure-independent.subsystems.
Cargo.lockmust be tracked (not.gitignored).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.mdconsistent as required by that document.Acceptance criteria
humexecutable package exists.hum-core,hum-audio,hum-library,hum-config,hum-ui,hum-platform).docs/architecture.mddirection.hum-coreimports no infrastructure crate.Cargo.lockexists and is tracked.rustfmtcheck succeeds.LICENSEremains untouched.Testing and validation
Run, using the final valid command forms selected during implementation:
cargo check --workspacecargo fmt --all -- --checkcargo clippy --workspace --all-targets -- -D warningscargo test --workspaceIf workspace configuration makes a slightly different Clippy invocation
necessary, follow
docs/development.mdand report the actual command used.Also inspect
cargo metadata(or an equivalent) as evidence that the internaldependency graph is acyclic and correctly directed.
Expected commit
chore: initialize cargo workspace