feat(crates): add soar-events for frontend-agnostic event reporting

[QaidVoid]

Introduces the soar-events crate with a typed event system that decouples operation progress reporting from any specific frontend, enabling both CLI and GUI consumers.

Summary by CodeRabbit

• New Features

  • Introduced a structured event model for operation lifecycles and logging.
  • Added flexible event sinks for emitting, collecting, and no-op handling.

• Chores

  • Added a new workspace crate to host the event infrastructure and made it available to the workspace.
  • Exposed event types and handles for consumption by other components.

[coderabbitai]

📝 Walkthrough

Walkthrough

Adds a new workspace crate soar-events that defines a comprehensive set of structured event types for Soar and provides multiple event sink implementations and tests for emitting/collecting those events. (46 words)

Changes

Cohort / File(s)	Summary
Workspace manifest Cargo.toml, crates/soar-events/Cargo.toml	Added crates/soar-events to workspace members and declared workspace dependency soar-events = { version = "0.0.0", path = "crates/soar-events" }. New crate manifest with package metadata and workspace-inherited fields.
Event type definitions crates/soar-events/src/event.rs	Added pub enum SoarEvent plus numerous supporting enums (VerifyStage, InstallStage, RemoveStage, SyncStage, UpdateCheckStatus, UpdateCleanupStage, HookStage, RunStage, BuildStage, LogLevel) and associated payload fields for detailed lifecycle events.
Event sink implementations crates/soar-events/src/sink.rs	Introduced pub trait EventSink: Send + Sync and three implementations: ChannelSink (mpsc sender/receiver), NullSink (no-op), and CollectorSink (in-memory Mutex<Vec>) with query helpers.
Library root & tests crates/soar-events/src/lib.rs	Re-exported modules, added type aliases OperationId = u64 and EventSinkHandle = Arc<dyn EventSink>, and included an extensive test suite covering sink behaviors, event variants, and concurrency/trait bounds.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~22 minutes

Poem

🐰 I hop with events both big and small,
I catch their signals, one and all,
Channels hum and collectors keep,
Null sinks nap while others leap,
A tiny crate where messages call.

🚥 Pre-merge checks | ✅ 3 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 46.67% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately describes the main change: introducing a new soar-events crate for frontend-agnostic event reporting, which aligns with the changeset's core objective.
Merge Conflict Detection	✅ Passed	✅ No merge conflicts detected when merging into main

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch crates/events

---

No actionable comments were generated in the recent review. 🎉

🧹 Recent nitpick comments

crates/soar-events/src/event.rs (2)

4-5: Consider deriving PartialEq and Eq on SoarEvent.

All field types (String, u64, u32, i32, usize, Option<_>) and all nested enums already derive PartialEq + Eq. Adding it here enables direct assertion in tests (e.g., assert_eq!(event, expected)) and keeps the top-level enum consistent with the sub-enums.

Suggested change

-#[derive(Debug, Clone)]
+#[derive(Debug, Clone, PartialEq, Eq)]
 pub enum SoarEvent {

---

7-53: Optional: Extract repeated op_id/pkg_name/pkg_id triple into a shared struct.

At least 12 variants carry the same (op_id, pkg_name, pkg_id) triple. A shared struct would reduce duplication and simplify pattern matching with a single binding:

pub struct PackageOp {
    pub op_id: OperationId,
    pub pkg_name: String,
    pub pkg_id: String,
}

Then variants become e.g. DownloadStarting { pkg: PackageOp, total: u64 }. This is purely a maintainability suggestion — the current flat layout works fine.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[QaidVoid]

@coderabbitai full review

[coderabbitai]

✅ Actions performed

Full review triggered.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[coderabbitai]

Actionable comments posted: 2

🤖 Fix all issues with AI agents

In `@Cargo.toml`:
- Line 56: The workspace lists the dependency "soar-events" as version "0.1.0"
but the crate's own Cargo.toml has version "0.0.0", causing Cargo resolution to
fail; open the crate manifest for the soar-events crate and either change its
version field to "0.1.0" or adjust the workspace dependency to "0.0.0" so both
versions match (update the version = value in the workspace entry or the version
= value in crates/soar-events/Cargo.toml accordingly).

In `@crates/soar-events/src/lib.rs`:
- Around line 444-448: OperationFailed variant in enum SoarEvent is missing the
pkg_id field while all other per-package events include both pkg_name and
pkg_id; update the OperationFailed variant to include pkg_id (e.g., pkg_id:
<type>) in its definition, then update all creation sites (for example where
collector.emit(SoarEvent::OperationFailed { ... }) is called) to populate
pkg_id, and adjust any pattern matches/consumers that destructure
OperationFailed to handle the new pkg_id field so consumers can correlate
failures to package identifiers.

🧹 Nitpick comments (2)

crates/soar-events/src/event.rs (2)

36-53: Consider adding context fields to DownloadRetry and DownloadAborted.

DownloadRetry doesn't carry an attempt number or the error that triggered the retry, and DownloadAborted doesn't carry the final error reason. A GUI or CLI consumer would likely want to display "Retry 3/5: connection timed out" or "Aborted: max retries exceeded (last error: …)".

💡 Suggested additions

     DownloadRetry {
         op_id: OperationId,
         pkg_name: String,
         pkg_id: String,
+        attempt: u32,
+        error: String,
     },
     DownloadAborted {
         op_id: OperationId,
         pkg_name: String,
         pkg_id: String,
+        error: String,
     },

---

254-266: BuildStage variant ordering: Sandboxing listed last but logically happens first.

Sandboxing precedes Running in the build lifecycle, but it's the last variant in the enum. This doesn't affect functionality but reading order would better match chronological order.

Suggested reorder

 pub enum BuildStage {
+    /// Activating sandbox for build.
+    Sandboxing,
     /// Running build command N of M.
     Running {
         command_index: usize,
         total_commands: usize,
     },
     /// Build command completed.
     CommandComplete { command_index: usize },
-    /// Activating sandbox for build.
-    Sandboxing,
 }