huskies: merge 949

2026-05-13 07:10:00 +00:00
parent d87722f6c8
commit 4a0fbcaa95
15 changed files with 1454 additions and 231 deletions
@@ -0,0 +1,332 @@
+//! Typed contract for `/crdt-sync` WS-RPC methods.
+//!
+//! Each RPC method has a typed params struct and a typed result struct.
+//! Handlers deserialize the incoming params into the typed struct, do their
+//! work, and serialise a typed result struct back. Frontend code mirrors
+//! these definitions in `frontend/src/api/rpcContract.ts`; the
+//! `rpc_contract_snapshot` test in this module emits a canonical JSON snapshot
+//! of every method's params + result. If the Rust and TS shapes drift, the
+//! snapshot drifts too and the test fails — surfacing the mismatch in CI.
+//!
+//! When adding a method:
+//! 1. Add typed `*_params` and `*_result` structs here.
+//! 2. Add it to the [`CONTRACT_METHODS`] slice with a fixture for params + result.
+//! 3. Mirror the structs and the method name in
+//!    `frontend/src/api/rpcContract.ts`.
+
+use serde::{Deserialize, Serialize};
+
+// ── Params types ─────────────────────────────────────────────────────────────
+
+/// Params for `model.set_preference`.
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
+pub struct SetModelPreferenceParams {
+    pub model: String,
+}
+
+/// Params for `anthropic.set_api_key`.
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
+pub struct SetAnthropicApiKeyParams {
+    pub api_key: String,
+}
+
+/// Params for `settings.put_editor`.
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
+pub struct PutEditorParams {
+    pub editor_command: Option<String>,
+}
+
+/// Params for `settings.open_file`.
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
+pub struct OpenFileParams {
+    pub path: String,
+    pub line: Option<u32>,
+}
+
+/// Params for `project.open`.
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
+pub struct OpenProjectParams {
+    pub path: String,
+}
+
+/// Params for `project.forget`.
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
+pub struct ForgetProjectParams {
+    pub path: String,
+}
+
+/// Params for `bot_config.save`. Shape mirrors the response from `bot_config.get`.
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
+pub struct BotConfigPayload {
+    pub transport: Option<String>,
+    pub enabled: Option<bool>,
+    pub homeserver: Option<String>,
+    pub username: Option<String>,
+    pub password: Option<String>,
+    pub room_ids: Option<Vec<String>>,
+    pub slack_bot_token: Option<String>,
+    pub slack_signing_secret: Option<String>,
+    pub slack_channel_ids: Option<Vec<String>>,
+}
+
+/// Params (and result) for `settings.put_project`. Mirrors the
+/// `settings.get_project` shape.
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
+pub struct ProjectSettingsPayload {
+    pub default_qa: String,
+    pub default_coder_model: Option<String>,
+    pub max_coders: Option<u32>,
+    pub max_retries: u32,
+    pub base_branch: Option<String>,
+    pub rate_limit_notifications: bool,
+    pub timezone: Option<String>,
+    pub rendezvous: Option<String>,
+    pub watcher_sweep_interval_secs: u64,
+    pub watcher_done_retention_secs: u64,
+}
+
+// ── Result types ─────────────────────────────────────────────────────────────
+
+/// Result envelope for write methods that simply succeed or fail.
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
+pub struct OkResult {
+    pub ok: bool,
+}
+
+/// Result for `settings.put_editor`. Mirrors `settings.get_editor` envelope.
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
+pub struct EditorSettingsResult {
+    pub editor_command: Option<String>,
+}
+
+/// Result for `project.open` — returns the canonical path string.
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
+pub struct OpenProjectResult {
+    pub path: String,
+}
+
+// ── Contract metadata ────────────────────────────────────────────────────────
+
+/// One entry per registered RPC method, used by the drift-snapshot test.
+#[cfg(test)]
+pub struct ContractEntry {
+    pub method: &'static str,
+    pub params_example: fn() -> serde_json::Value,
+    pub result_example: fn() -> serde_json::Value,
+}
+
+/// Canonical fixtures for every typed write method. The TS-side
+/// `rpcContract.ts` file MUST expose the same shapes for every entry.
+#[cfg(test)]
+pub static CONTRACT_METHODS: &[ContractEntry] = &[
+    ContractEntry {
+        method: "model.set_preference",
+        params_example: || {
+            serde_json::to_value(SetModelPreferenceParams {
+                model: "claude-sonnet-4-6".to_string(),
+            })
+            .unwrap()
+        },
+        result_example: || serde_json::to_value(OkResult { ok: true }).unwrap(),
+    },
+    ContractEntry {
+        method: "anthropic.set_api_key",
+        params_example: || {
+            serde_json::to_value(SetAnthropicApiKeyParams {
+                api_key: "sk-ant-...".to_string(),
+            })
+            .unwrap()
+        },
+        result_example: || serde_json::to_value(OkResult { ok: true }).unwrap(),
+    },
+    ContractEntry {
+        method: "settings.put_editor",
+        params_example: || {
+            serde_json::to_value(PutEditorParams {
+                editor_command: Some("zed".to_string()),
+            })
+            .unwrap()
+        },
+        result_example: || {
+            serde_json::to_value(EditorSettingsResult {
+                editor_command: Some("zed".to_string()),
+            })
+            .unwrap()
+        },
+    },
+    ContractEntry {
+        method: "settings.open_file",
+        params_example: || {
+            serde_json::to_value(OpenFileParams {
+                path: "src/main.rs".to_string(),
+                line: Some(42),
+            })
+            .unwrap()
+        },
+        result_example: || serde_json::to_value(OkResult { ok: true }).unwrap(),
+    },
+    ContractEntry {
+        method: "settings.put_project",
+        params_example: || {
+            serde_json::to_value(ProjectSettingsPayload {
+                default_qa: "server".to_string(),
+                default_coder_model: None,
+                max_coders: None,
+                max_retries: 2,
+                base_branch: None,
+                rate_limit_notifications: true,
+                timezone: None,
+                rendezvous: None,
+                watcher_sweep_interval_secs: 60,
+                watcher_done_retention_secs: 86_400,
+            })
+            .unwrap()
+        },
+        result_example: || {
+            serde_json::to_value(ProjectSettingsPayload {
+                default_qa: "server".to_string(),
+                default_coder_model: None,
+                max_coders: None,
+                max_retries: 2,
+                base_branch: None,
+                rate_limit_notifications: true,
+                timezone: None,
+                rendezvous: None,
+                watcher_sweep_interval_secs: 60,
+                watcher_done_retention_secs: 86_400,
+            })
+            .unwrap()
+        },
+    },
+    ContractEntry {
+        method: "project.open",
+        params_example: || {
+            serde_json::to_value(OpenProjectParams {
+                path: "/path/to/project".to_string(),
+            })
+            .unwrap()
+        },
+        result_example: || {
+            serde_json::to_value(OpenProjectResult {
+                path: "/path/to/project".to_string(),
+            })
+            .unwrap()
+        },
+    },
+    ContractEntry {
+        method: "project.close",
+        params_example: || serde_json::json!({}),
+        result_example: || serde_json::to_value(OkResult { ok: true }).unwrap(),
+    },
+    ContractEntry {
+        method: "project.forget",
+        params_example: || {
+            serde_json::to_value(ForgetProjectParams {
+                path: "/path/to/project".to_string(),
+            })
+            .unwrap()
+        },
+        result_example: || serde_json::to_value(OkResult { ok: true }).unwrap(),
+    },
+    ContractEntry {
+        method: "bot_config.save",
+        params_example: || {
+            serde_json::to_value(BotConfigPayload {
+                transport: Some("matrix".to_string()),
+                enabled: Some(true),
+                homeserver: Some("https://matrix.example".to_string()),
+                username: Some("bot".to_string()),
+                password: Some("secret".to_string()),
+                room_ids: Some(vec!["!room:example".to_string()]),
+                slack_bot_token: None,
+                slack_signing_secret: None,
+                slack_channel_ids: None,
+            })
+            .unwrap()
+        },
+        result_example: || {
+            serde_json::to_value(BotConfigPayload {
+                transport: Some("matrix".to_string()),
+                enabled: Some(true),
+                homeserver: Some("https://matrix.example".to_string()),
+                username: Some("bot".to_string()),
+                password: Some("secret".to_string()),
+                room_ids: Some(vec!["!room:example".to_string()]),
+                slack_bot_token: None,
+                slack_signing_secret: None,
+                slack_channel_ids: None,
+            })
+            .unwrap()
+        },
+    },
+    ContractEntry {
+        method: "chat.cancel",
+        params_example: || serde_json::json!({}),
+        result_example: || serde_json::to_value(OkResult { ok: true }).unwrap(),
+    },
+];
+
+/// Build the canonical snapshot of the typed RPC contract.
+///
+/// The snapshot is a JSON object keyed by method name; each value contains
+/// `params` and `result` example payloads. The frontend imports this same
+/// snapshot via `frontend/src/api/rpcContract.snapshot.json`. When the
+/// frontend types drift from the Rust types, the snapshots disagree and
+/// `rpc_contract_snapshot_matches_committed_file` fails.
+#[cfg(test)]
+pub fn build_contract_snapshot() -> serde_json::Value {
+    let mut obj = serde_json::Map::new();
+    for entry in CONTRACT_METHODS {
+        let mut method_obj = serde_json::Map::new();
+        method_obj.insert("params".to_string(), (entry.params_example)());
+        method_obj.insert("result".to_string(), (entry.result_example)());
+        obj.insert(
+            entry.method.to_string(),
+            serde_json::Value::Object(method_obj),
+        );
+    }
+    serde_json::Value::Object(obj)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use std::path::PathBuf;
+
+    fn snapshot_path() -> PathBuf {
+        let manifest = PathBuf::from(env!("CARGO_MANIFEST_DIR"));
+        manifest
+            .parent()
+            .expect("workspace root")
+            .join("frontend")
+            .join("src")
+            .join("api")
+            .join("rpcContract.snapshot.json")
+    }
+
+    /// Guards that the Rust-side typed contract matches the committed
+    /// frontend snapshot. The snapshot file is consumed by the TS contract,
+    /// so any drift between Rust types and TS types fails this test.
+    ///
+    /// To update: run with `UPDATE_RPC_CONTRACT_SNAPSHOT=1` set.
+    #[test]
+    fn rpc_contract_snapshot_matches_committed_file() {
+        let current = build_contract_snapshot();
+        let rendered =
+            serde_json::to_string_pretty(&current).expect("snapshot must serialise") + "\n";
+
+        let path = snapshot_path();
+        if std::env::var("UPDATE_RPC_CONTRACT_SNAPSHOT").is_ok() {
+            std::fs::write(&path, &rendered).expect("write snapshot");
+            return;
+        }
+
+        let on_disk = std::fs::read_to_string(&path).unwrap_or_default();
+        assert_eq!(
+            on_disk.trim(),
+            rendered.trim(),
+            "RPC contract snapshot drift at {} — run UPDATE_RPC_CONTRACT_SNAPSHOT=1 cargo test to regenerate, then update frontend/src/api/rpcContract.ts to match",
+            path.display(),
+        );
+    }
+}