feat: hivectl matrix invite — add a user to the hive Space or a room (closes #1402)

hive-c0re/src/bin/hivectl.rs

@@ -195,6 +195,19 @@ enum MatrixCmd {
         /// Matrix localpart of the account to reset (e.g. `argus`).
         name: String,
     },
+    /// Invite a matrix user to the hive Space (default) or a specific
+    /// room. Uses the hive admin token; the admin account must be a
+    /// member of the target room with invite power (it owns the hive
+    /// Space). Idempotent — already-member / already-invited is a no-op.
+    Invite {
+        /// User to invite: a full id (`@mara:server`) or a bare
+        /// localpart (qualified with the homeserver's `server_name`).
+        user: String,
+        /// Target room id (`!abc:server`) or alias (`#name:server`).
+        /// Omit to invite to the hive Space.
+        #[arg(long)]
+        room: Option<String>,
+    },
 }
 
 /// Default htpasswd file path — the host-side location of the gateway's
@@ -300,6 +313,7 @@ async fn main() -> Result<()> {
             MatrixCmd::SyncAdmin => matrix_sync_admin().await,
             MatrixCmd::PromoteUser { name } => matrix_promote_user(&name).await,
             MatrixCmd::ResetPassword { name } => matrix_reset_password(&name).await,
+            MatrixCmd::Invite { user, room } => matrix_invite(&user, room.as_deref()).await,
         },
         Cmd::Gateway { cmd } => match cmd {
             GatewayCmd::CreateUser {
@@ -522,6 +536,32 @@ async fn matrix_promote_user(name: &str) -> Result<()> {
     Ok(())
 }
 
+async fn matrix_invite(user: &str, room: Option<&str>) -> Result<()> {
+    if !hive_c0re::matrix::is_present().await {
+        bail!(
+            "hive-matrix container not running — start it (services.hyperhive.matrix.enable = true) first"
+        );
+    }
+    let admin_token = hive_c0re::matrix::read_admin_token()?;
+    let client = reqwest::Client::builder()
+        .timeout(std::time::Duration::from_secs(30))
+        .build()
+        .context("build reqwest client")?;
+    let server_name = hive_c0re::matrix::discover_server_name(&client)
+        .await
+        .context("discover matrix server_name")?;
+    let room_id = hive_c0re::matrix::invite_user(&client, &admin_token, user, room, &server_name)
+        .await
+        .with_context(|| format!("matrix invite {user}"))?;
+    let target = if user.starts_with('@') {
+        user.to_owned()
+    } else {
+        format!("@{user}:{server_name}")
+    };
+    println!("matrix: invited {target} to {room_id}");
+    Ok(())
+}
+
 async fn matrix_reset_password(name: &str) -> Result<()> {
     if !hive_c0re::matrix::is_present().await {
         bail!(