From 09b48c6a51325d258693ffce4505f08d7ab82173 Mon Sep 17 00:00:00 2001 From: Gabriel Fonseca Date: Mon, 16 Nov 2026 02:32:02 +0000 Subject: [PATCH] feat(integrations): add typed manifest-driven integrations system - Add IntegrationManifest types + validation in crates/code-integrations (manifest.rs): id/version/display_name/transport/capabilities with JSON Schema input/output validation, events, context_fields, AuthSpec - Add 4 built-in provider manifests (github, linear, posthog, sentry) in providers.rs with BUILTIN_PROVIDER_IDS - Add /v1/integrations routes in code-server (list/get/capabilities/events + 501 invoke stub); built-ins seeded on startup, config manifest with same id overrides a built-in (FRONTAL_CODE_INTEGRATIONS_CONFIG) - Add CLI 'integrations list|show|capabilities|validate' commands with --json support - Add IntegrationClient to Rust SDK and TypeScript SDK (list/get/ capabilities/events/invoke) - Keep deprecated call_* wrappers in mcp/integration.rs functional as adapter layer (tracker_reporting.rs unaffected) - Docs: new docs/INTEGRATIONS.md; updated MCP.md and API_REFERENCES.md Tested: - cargo test -p code-integrations --lib (84 passed) - cargo test -p code-server --lib (142 passed) - cargo test -p cli --bin code (203 passed) - cargo test -p frontal-code-sdk --lib (11 passed) - cargo clippy --all-targets -- -D warnings (clean) - npm run build && npm test in sdks/typescript (43 passed) --- Cargo.lock | 2 + bun.lock | 2 +- cli/src/integrations.rs | 764 +++++++++++++++++++++ cli/src/main.rs | 97 +++ crates/code-integrations/src/lib.rs | 11 + crates/code-integrations/src/manifest.rs | 542 +++++++++++++++ crates/code-integrations/src/mcp/tools.rs | 3 +- crates/code-integrations/src/providers.rs | 412 +++++++++++ crates/code-server/src/integrations.rs | 595 ++++++++++++++++ crates/code-server/src/lib.rs | 11 + docs/API_REFERENCES.md | 53 ++ docs/INTEGRATIONS.md | 274 ++++++++ docs/MCP.md | 17 +- sdks/rust/Cargo.toml | 2 + sdks/rust/src/integrations.rs | 328 +++++++++ sdks/rust/src/lib.rs | 5 + sdks/typescript/src/index.ts | 8 + sdks/typescript/src/integrations.ts | 172 +++++ sdks/typescript/tests/integrations.test.ts | 57 ++ 19 files changed, 3347 insertions(+), 8 deletions(-) create mode 100644 cli/src/integrations.rs create mode 100644 crates/code-integrations/src/manifest.rs create mode 100644 crates/code-integrations/src/providers.rs create mode 100644 crates/code-server/src/integrations.rs create mode 100644 docs/INTEGRATIONS.md create mode 100644 sdks/rust/src/integrations.rs create mode 100644 sdks/typescript/src/integrations.ts create mode 100644 sdks/typescript/tests/integrations.test.ts diff --git a/Cargo.lock b/Cargo.lock index e47d037c..ee7187cd 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -1235,6 +1235,8 @@ name = "frontal-code-sdk" version = "0.3.0" dependencies = [ "futures-util", + "reqwest", + "serde", "serde_json", "tempfile", "thiserror 1.0.69", diff --git a/bun.lock b/bun.lock index 73bd784a..d9594ee0 100644 --- a/bun.lock +++ b/bun.lock @@ -18,7 +18,7 @@ }, "sdks/typescript": { "name": "@frontal-labs/code-sdk", - "version": "0.1.0", + "version": "0.2.0", "devDependencies": { "@frontal-labs/code-zod-schemas": "file:../../extensions/zod", "@types/node": "^20.12.0", diff --git a/cli/src/integrations.rs b/cli/src/integrations.rs new file mode 100644 index 00000000..6d44274b --- /dev/null +++ b/cli/src/integrations.rs @@ -0,0 +1,764 @@ +//! `frontal-code integrations` subcommand handlers. +//! +//! Loads typed [`IntegrationManifest`]s from the project settings +//! (`.frontal-code/settings.json` → `mcp.integrations`) and the +//! `FRONTAL_CODE_INTEGRATIONS_CONFIG` environment variable, then renders +//! them for the CLI. + +use std::path::Path; + +use code_integrations::mcp::config::McpTransport; +use code_integrations::mcp::tools::PermissionMode; +use code_integrations::{ + AuthSpec, CapabilitySpec, EventSpec, IntegrationManifest, ManifestRegistry, SignatureSpec, + TransportConfig, ValidationIssue, +}; +use serde_json::{json, Value}; + +/// Environment variable holding a JSON array of integration manifests. +pub const ENV_INTEGRATIONS_CONFIG: &str = "FRONTAL_CODE_INTEGRATIONS_CONFIG"; + +/// Subcommand help text shown with no arguments or an unknown subcommand. +#[must_use] +pub fn help_text() -> &'static str { + "Usage: frontal-code integrations [options] + +Subcommands: + list List all configured integrations + show Show full details for an integration + capabilities List the capabilities of an integration + validate Validate a manifest file + +Options: + --json Emit JSON instead of a table" +} + +/// Load the manifest registry: the built-in providers (GitHub, Linear, +/// `PostHog`, and Sentry) as defaults, layered with settings discovered by +/// walking up from `cwd` and the `FRONTAL_CODE_INTEGRATIONS_CONFIG` env var. +/// +/// Configuration entries with the same id as a built-in override it; entries +/// that fail to parse are skipped (invalid entries cannot be registered +/// anyway). +pub fn load_registry(cwd: &Path) -> ManifestRegistry { + let mut registry = code_integrations::builtin_providers() + .expect("built-in provider manifests are valid"); + + if let Some(settings) = find_settings_file(cwd) { + if let Ok(contents) = std::fs::read_to_string(&settings) { + let Ok(parsed) = serde_json::from_str::(&contents) else { + return registry; + }; + if let Some(integrations) = parsed + .get("mcp") + .and_then(|mcp| mcp.get("integrations")) + .and_then(|value| value.as_object()) + { + for (_, manifest_json) in integrations { + let Ok(manifest) = + serde_json::from_value::(manifest_json.clone()) + else { + continue; + }; + register_or_override(&mut registry, manifest); + } + } + } + } + + if let Ok(raw) = std::env::var(ENV_INTEGRATIONS_CONFIG) { + let Ok(entries) = serde_json::from_str::>(&raw) else { + return registry; + }; + for manifest in entries { + register_or_override(&mut registry, manifest); + } + } + + registry +} + +/// Register a manifest, replacing any existing manifest with the same id so +/// that project configuration can override a built-in provider. +fn register_or_override(registry: &mut ManifestRegistry, manifest: IntegrationManifest) { + let id = manifest.id.clone(); + if registry.get(&id).is_some() { + registry.remove(&id); + } + let _ = registry.register(manifest); +} + +/// Walk up from `cwd` (inclusive) looking for `.frontal-code/settings.json`. +fn find_settings_file(cwd: &Path) -> Option { + let mut current: Option<&Path> = Some(cwd); + while let Some(dir) = current { + let candidate = dir.join(".frontal-code").join("settings.json"); + if candidate.is_file() { + return Some(candidate); + } + current = dir.parent(); + } + None +} + +/// Summary of one integration for table/JSON rendering. +#[derive(serde::Serialize)] +struct IntegrationSummary { + id: String, + version: String, + display_name: String, + capability_count: usize, + auth: String, +} + +fn summarize(manifest: &IntegrationManifest) -> IntegrationSummary { + IntegrationSummary { + id: manifest.id.clone(), + version: manifest.version.clone(), + display_name: manifest.display_name.clone(), + capability_count: manifest.capabilities.len(), + auth: auth_label(manifest.auth.as_ref()), + } +} + +fn auth_label(auth: Option<&AuthSpec>) -> String { + match auth { + Some(AuthSpec::OAuth { .. }) => "oauth".to_string(), + Some(AuthSpec::ApiKey { .. }) => "api_key".to_string(), + Some(AuthSpec::None) | None => "none".to_string(), + } +} + +fn transport_label(transport: &McpTransport) -> String { + match transport { + McpTransport::Stdio => "stdio", + McpTransport::Sse => "sse", + McpTransport::Http => "http", + McpTransport::WebSocket => "websocket", + McpTransport::Sdk => "sdk", + McpTransport::ManagedProxy => "managed_proxy", + } + .to_string() +} + +fn permission_label(mode: PermissionMode) -> String { + match mode { + PermissionMode::ReadOnly => "read-only", + PermissionMode::WorkspaceWrite => "workspace-write", + PermissionMode::DangerFullAccess => "danger-full-access", + } + .to_string() +} + +fn transport_detail(config: &TransportConfig) -> String { + match config { + TransportConfig::Stdio { command, args, .. } => { + let args = args + .iter() + .map(ToString::to_string) + .collect::>() + .join(" "); + if args.is_empty() { + command.clone() + } else { + format!("{command} {args}") + } + } + TransportConfig::Http { url, .. } + | TransportConfig::Sse { url, .. } + | TransportConfig::WebSocket { url } => url.clone(), + TransportConfig::Sdk { module } => module.clone(), + TransportConfig::ManagedProxy { target, .. } => target.clone(), + } +} + +/// Render the integration list as a human-readable table. +pub fn list_integrations(registry: &ManifestRegistry) -> String { + let manifests = registry.list(); + let mut lines = vec![format!("INTEGRATIONS ({})", manifests.len())]; + if manifests.is_empty() { + lines.push(String::new()); + lines.push(" No integrations configured.".to_string()); + return lines.join("\n"); + } + lines.push(String::new()); + + let id_width = manifests + .iter() + .map(|manifest| manifest.id.len()) + .max() + .unwrap_or(0) + .max("ID".len()); + let name_width = manifests + .iter() + .map(|manifest| manifest.display_name.len()) + .max() + .unwrap_or(0) + .max("NAME".len()); + lines.push(format!( + " {id: String { + let summaries: Vec = registry + .list() + .iter() + .map(|manifest| json!(summarize(manifest))) + .collect(); + serde_json::to_string_pretty(&Value::Array(summaries)).unwrap_or_else(|_| "[]".to_string()) +} + +/// Render full detail for one integration. +pub fn show_integration(registry: &ManifestRegistry, id: &str) -> Result { + let manifest = registry.get(id).ok_or_else(|| { + format!("integration `{id}` not found (see `frontal-code integrations list`)") + })?; + + let transport = format!( + "{} ({})", + transport_label(&manifest.transport), + transport_detail(&manifest.transport_config) + ); + let auth = auth_detail(manifest.auth.as_ref()).unwrap_or_else(|| "none".to_string()); + let mut lines = vec![ + format!("INTEGRATION: {}", manifest.id), + String::new(), + format!(" {id:<16}", id = manifest.id), + format!(" version: {version}", version = manifest.version), + format!( + " name: {display_name}", + display_name = manifest.display_name + ), + format!( + " description: {description}", + description = manifest.description + ), + format!(" transport: {transport}"), + format!(" auth: {auth}"), + ]; + + lines.push(String::new()); + lines.push(format!(" CAPABILITIES ({}):", manifest.capabilities.len())); + for capability in &manifest.capabilities { + let idempotent = if capability.idempotent { + " idempotent" + } else { + "" + }; + lines.push(format!( + " {name:<20} [{permission}{idempotent}", + name = capability.name, + permission = permission_label(capability.permission_mode), + idempotent = idempotent, + )); + lines.push(format!(" {}", capability.description)); + } + + if !manifest.events.is_empty() { + lines.push(String::new()); + lines.push(format!(" EVENTS ({}):", manifest.events.len())); + for event in &manifest.events { + let signature = event + .signature + .as_ref() + .map_or_else(|| "none".to_string(), signature_label); + lines.push(format!( + " {name:<20} {description}", + name = event.name, + description = event.description + )); + lines.push(format!(" signature: {signature}")); + } + } + + if !manifest.context_fields.is_empty() { + lines.push(String::new()); + lines.push(format!( + " CONTEXT FIELDS ({}):", + manifest.context_fields.len() + )); + for field in &manifest.context_fields { + lines.push(format!( + " {name:<20} {description}", + name = field.name, + description = field.description + )); + } + } + + Ok(lines.join("\n")) +} + +fn signature_label(signature: &SignatureSpec) -> String { + match signature { + SignatureSpec::HmacSha256 { secret_env } => format!("hmac_sha256 ({secret_env})"), + SignatureSpec::None => "none".to_string(), + } +} + +fn auth_detail(auth: Option<&AuthSpec>) -> Option { + match auth { + Some(AuthSpec::OAuth { + client_id_env, + client_secret_env, + auth_url, + scopes, + .. + }) => Some(format!( + "oauth (client_id_env={client_id_env}, client_secret_env={}, scopes=[{}]) auth_url={auth_url}", + client_secret_env + .as_deref() + .map(str::trim) + .filter(|value| !value.is_empty()) + .unwrap_or("unset"), + scopes.join(", "), + )), + Some(AuthSpec::ApiKey { env_var, header }) => Some(format!( + "api_key (env_var={env_var}, header={})", + header.as_deref().unwrap_or("default") + )), + Some(AuthSpec::None) => Some("none".to_string()), + None => None, + } +} + +/// Render full detail for one integration as a JSON object. +pub fn show_integration_json(registry: &ManifestRegistry, id: &str) -> Result { + let manifest = registry.get(id).ok_or_else(|| { + format!("integration `{id}` not found (see `frontal-code integrations list`)") + })?; + serde_json::to_string_pretty(&manifest) + .map_err(|error| format!("failed to serialize integration `{id}`: {error}")) +} + +/// Render the capability table for one integration. +pub fn list_capabilities(registry: &ManifestRegistry, id: &str) -> Result { + let manifest = registry.get(id).ok_or_else(|| { + format!("integration `{id}` not found (see `frontal-code integrations list`)") + })?; + + let mut lines = vec![format!( + "CAPABILITIES: {id} ({})", + manifest.capabilities.len() + )]; + if manifest.capabilities.is_empty() { + lines.push(String::new()); + lines.push(" No capabilities declared.".to_string()); + return Ok(lines.join("\n")); + } + lines.push(String::new()); + + let name_width = manifest + .capabilities + .iter() + .map(|capability| capability.name.len()) + .max() + .unwrap_or(0) + .max("NAME".len()); + lines.push(format!( + " {name: Result { + let manifest = registry.get(id).ok_or_else(|| { + format!("integration `{id}` not found (see `frontal-code integrations list`)") + })?; + let capabilities: Vec = manifest + .capabilities + .iter() + .map(|capability| { + let summary = json!(capability); + json!({ + "name": summary.get("name"), + "description": summary.get("description"), + "permission_mode": summary.get("permission_mode"), + "idempotent": summary.get("idempotent"), + }) + }) + .collect(); + serde_json::to_string_pretty(&Value::Array(capabilities)) + .map_err(|error| format!("failed to serialize capabilities for `{id}`: {error}")) +} + +/// Parse a file as an [`IntegrationManifest`] and run its validation. +/// +/// Returns a human-readable report: `valid` when the manifest passes, or a +/// list of issues otherwise. +pub fn validate_manifest_file(path: &Path) -> Result { + let contents = std::fs::read_to_string(path) + .map_err(|error| format!("failed to read {}: {error}", path.display()))?; + let manifest: IntegrationManifest = serde_json::from_str(&contents) + .map_err(|error| format!("failed to parse {}: {error}", path.display()))?; + match manifest.validate() { + Ok(()) => Ok(format!( + "{}: valid ({} {})", + path.display(), + manifest.id, + manifest.version + )), + Err(issues) => Ok(render_validation_report(path, &manifest, issues)), + } +} + +fn render_validation_report( + path: &Path, + manifest: &IntegrationManifest, + issues: Vec, +) -> String { + let mut lines = vec![format!( + "{}: invalid ({} {}, {} issue(s))", + path.display(), + manifest.id, + manifest.version, + issues.len() + )]; + for issue in issues { + lines.push(format!( + " {field}: {message}", + field = issue.field, + message = issue.message + )); + } + lines.join("\n") +} + +/// JSON report for `validate`. +pub fn validate_manifest_file_json(path: &Path) -> Result { + let contents = std::fs::read_to_string(path) + .map_err(|error| format!("failed to read {}: {error}", path.display()))?; + let manifest: IntegrationManifest = serde_json::from_str(&contents) + .map_err(|error| format!("failed to parse {}: {error}", path.display()))?; + let issues = match manifest.validate() { + Ok(()) => Vec::new(), + Err(issues) => issues, + }; + let report = json!({ + "path": path.display().to_string(), + "id": manifest.id, + "version": manifest.version, + "valid": issues.is_empty(), + "issues": issues.iter().map(|issue| json!({ + "field": issue.field, + "message": issue.message, + })).collect::>(), + }); + serde_json::to_string_pretty(&report) + .map_err(|error| format!("failed to serialize validation report: {error}")) +} + +#[cfg(test)] +mod tests { + use super::*; + + /// Guards tests that read `FRONTAL_CODE_INTEGRATIONS_CONFIG`; cargo runs + /// tests on multiple threads and env vars are process-global. + static ENV_LOCK: std::sync::Mutex<()> = std::sync::Mutex::new(()); + + fn test_registry() -> ManifestRegistry { + let manifest = IntegrationManifest { + id: "github".to_string(), + version: "1.0.0".to_string(), + display_name: "GitHub".to_string(), + description: "GitHub integration".to_string(), + transport: McpTransport::Stdio, + transport_config: TransportConfig::Stdio { + command: "gh-mcp".to_string(), + args: vec!["serve".to_string()], + env: std::collections::BTreeMap::new(), + }, + capabilities: vec![ + CapabilitySpec { + name: "create_issue".to_string(), + description: "Create an issue".to_string(), + input_schema: json!({"type": "object"}), + output_schema: Some(json!({"type": "object"})), + permission_mode: PermissionMode::WorkspaceWrite, + idempotent: false, + }, + CapabilitySpec { + name: "list_issues".to_string(), + description: "List issues".to_string(), + input_schema: json!({"type": "object"}), + output_schema: None, + permission_mode: PermissionMode::ReadOnly, + idempotent: true, + }, + ], + auth: Some(AuthSpec::OAuth { + client_id_env: "GITHUB_OAUTH_CLIENT_ID".to_string(), + client_secret_env: Some("GITHUB_OAUTH_CLIENT_SECRET".to_string()), + auth_url: "https://github.com/login/oauth/authorize".to_string(), + token_url: "https://github.com/login/oauth/access_token".to_string(), + scopes: vec!["repo".to_string()], + redirect_path: None, + }), + events: Vec::::new(), + context_fields: Vec::new(), + }; + let mut registry = ManifestRegistry::new(); + registry.register(manifest).expect("register"); + registry + } + + fn temp_dir(name: &str) -> std::path::PathBuf { + let dir = std::env::temp_dir().join(format!( + "frontal-integrations-test-{name}-{}", + std::process::id() + )); + std::fs::create_dir_all(&dir).expect("create temp dir"); + dir + } + + #[test] + fn load_registry_reads_settings_file_and_stops_at_first_match() { + let dir = temp_dir("settings"); + let settings_dir = dir.join(".frontal-code"); + std::fs::create_dir_all(&settings_dir).expect("create settings dir"); + let manifest_json = json!({ + "id": "linear", + "version": "2.1.0", + "display_name": "Linear", + "description": "Linear integration", + "transport": "stdio", + "transport_config": { + "kind": "stdio", + "command": "linear-mcp", + "args": ["serve"], + "env": {} + }, + "capabilities": [{ + "name": "create_issue", + "description": "Create an issue", + "input_schema": {"type": "object"}, + "permission_mode": "workspace_write", + "idempotent": false + }], + "auth": { + "kind": "api_key", + "env_var": "LINEAR_API_KEY", + "header": null + }, + "events": [], + "context_fields": [] + }); + let settings = json!({ "mcp": { "integrations": { "linear": manifest_json } } }); + std::fs::write( + settings_dir.join("settings.json"), + serde_json::to_string_pretty(&settings).expect("serialize"), + ) + .expect("write settings"); + + let _guard = ENV_LOCK.lock().expect("env lock poisoned"); + std::env::remove_var(ENV_INTEGRATIONS_CONFIG); + let registry = load_registry(&dir); + // The built-in linear manifest is overridden by the settings file; + // the other built-ins remain. + assert_eq!(registry.list().len(), 4); + let linear = registry.get("linear").expect("linear registered"); + assert_eq!(linear.version, "2.1.0"); + assert!(matches!(linear.auth, Some(AuthSpec::ApiKey { .. }))); + assert!(registry.get("github").is_some()); + assert!(registry.get("sentry").is_some()); + } + + #[test] + fn load_registry_seeds_builtins_when_no_config() { + let dir = temp_dir("empty"); + std::fs::create_dir_all(&dir).expect("create temp dir"); + let _guard = ENV_LOCK.lock().expect("env lock poisoned"); + std::env::remove_var(ENV_INTEGRATIONS_CONFIG); + let registry = load_registry(&dir); + assert_eq!(registry.list().len(), 4); + for id in code_integrations::BUILTIN_PROVIDER_IDS { + assert!(registry.get(id).is_some(), "missing built-in `{id}`"); + } + } + + #[test] + fn list_integrations_renders_table() { + let registry = test_registry(); + let output = list_integrations(®istry); + assert!(output.contains("INTEGRATIONS (1)"), "got: {output}"); + assert!(output.contains(" ID VERSION"), "got: {output}"); + assert!(output.contains("github"), "got: {output}"); + assert!(output.contains("1.0.0"), "got: {output}"); + assert!(output.contains("GitHub"), "got: {output}"); + assert!(output.contains("oauth"), "got: {output}"); + } + + #[test] + fn list_integrations_json_renders_array() { + let registry = test_registry(); + let output = list_integrations_json(®istry); + let parsed: Value = serde_json::from_str(&output).expect("valid json"); + let array = parsed.as_array().expect("array"); + assert_eq!(array.len(), 1); + assert_eq!(array[0].get("id").and_then(Value::as_str), Some("github")); + assert_eq!( + array[0].get("capability_count").and_then(Value::as_u64), + Some(2) + ); + assert_eq!(array[0].get("auth").and_then(Value::as_str), Some("oauth")); + } + + #[test] + fn show_integration_known_id() { + let registry = test_registry(); + let output = show_integration(®istry, "github").expect("known id"); + assert!(output.contains("INTEGRATION: github"), "got: {output}"); + assert!(output.contains("gh-mcp serve"), "got: {output}"); + assert!(output.contains("create_issue"), "got: {output}"); + assert!(output.contains("workspace-write"), "got: {output}"); + assert!(output.contains("idempotent"), "got: {output}"); + } + + #[test] + fn show_integration_unknown_id() { + let registry = test_registry(); + let error = show_integration(®istry, "missing").expect_err("unknown id fails"); + assert!(error.contains("`missing` not found"), "got: {error}"); + } + + #[test] + fn show_integration_json_roundtrips() { + let registry = test_registry(); + let output = show_integration_json(®istry, "github").expect("known id"); + let parsed: IntegrationManifest = + serde_json::from_str(&output).expect("valid manifest json"); + assert_eq!(parsed.id, "github"); + } + + #[test] + fn list_capabilities_renders_table() { + let registry = test_registry(); + let output = list_capabilities(®istry, "github").expect("known id"); + assert!(output.contains("CAPABILITIES: github (2)"), "got: {output}"); + assert!(output.contains("create_issue"), "got: {output}"); + assert!(output.contains("list_issues"), "got: {output}"); + assert!(output.contains("read-only"), "got: {output}"); + assert!(output.contains("no"), "got: {output}"); + } + + #[test] + fn list_capabilities_unknown_id() { + let registry = test_registry(); + let error = list_capabilities(®istry, "missing").expect_err("unknown id fails"); + assert!(error.contains("`missing` not found"), "got: {error}"); + } + + fn write_manifest(dir: &Path, name: &str, contents: &str) -> std::path::PathBuf { + let path = dir.join(name); + std::fs::write(&path, contents).expect("write manifest"); + path + } + + fn valid_manifest_json() -> String { + serde_json::to_string_pretty(&json!({ + "id": "github", + "version": "1.0.0", + "display_name": "GitHub", + "description": "GitHub integration", + "transport": "stdio", + "transport_config": { + "kind": "stdio", + "command": "gh-mcp", + "args": ["serve"], + "env": {} + }, + "capabilities": [{ + "name": "create_issue", + "description": "Create an issue", + "input_schema": {"type": "object"}, + "permission_mode": "workspace_write", + "idempotent": false + }], + "auth": { + "kind": "api_key", + "env_var": "GITHUB_TOKEN", + "header": null + }, + "events": [], + "context_fields": [] + })) + .expect("serialize") + } + + #[test] + fn validate_manifest_file_valid() { + let dir = temp_dir("validate-valid"); + let path = write_manifest(&dir, "valid.json", &valid_manifest_json()); + let output = validate_manifest_file(&path).expect("valid manifest"); + assert!(output.contains("valid"), "got: {output}"); + assert!(output.contains("github"), "got: {output}"); + } + + #[test] + fn validate_manifest_file_invalid_reports_issues() { + let dir = temp_dir("validate-invalid"); + let bad = valid_manifest_json().replace("\"github\"", "\"Bad Id!\""); + let path = write_manifest(&dir, "invalid.json", &bad); + let output = validate_manifest_file(&path).expect("parses but is invalid"); + assert!(output.contains("invalid"), "got: {output}"); + assert!(output.contains("id"), "got: {output}"); + } + + #[test] + fn validate_manifest_file_unparseable() { + let dir = temp_dir("validate-unparseable"); + let path = write_manifest(&dir, "unparseable.json", "{ not json"); + let error = validate_manifest_file(&path).expect_err("unparseable fails"); + assert!(error.contains("failed to parse"), "got: {error}"); + } + + #[test] + fn validate_manifest_file_json_shape() { + let dir = temp_dir("validate-json"); + let path = write_manifest(&dir, "valid.json", &valid_manifest_json()); + let output = validate_manifest_file_json(&path).expect("valid manifest"); + let parsed: Value = serde_json::from_str(&output).expect("valid json"); + assert_eq!(parsed.get("valid").and_then(Value::as_bool), Some(true)); + assert!(parsed.get("issues").and_then(Value::as_array).is_some()); + } +} diff --git a/cli/src/main.rs b/cli/src/main.rs index 0d86bf1d..28a42e98 100644 --- a/cli/src/main.rs +++ b/cli/src/main.rs @@ -13,6 +13,7 @@ mod analytics; mod auth; mod init; mod input; +mod integrations; mod mentions; mod notify; mod render; @@ -255,6 +256,10 @@ fn dispatch(action: CliAction) -> Result<(), Box> { args, output_format, } => LiveCli::print_mcp(args.as_deref(), output_format)?, + CliAction::Integrations { + args, + output_format, + } => run_integrations_command(args.as_deref(), output_format)?, CliAction::Trust { revoke } => print_workspace_trust(revoke)?, CliAction::Skills { args, @@ -338,6 +343,90 @@ fn dispatch(action: CliAction) -> Result<(), Box> { Ok(()) } +fn run_integrations_command( + args: Option<&str>, + output_format: CliOutputFormat, +) -> Result<(), Box> { + let mut tokens = args + .map(|value| { + value + .split_whitespace() + .map(str::to_string) + .collect::>() + }) + .unwrap_or_default(); + let mut as_json = matches!(output_format, CliOutputFormat::Json); + tokens.retain(|token| { + if token == "--json" || token == "--output-format=json" { + as_json = true; + false + } else { + true + } + }); + + let Some(subcommand) = tokens.first().map(String::as_str) else { + println!("{}", integrations::help_text()); + return Ok(()); + }; + + match subcommand { + "list" => { + let registry = integrations::load_registry(&env::current_dir()?); + let output = if as_json { + integrations::list_integrations_json(®istry) + } else { + integrations::list_integrations(®istry) + }; + println!("{output}"); + } + "show" | "capabilities" => { + let id = tokens + .get(1) + .and_then(|value| value.split('=').next()) + .filter(|value| !value.starts_with("--")) + .ok_or_else(|| { + "`frontal-code integrations {subcommand}` requires an integration id. \ + Use `frontal-code integrations {subcommand} `." + .to_string() + })? + .to_string(); + let registry = integrations::load_registry(&env::current_dir()?); + let output = match (subcommand, as_json) { + ("show", true) => integrations::show_integration_json(®istry, &id), + ("show", false) => integrations::show_integration(®istry, &id), + ("capabilities", true) => integrations::list_capabilities_json(®istry, &id), + _ => integrations::list_capabilities(®istry, &id), + } + .map_err(Box::::from)?; + println!("{output}"); + } + "validate" => { + let path = tokens + .get(1) + .filter(|value| !value.starts_with("--")) + .ok_or_else(|| { + "`frontal-code integrations validate` requires a manifest file path. \ + Use `frontal-code integrations validate `." + .to_string() + })?; + let path = Path::new(path); + let output = if as_json { + integrations::validate_manifest_file_json(path) + } else { + integrations::validate_manifest_file(path) + } + .map_err(Box::::from)?; + println!("{output}"); + } + other => { + eprintln!("unknown integrations subcommand: {other}"); + eprintln!("{}", integrations::help_text()); + } + } + Ok(()) +} + #[derive(Debug, Clone, PartialEq, Eq)] struct TelemetryResolution { enabled: bool, @@ -475,6 +564,10 @@ enum CliAction { args: Option, output_format: CliOutputFormat, }, + Integrations { + args: Option, + output_format: CliOutputFormat, + }, Trust { revoke: bool, }, @@ -1101,6 +1194,10 @@ fn parse_args(args: &[String]) -> Result { args: join_optional_args(&rest[1..]), output_format, }), + "integrations" => Ok(CliAction::Integrations { + args: join_optional_args(&rest[1..]), + output_format, + }), "trust" => match rest.get(1).map(String::as_str) { None => Ok(CliAction::Trust { revoke: false }), Some("--revoke") if rest.len() == 2 => Ok(CliAction::Trust { revoke: true }), diff --git a/crates/code-integrations/src/lib.rs b/crates/code-integrations/src/lib.rs index 39fce695..bb996353 100644 --- a/crates/code-integrations/src/lib.rs +++ b/crates/code-integrations/src/lib.rs @@ -4,7 +4,9 @@ //! including Model Context Protocol (MCP) server management and tool bridging. pub mod ide; +pub mod manifest; pub mod mcp; +pub mod providers; // Re-export commonly used MCP types for convenience pub use mcp::{ @@ -17,6 +19,15 @@ pub use mcp::{ tools::{execute_mcp_tool, mcp_tool_specs, ToolSpec}, }; +// Re-export the integration manifest system (the typed plugin contract) +pub use manifest::{ + AuthSpec, CapabilitySpec, ContextFieldSpec, EventSpec, IntegrationManifest, + ManifestRegistry, SignatureSpec, TransportConfig, ValidationIssue, +}; + +// Re-export the built-in provider manifests (GitHub, Linear, PostHog, Sentry) +pub use providers::{builtin_providers, BUILTIN_PROVIDER_IDS}; + #[cfg(test)] mod tests { #[test] diff --git a/crates/code-integrations/src/manifest.rs b/crates/code-integrations/src/manifest.rs new file mode 100644 index 00000000..e4e26941 --- /dev/null +++ b/crates/code-integrations/src/manifest.rs @@ -0,0 +1,542 @@ +//! Typed, declarative integration manifests. +//! +//! An [`IntegrationManifest`] is the plugin contract for `FrontalCode` integrations: +//! the server, CLI, and SDKs all consume this shape. Manifests declare how to reach +//! an integration (transport + transport config), the capabilities (tools/endpoints) +//! it exposes, its auth requirements, the webhook events it can emit, and the fields +//! it writes into task context. + +use crate::mcp::config::McpTransport; +use crate::mcp::tools::PermissionMode; +use regex::Regex; +use serde::{Deserialize, Serialize}; +use std::collections::{BTreeMap, BTreeSet}; + +/// A fully typed, declarative definition of an integration. +/// This is the plugin contract: the server, CLI, and SDKs all consume this shape. +#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)] +pub struct IntegrationManifest { + /// Unique identifier (e.g., "github", "linear", "my-custom-api") + pub id: String, + /// Semver version of this manifest + pub version: String, + pub display_name: String, + pub description: String, + /// How to reach the integration. Reuses the existing MCP transport enum. + pub transport: McpTransport, + /// Transport-specific config (command/args/env for stdio, url for http, etc.) + pub transport_config: TransportConfig, + /// The capabilities (tools/endpoints) this integration exposes + pub capabilities: Vec, + /// Auth requirements, if any + pub auth: Option, + /// Webhook events this integration can emit (for webhook-capable integrations) + pub events: Vec, + /// Fields this integration writes into task context (prefix-based) + pub context_fields: Vec, +} + +/// Transport-specific configuration. Tagged enum. +#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)] +#[serde(tag = "kind", rename_all = "snake_case")] +pub enum TransportConfig { + Stdio { + command: String, + args: Vec, + env: BTreeMap, + }, + Http { + url: String, + headers: BTreeMap, + }, + Sse { + url: String, + headers: BTreeMap, + }, + WebSocket { + url: String, + }, + Sdk { + module: String, + }, + ManagedProxy { + proxy_url: String, + target: String, + }, +} + +/// A single capability (tool/endpoint) exposed by an integration. +#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)] +pub struct CapabilitySpec { + pub name: String, + pub description: String, + /// JSON Schema for input validation (industry standard, matches MCP) + pub input_schema: serde_json::Value, + /// JSON Schema for output validation + pub output_schema: Option, + pub permission_mode: PermissionMode, + /// If true, safe to retry on failure + pub idempotent: bool, +} + +/// Auth specification for an integration. +#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)] +#[serde(tag = "kind", rename_all = "snake_case")] +pub enum AuthSpec { + None, + OAuth { + client_id_env: String, + client_secret_env: Option, + auth_url: String, + token_url: String, + scopes: Vec, + redirect_path: Option, + }, + ApiKey { + env_var: String, + header: Option, + }, +} + +/// A webhook event this integration can emit. +#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)] +pub struct EventSpec { + pub name: String, + pub description: String, + /// JSON Schema for the event payload + pub payload_schema: serde_json::Value, + /// Signature verification method + pub signature: Option, +} + +/// Signature verification method for webhook events. +#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)] +#[serde(tag = "kind", rename_all = "snake_case")] +pub enum SignatureSpec { + HmacSha256 { secret_env: String }, + None, +} + +/// A field this integration writes into task context. +#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)] +pub struct ContextFieldSpec { + pub name: String, + pub description: String, + pub schema: serde_json::Value, +} + +/// A single validation issue found while checking a manifest. +#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)] +pub struct ValidationIssue { + /// Dot-separated path to the offending field (e.g., "capabilities[2].name"). + pub field: String, + /// Human-readable description of the problem. + pub message: String, +} + +impl IntegrationManifest { + /// Validate this manifest, returning any issues found. + /// + /// Returns `Ok(())` when the manifest is well-formed. + pub fn validate(&self) -> Result<(), Vec> { + let mut issues: Vec = Vec::new(); + self.validate_id(&mut issues); + self.validate_version(&mut issues); + self.validate_capabilities(&mut issues); + self.validate_auth(&mut issues); + self.validate_events(&mut issues); + if issues.is_empty() { + Ok(()) + } else { + Err(issues) + } + } + + fn validate_id(&self, issues: &mut Vec) { + // `id`: non-empty, lowercase alphanumeric + hyphens, max 64 chars. + if self.id.is_empty() { + issues.push(ValidationIssue { + field: "id".to_string(), + message: "id must be non-empty".to_string(), + }); + } else if self.id.len() > 64 { + issues.push(ValidationIssue { + field: "id".to_string(), + message: format!("id must be at most 64 characters, got {}", self.id.len()), + }); + } else if !id_re().is_match(&self.id) { + issues.push(ValidationIssue { + field: "id".to_string(), + message: format!( + "id `{}` must be lowercase alphanumeric with hyphens only", + self.id + ), + }); + } + + } + + fn validate_version(&self, issues: &mut Vec) { + // `version`: must parse as semver. + if !semver_re().is_match(&self.version) { + issues.push(ValidationIssue { + field: "version".to_string(), + message: format!( + "version `{}` is not valid semver (expected e.g. `1.2.3`)", + self.version + ), + }); + } + + } + + fn validate_capabilities(&self, issues: &mut Vec) { + // `capabilities`: must be non-empty, names unique, schemas valid JSON. + if self.capabilities.is_empty() { + issues.push(ValidationIssue { + field: "capabilities".to_string(), + message: "capabilities must be non-empty".to_string(), + }); + } + let mut seen: BTreeSet<&str> = BTreeSet::new(); + for (index, capability) in self.capabilities.iter().enumerate() { + let field = format!("capabilities[{index}]"); + if !seen.insert(&capability.name) { + issues.push(ValidationIssue { + field: format!("{field}.name"), + message: format!("duplicate capability name `{}`", capability.name), + }); + } + if capability.input_schema.is_null() { + issues.push(ValidationIssue { + field: format!("{field}.input_schema"), + message: "input_schema must be valid JSON".to_string(), + }); + } + if let Some(output_schema) = &capability.output_schema { + if output_schema.is_null() { + issues.push(ValidationIssue { + field: format!("{field}.output_schema"), + message: "output_schema must be valid JSON".to_string(), + }); + } + } + } + + } + + fn validate_auth(&self, issues: &mut Vec) { + // `auth`: env var names must be non-empty strings. + match &self.auth { + Some(AuthSpec::OAuth { + client_id_env, + client_secret_env, + .. + }) => { + if client_id_env.is_empty() { + issues.push(ValidationIssue { + field: "auth.client_id_env".to_string(), + message: "auth.client_id_env must be a non-empty string".to_string(), + }); + } + if let Some(secret) = client_secret_env { + if secret.is_empty() { + issues.push(ValidationIssue { + field: "auth.client_secret_env".to_string(), + message: "auth.client_secret_env must be a non-empty string" + .to_string(), + }); + } + } + } + Some(AuthSpec::ApiKey { env_var, .. }) => { + if env_var.is_empty() { + issues.push(ValidationIssue { + field: "auth.env_var".to_string(), + message: "auth.env_var must be a non-empty string".to_string(), + }); + } + } + Some(AuthSpec::None) | None => {} + } + + } + + fn validate_events(&self, issues: &mut Vec) { + // `events`: names must be unique. + let mut seen_events: BTreeSet<&str> = BTreeSet::new(); + for (index, event) in self.events.iter().enumerate() { + let field = format!("events[{index}]"); + if !seen_events.insert(&event.name) { + issues.push(ValidationIssue { + field: format!("{field}.name"), + message: format!("duplicate event name `{}`", event.name), + }); + } + } + } +} + +/// Registry of integration manifests, keyed by manifest id. +#[derive(Debug, Clone, Default)] +pub struct ManifestRegistry { + manifests: BTreeMap, +} + +impl ManifestRegistry { + /// Create an empty registry. + #[must_use] + pub fn new() -> Self { + Self::default() + } + + /// Register a manifest, rejecting it if it fails validation + /// or if a manifest with the same id is already registered. + pub fn register(&mut self, manifest: IntegrationManifest) -> Result<(), Vec> { + manifest.validate()?; + if self.manifests.contains_key(&manifest.id) { + return Err(vec![ValidationIssue { + field: "id".to_string(), + message: format!("manifest with id `{}` is already registered", manifest.id), + }]); + } + self.manifests.insert(manifest.id.clone(), manifest); + Ok(()) + } + + /// Remove a manifest by id, returning it if it was present. + pub fn remove(&mut self, id: &str) -> Option { + self.manifests.remove(id) + } + + /// Look up a manifest by id. + #[must_use] + pub fn get(&self, id: &str) -> Option<&IntegrationManifest> { + self.manifests.get(id) + } + + /// List all registered manifests in id order. + #[must_use] + pub fn list(&self) -> Vec<&IntegrationManifest> { + self.manifests.values().collect() + } + + /// Look up a single capability on a registered manifest. + #[must_use] + pub fn capability( + &self, + integration_id: &str, + capability: &str, + ) -> Option<&CapabilitySpec> { + self.manifests + .get(integration_id)? + .capabilities + .iter() + .find(|spec| spec.name == capability) + } +} + +static ID_RE: std::sync::OnceLock = std::sync::OnceLock::new(); +static SEMVER_RE: std::sync::OnceLock = std::sync::OnceLock::new(); + +fn id_re() -> &'static Regex { + ID_RE.get_or_init(|| Regex::new("^[a-z0-9]+(-[a-z0-9]+)*$").expect("static regex is valid")) +} + +fn semver_re() -> &'static Regex { + SEMVER_RE.get_or_init(|| { + Regex::new( + r"^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$", + ) + .expect("static regex is valid") + }) +} + +#[cfg(test)] +mod tests { + use super::*; + + fn valid_manifest() -> IntegrationManifest { + IntegrationManifest { + id: "github".to_string(), + version: "1.0.0".to_string(), + display_name: "GitHub".to_string(), + description: "GitHub integration".to_string(), + transport: McpTransport::Stdio, + transport_config: TransportConfig::Stdio { + command: "gh-mcp".to_string(), + args: vec!["serve".to_string()], + env: BTreeMap::new(), + }, + capabilities: vec![CapabilitySpec { + name: "create_issue".to_string(), + description: "Create an issue".to_string(), + input_schema: serde_json::json!({"type": "object"}), + output_schema: Some(serde_json::json!({"type": "object"})), + permission_mode: PermissionMode::WorkspaceWrite, + idempotent: false, + }], + auth: Some(AuthSpec::ApiKey { + env_var: "GITHUB_TOKEN".to_string(), + header: None, + }), + events: vec![EventSpec { + name: "issue.opened".to_string(), + description: "An issue was opened".to_string(), + payload_schema: serde_json::json!({"type": "object"}), + signature: None, + }], + context_fields: vec![ContextFieldSpec { + name: "github.issue".to_string(), + description: "The linked GitHub issue".to_string(), + schema: serde_json::json!({"type": "object"}), + }], + } + } + + #[test] + fn valid_manifest_roundtrips_through_serde_json() { + let manifest = valid_manifest(); + let json = serde_json::to_string(&manifest).expect("serialize"); + let parsed: IntegrationManifest = serde_json::from_str(&json).expect("deserialize"); + assert_eq!(parsed.id, manifest.id); + assert_eq!(parsed.version, manifest.version); + assert_eq!(parsed.capabilities.len(), manifest.capabilities.len()); + assert!(matches!(parsed.transport, McpTransport::Stdio)); + assert!(matches!(parsed.transport_config, TransportConfig::Stdio { .. })); + assert!(matches!(parsed.auth, Some(AuthSpec::ApiKey { .. }))); + assert_eq!(parsed.events.len(), manifest.events.len()); + assert_eq!(parsed.context_fields.len(), manifest.context_fields.len()); + assert!(parsed.validate().is_ok()); + } + + #[test] + fn validation_catches_duplicate_capability_names() { + let mut manifest = valid_manifest(); + manifest.capabilities.push(CapabilitySpec { + name: "create_issue".to_string(), + description: "Duplicate".to_string(), + input_schema: serde_json::json!({"type": "object"}), + output_schema: None, + permission_mode: PermissionMode::ReadOnly, + idempotent: true, + }); + let issues = manifest.validate().expect_err("should fail"); + assert!( + issues + .iter() + .any(|issue| issue.field == "capabilities[1].name" + && issue.message.contains("duplicate capability name")), + "expected duplicate capability issue, got {issues:?}" + ); + } + + #[test] + fn validation_catches_invalid_id_format() { + let mut manifest = valid_manifest(); + manifest.id = "GitHub_1".to_string(); + let issues = manifest.validate().expect_err("should fail"); + assert!( + issues + .iter() + .any(|issue| issue.field == "id" && issue.message.contains("lowercase")), + "expected id format issue, got {issues:?}" + ); + } + + #[test] + fn validation_catches_invalid_version() { + let mut manifest = valid_manifest(); + manifest.version = "not-a-version".to_string(); + let issues = manifest.validate().expect_err("should fail"); + assert!( + issues + .iter() + .any(|issue| issue.field == "version" && issue.message.contains("semver")), + "expected semver issue, got {issues:?}" + ); + } + + #[test] + fn validation_catches_empty_capabilities() { + let mut manifest = valid_manifest(); + manifest.capabilities.clear(); + let issues = manifest.validate().expect_err("should fail"); + assert!( + issues + .iter() + .any(|issue| issue.field == "capabilities" + && issue.message.contains("non-empty")), + "expected empty capabilities issue, got {issues:?}" + ); + } + + #[test] + fn validation_catches_duplicate_event_names() { + let mut manifest = valid_manifest(); + manifest.events.push(EventSpec { + name: "issue.opened".to_string(), + description: "Duplicate".to_string(), + payload_schema: serde_json::json!({"type": "object"}), + signature: None, + }); + let issues = manifest.validate().expect_err("should fail"); + assert!( + issues + .iter() + .any(|issue| issue.field == "events[1].name" + && issue.message.contains("duplicate event name")), + "expected duplicate event issue, got {issues:?}" + ); + } + + #[test] + fn validation_catches_empty_auth_env_vars() { + let mut manifest = valid_manifest(); + manifest.auth = Some(AuthSpec::ApiKey { + env_var: String::new(), + header: None, + }); + let issues = manifest.validate().expect_err("should fail"); + assert!( + issues + .iter() + .any(|issue| issue.field == "auth.env_var" + && issue.message.contains("non-empty")), + "expected empty env var issue, got {issues:?}" + ); + } + + #[test] + fn registry_register_get_list_capability_work() { + let mut registry = ManifestRegistry::new(); + let manifest = valid_manifest(); + registry.register(manifest.clone()).expect("register"); + + assert!(registry.get("github").is_some()); + assert!(registry.get("missing").is_none()); + assert_eq!(registry.list(), [&manifest]); + assert!(registry.capability("github", "create_issue").is_some()); + assert!(registry.capability("github", "missing").is_none()); + assert!(registry.capability("missing", "create_issue").is_none()); + + // Registering the same id again is rejected. + let err = registry + .register(manifest) + .expect_err("duplicate id must fail"); + assert_eq!(err.len(), 1); + assert_eq!(err[0].field, "id"); + } + + #[test] + fn registry_rejects_invalid_manifest() { + let mut registry = ManifestRegistry::new(); + let mut manifest = valid_manifest(); + manifest.id = "Bad Id!".to_string(); + let err = registry.register(manifest).expect_err("invalid manifest must fail"); + assert!( + err.iter().any(|issue| issue.field == "id"), + "expected id issue, got {err:?}" + ); + } +} diff --git a/crates/code-integrations/src/mcp/tools.rs b/crates/code-integrations/src/mcp/tools.rs index 910f3249..5d71105b 100644 --- a/crates/code-integrations/src/mcp/tools.rs +++ b/crates/code-integrations/src/mcp/tools.rs @@ -9,7 +9,8 @@ use serde_json::{from_value, json, Value as JsonValue}; use std::sync::OnceLock; /// Permission mode for tools -#[derive(Debug, Clone, PartialEq, Eq)] +#[derive(Debug, Clone, Copy, PartialEq, Eq, serde::Serialize, serde::Deserialize)] +#[serde(rename_all = "snake_case")] pub enum PermissionMode { ReadOnly, WorkspaceWrite, diff --git a/crates/code-integrations/src/providers.rs b/crates/code-integrations/src/providers.rs new file mode 100644 index 00000000..3fdde721 --- /dev/null +++ b/crates/code-integrations/src/providers.rs @@ -0,0 +1,412 @@ +//! Built-in provider manifests. +//! +//! These are the four first-party integrations (GitHub, Linear, `PostHog`, +//! and Sentry) expressed as config-driven [`IntegrationManifest`] values instead +//! of hardcoded provider code. They are the defaults the server and CLI load +//! when no project-level overrides are configured. +//! +//! The legacy `IntegrationRegistry::call_*` methods (see +//! [`crate::mcp::integration`]) remain as deprecated adapters over the +//! corresponding capabilities below for one release. + +use std::collections::BTreeMap; + +use serde_json::json; + +use crate::manifest::{ + AuthSpec, CapabilitySpec, IntegrationManifest, ManifestRegistry, TransportConfig, +}; +use crate::mcp::config::McpTransport; +use crate::mcp::tools::PermissionMode; + +/// The four built-in provider integration IDs, in stable (sorted) order. +pub const BUILTIN_PROVIDER_IDS: [&str; 4] = ["github", "linear", "posthog", "sentry"]; + +/// Returns the four built-in provider manifests, ready to register. +/// +/// Each manifest is validated before being returned; a built-in manifest that +/// fails validation is a bug, so this returns a `Result` that callers (and +/// tests) can assert on. +pub fn builtin_providers() -> Result> { + let mut registry = ManifestRegistry::new(); + let mut failures = Vec::new(); + for manifest in [ + github_manifest(), + linear_manifest(), + posthog_manifest(), + sentry_manifest(), + ] { + if let Err(issues) = registry.register(manifest) { + failures.extend(issues.into_iter().map(|issue| issue.message)); + } + } + if failures.is_empty() { + Ok(registry) + } else { + Err(failures) + } +} + +/// The GitHub integration: PR creation, issue comments, and check runs against +/// the GitHub REST/MCP surface. +fn github_manifest() -> IntegrationManifest { + IntegrationManifest { + id: "github".into(), + version: "1.0.0".into(), + display_name: "GitHub".into(), + description: "Create pull requests, comment on issues, and report check runs." + .into(), + transport: McpTransport::Http, + transport_config: TransportConfig::Http { + url: "https://api.github.com".into(), + headers: header_map(&[("Authorization", "${GITHUB_TOKEN}")]), + }, + capabilities: vec![ + CapabilitySpec { + name: "create_pr".into(), + description: "Open a pull request on a repository.".into(), + input_schema: json!({ + "type": "object", + "properties": { + "repo": { "type": "string" }, + "title": { "type": "string" }, + "body": { "type": "string" }, + "head": { "type": "string" }, + "base": { "type": "string" } + }, + "required": ["repo", "title", "head", "base"] + }), + output_schema: Some(json!({ + "type": "object", + "properties": { "number": { "type": "integer" }, "url": { "type": "string" } } + })), + permission_mode: PermissionMode::WorkspaceWrite, + idempotent: false, + }, + CapabilitySpec { + name: "create_issue_comment".into(), + description: "Add a comment to an issue or pull request.".into(), + input_schema: json!({ + "type": "object", + "properties": { + "repo": { "type": "string" }, + "issue_number": { "type": "integer" }, + "body": { "type": "string" } + }, + "required": ["repo", "issue_number", "body"] + }), + output_schema: Some(json!({ + "type": "object", + "properties": { "id": { "type": "integer" }, "url": { "type": "string" } } + })), + permission_mode: PermissionMode::WorkspaceWrite, + idempotent: false, + }, + CapabilitySpec { + name: "create_check_run".into(), + description: "Create a check run for a commit.".into(), + input_schema: json!({ + "type": "object", + "properties": { + "repo": { "type": "string" }, + "name": { "type": "string" }, + "head_sha": { "type": "string" }, + "status": { "type": "string" }, + "conclusion": { "type": "string" } + }, + "required": ["repo", "name", "head_sha"] + }), + output_schema: Some(json!({ + "type": "object", + "properties": { "id": { "type": "integer" }, "url": { "type": "string" } } + })), + permission_mode: PermissionMode::WorkspaceWrite, + idempotent: false, + }, + ], + auth: Some(AuthSpec::ApiKey { + env_var: "GITHUB_TOKEN".into(), + header: Some("Authorization".into()), + }), + events: Vec::new(), + context_fields: Vec::new(), + } +} + +/// The Linear integration: issue comments used by the tracker reporter. +fn linear_manifest() -> IntegrationManifest { + IntegrationManifest { + id: "linear".into(), + version: "1.0.0".into(), + display_name: "Linear".into(), + description: "Comment on Linear issues for tracker reporting.".into(), + transport: McpTransport::Http, + transport_config: TransportConfig::Http { + url: "https://api.linear.app/graphql".into(), + headers: header_map(&[("Authorization", "${LINEAR_API_KEY}")]), + }, + capabilities: vec![CapabilitySpec { + name: "create_issue_comment".into(), + description: "Add a comment to a Linear issue.".into(), + input_schema: json!({ + "type": "object", + "properties": { + "issue_id": { "type": "string" }, + "body": { "type": "string" } + }, + "required": ["issue_id", "body"] + }), + output_schema: Some(json!({ + "type": "object", + "properties": { "id": { "type": "string" }, "url": { "type": "string" } } + })), + permission_mode: PermissionMode::WorkspaceWrite, + idempotent: false, + }], + auth: Some(AuthSpec::ApiKey { + env_var: "LINEAR_API_KEY".into(), + header: Some("Authorization".into()), + }), + events: Vec::new(), + context_fields: Vec::new(), + } +} + +/// The `PostHog` integration: capture product and telemetry events. +fn posthog_manifest() -> IntegrationManifest { + IntegrationManifest { + id: "posthog".into(), + version: "1.0.0".into(), + display_name: "PostHog".into(), + description: "Capture analytics events in PostHog.".into(), + transport: McpTransport::Http, + transport_config: TransportConfig::Http { + url: "https://us.i.posthog.com/capture/".into(), + headers: BTreeMap::new(), + }, + capabilities: vec![ + CapabilitySpec { + name: "capture_event".into(), + description: "Capture a single analytics event.".into(), + input_schema: json!({ + "type": "object", + "properties": { + "event": { "type": "string" }, + "distinct_id": { "type": "string" }, + "properties": { "type": "object" } + }, + "required": ["event", "distinct_id"] + }), + output_schema: Some(json!({ + "type": "object", + "properties": { "status": { "type": "string" } } + })), + permission_mode: PermissionMode::WorkspaceWrite, + idempotent: true, + }, + CapabilitySpec { + name: "capture_events_batch".into(), + description: "Capture a batch of analytics events.".into(), + input_schema: json!({ + "type": "object", + "properties": { + "batch": { + "type": "array", + "items": { + "type": "object", + "properties": { + "event": { "type": "string" }, + "distinct_id": { "type": "string" }, + "properties": { "type": "object" } + }, + "required": ["event", "distinct_id"] + } + } + }, + "required": ["batch"] + }), + output_schema: Some(json!({ + "type": "object", + "properties": { "status": { "type": "string" } } + })), + permission_mode: PermissionMode::WorkspaceWrite, + idempotent: true, + }, + ], + auth: Some(AuthSpec::ApiKey { + env_var: "POSTHOG_API_KEY".into(), + header: Some("Authorization".into()), + }), + events: Vec::new(), + context_fields: Vec::new(), + } +} + +/// The Sentry integration: create issues and comments for error reporting. +fn sentry_manifest() -> IntegrationManifest { + IntegrationManifest { + id: "sentry".into(), + version: "1.0.0".into(), + display_name: "Sentry".into(), + description: "Create Sentry issues and comments for error reporting." + .into(), + transport: McpTransport::Http, + transport_config: TransportConfig::Http { + url: "https://sentry.io/api/0".into(), + headers: header_map(&[("Authorization", "Token ${SENTRY_AUTH_TOKEN}")]), + }, + capabilities: vec![ + CapabilitySpec { + name: "create_issue".into(), + description: "Create a new Sentry issue.".into(), + input_schema: json!({ + "type": "object", + "properties": { + "project": { "type": "string" }, + "title": { "type": "string" }, + "message": { "type": "string" } + }, + "required": ["project", "title", "message"] + }), + output_schema: Some(json!({ + "type": "object", + "properties": { "id": { "type": "string" }, "url": { "type": "string" } } + })), + permission_mode: PermissionMode::WorkspaceWrite, + idempotent: false, + }, + CapabilitySpec { + name: "create_issue_comment".into(), + description: "Add a comment to a Sentry issue.".into(), + input_schema: json!({ + "type": "object", + "properties": { + "issue_id": { "type": "string" }, + "body": { "type": "string" } + }, + "required": ["issue_id", "body"] + }), + output_schema: Some(json!({ + "type": "object", + "properties": { "id": { "type": "string" }, "url": { "type": "string" } } + })), + permission_mode: PermissionMode::WorkspaceWrite, + idempotent: false, + }, + ], + auth: Some(AuthSpec::ApiKey { + env_var: "SENTRY_AUTH_TOKEN".into(), + header: Some("Authorization".into()), + }), + events: Vec::new(), + context_fields: Vec::new(), + } +} + +fn header_map(pairs: &[(&str, &str)]) -> BTreeMap { + pairs.iter().map(|(k, v)| (k.to_string(), v.to_string())).collect() +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn builtin_providers_all_validate() { + let registry = builtin_providers().expect("all built-in manifests must validate"); + assert_eq!(registry.list().len(), 4); + for id in BUILTIN_PROVIDER_IDS { + assert!(registry.get(id).is_some(), "missing built-in `{id}`"); + } + } + + #[test] + fn builtin_provider_ids_are_sorted_and_unique() { + let ids: Vec<&str> = BUILTIN_PROVIDER_IDS.to_vec(); + let mut sorted = ids.clone(); + sorted.sort_unstable(); + assert_eq!(ids, sorted, "BUILTIN_PROVIDER_IDS must be sorted"); + assert_eq!( + ids.len(), + ids.iter().collect::>().len(), + "BUILTIN_PROVIDER_IDS must be unique" + ); + } + + #[test] + fn each_builtin_manifest_roundtrips_through_serde_json() { + for manifest in [ + github_manifest(), + linear_manifest(), + posthog_manifest(), + sentry_manifest(), + ] { + let original_id = manifest.id.clone(); + let json = serde_json::to_string(&manifest).expect("serialize"); + let parsed: IntegrationManifest = serde_json::from_str(&json).expect("deserialize"); + assert_eq!(parsed, manifest, "roundtrip mismatch for {original_id}"); + assert!(parsed.validate().is_ok(), "{original_id} must validate"); + } + } + + #[test] + fn github_manifest_exposes_expected_capabilities() { + let manifest = github_manifest(); + let names: Vec<&str> = manifest.capabilities.iter().map(|c| c.name.as_str()).collect(); + assert_eq!( + names, + vec!["create_pr", "create_issue_comment", "create_check_run"] + ); + } + + #[test] + fn linear_manifest_targets_issue_comments() { + let manifest = linear_manifest(); + let capability = manifest + .capabilities + .iter() + .find(|c| c.name == "create_issue_comment") + .expect("linear must expose create_issue_comment"); + assert_eq!(capability.permission_mode, PermissionMode::WorkspaceWrite); + assert!(!capability.idempotent); + } + + #[test] + fn posthog_capabilities_are_idempotent_writes() { + let manifest = posthog_manifest(); + assert!( + !manifest.capabilities.is_empty(), + "posthog must expose at least one capability" + ); + for capability in &manifest.capabilities { + assert!( + capability.idempotent, + "posthog capability `{}` must be idempotent", + capability.name + ); + assert_eq!(capability.permission_mode, PermissionMode::WorkspaceWrite); + } + } + + #[test] + fn all_builtins_use_http_transport_with_api_key_auth() { + for manifest in [ + github_manifest(), + linear_manifest(), + posthog_manifest(), + sentry_manifest(), + ] { + assert!( + matches!(manifest.transport, McpTransport::Http), + "{} must use http transport", + manifest.id + ); + match manifest.auth { + Some(AuthSpec::ApiKey { env_var, .. }) => { + assert!(!env_var.is_empty(), "{} env_var must be set", manifest.id); + } + other => panic!("{} must use api_key auth, got {other:?}", manifest.id), + } + } + } +} diff --git a/crates/code-server/src/integrations.rs b/crates/code-server/src/integrations.rs new file mode 100644 index 00000000..d4637d24 --- /dev/null +++ b/crates/code-server/src/integrations.rs @@ -0,0 +1,595 @@ +//! `/v1/integrations` control-plane routes. +//! +//! Serves the typed integration manifests from [`code_integrations`]: listing +//! integrations, inspecting a single manifest, its capabilities, and its +//! events. Capability invocation is a stub for now; real MCP dispatch lands +//! in Phase 3. + +use std::sync::Mutex; + +use axum::extract::Path; +use axum::extract::State; +use axum::response::Json; +use axum::routing::{get, post}; +use axum::Router; +use code_integrations::mcp::tools::PermissionMode; +use code_integrations::{AuthSpec, IntegrationManifest, ManifestRegistry}; +use serde::{Deserialize, Serialize}; +use serde_json::Value; +use std::sync::Arc; + +use crate::AppError; +use crate::ServerState; + +/// Environment variable holding a JSON array of [`IntegrationManifest`] values. +pub const INTEGRATIONS_CONFIG_ENV: &str = "FRONTAL_CODE_INTEGRATIONS_CONFIG"; + +/// Server state for the integrations routes. The registry is validated on +/// load; manifests that fail validation are skipped with a warning. +#[derive(Debug, Default)] +pub struct IntegrationsState { + pub registry: Mutex, +} + +impl IntegrationsState { + /// Create an empty state with no registered integrations. + #[cfg(test)] + #[must_use] + pub fn new() -> Self { + Self { + registry: Mutex::new(ManifestRegistry::new()), + } + } + + /// Create a state seeded with the built-in provider manifests (GitHub, + /// Linear, `PostHog`, and Sentry). These are the first-party defaults; + /// project-level configuration can still override any of them by id. + #[cfg(test)] + #[must_use] + pub fn with_builtins() -> Self { + Self { + registry: Mutex::new( + code_integrations::builtin_providers().expect("built-in provider manifests are valid"), + ), + } + } + + /// Load integrations from the `FRONTAL_CODE_INTEGRATIONS_CONFIG` + /// environment variable, a JSON array of manifests, on top of the + /// built-in providers. The env var can add new integrations or override a + /// built-in by id. Missing or invalid entries are skipped with a warning + /// so one bad manifest cannot take the whole registry down. + #[must_use] + pub fn load_from_env() -> Self { + Self::from_json( + &std::env::var(INTEGRATIONS_CONFIG_ENV).unwrap_or_default(), + code_integrations::builtin_providers().expect("built-in provider manifests are valid"), + ) + } + + /// Build a state from a raw JSON array of manifests, layered on top of a + /// base registry (typically the built-in providers). An empty, invalid, + /// or malformed string yields the base registry with a warning; + /// individual manifests that fail validation are skipped with a warning + /// so one bad manifest cannot take the whole registry down. A manifest + /// whose id collides with a base entry replaces it, letting project + /// configuration override a built-in. + #[must_use] + pub fn from_json(raw: &str, base: ManifestRegistry) -> Self { + let mut registry = base; + let trimmed = raw.trim(); + if !trimmed.is_empty() { + let Ok(manifests) = serde_json::from_str::>(trimmed) else { + eprintln!("warning: {INTEGRATIONS_CONFIG_ENV} is not a JSON array of manifests; ignoring it"); + return Self { + registry: Mutex::new(registry), + }; + }; + for manifest in manifests { + let id = manifest.id.clone(); + if registry.get(&id).is_some() { + // A same-id manifest from configuration overrides the + // built-in: drop the existing entry, then register the new one. + registry.remove(&id); + } + if let Err(issues) = registry.register(manifest) { + let reason = issues + .iter() + .map(|issue| format!("{}: {}", issue.field, issue.message)) + .collect::>() + .join("; "); + eprintln!("warning: skipping integration manifest `{id}`: {reason}"); + } + } + } + Self { + registry: Mutex::new(registry), + } + } +} + +/// One row of the integration list. +#[derive(Debug, Clone, PartialEq, Eq, Serialize)] +pub struct IntegrationSummary { + pub id: String, + pub version: String, + pub display_name: String, + pub description: String, + pub capability_count: usize, + pub auth_required: bool, + pub event_count: usize, +} + +impl From<&IntegrationManifest> for IntegrationSummary { + fn from(manifest: &IntegrationManifest) -> Self { + Self { + id: manifest.id.clone(), + version: manifest.version.clone(), + display_name: manifest.display_name.clone(), + description: manifest.description.clone(), + capability_count: manifest.capabilities.len(), + auth_required: manifest + .auth + .as_ref() + .is_some_and(|auth| !matches!(auth, AuthSpec::None)), + event_count: manifest.events.len(), + } + } +} + +/// One capability of an integration. +#[derive(Debug, Clone, PartialEq, Eq, Serialize)] +pub struct CapabilitySummary { + pub name: String, + pub description: String, + pub permission_mode: String, + pub idempotent: bool, +} + +impl From<&code_integrations::CapabilitySpec> for CapabilitySummary { + fn from(spec: &code_integrations::CapabilitySpec) -> Self { + Self { + name: spec.name.clone(), + description: spec.description.clone(), + permission_mode: permission_mode_label(spec.permission_mode), + idempotent: spec.idempotent, + } + } +} + +/// One webhook event an integration can emit. +#[derive(Debug, Clone, PartialEq, Eq, Serialize)] +pub struct EventSummary { + pub name: String, + pub description: String, + pub signature_required: bool, +} + +impl From<&code_integrations::EventSpec> for EventSummary { + fn from(event: &code_integrations::EventSpec) -> Self { + Self { + name: event.name.clone(), + description: event.description.clone(), + signature_required: event.signature.is_some(), + } + } +} + +/// Input for invoking a capability. The JSON value is the MCP tool input. +#[derive(Debug, Clone, PartialEq, Eq, Deserialize)] +pub struct InvokeRequest { + pub input: Value, +} + +fn permission_mode_label(mode: PermissionMode) -> String { + match mode { + PermissionMode::ReadOnly => "read_only", + PermissionMode::WorkspaceWrite => "workspace_write", + PermissionMode::DangerFullAccess => "danger_full_access", + } + .to_string() +} + +pub(crate) async fn list_integrations( + State(state): State>, +) -> Result>, AppError> { + let registry = state + .integrations + .registry + .lock() + .map_err(|_| AppError::internal("integrations registry lock poisoned"))?; + Ok(Json(registry.list().into_iter().map(IntegrationSummary::from).collect())) +} + +pub(crate) async fn get_integration( + Path(id): Path, + State(state): State>, +) -> Result, AppError> { + let registry = state + .integrations + .registry + .lock() + .map_err(|_| AppError::internal("integrations registry lock poisoned"))?; + let manifest = registry + .get(&id) + .ok_or_else(|| AppError::not_found(format!("integration not found: {id}")))?; + Ok(Json(manifest.clone())) +} + +pub(crate) async fn list_capabilities( + Path(id): Path, + State(state): State>, +) -> Result>, AppError> { + let registry = state + .integrations + .registry + .lock() + .map_err(|_| AppError::internal("integrations registry lock poisoned"))?; + let manifest = registry + .get(&id) + .ok_or_else(|| AppError::not_found(format!("integration not found: {id}")))?; + Ok(Json( + manifest.capabilities.iter().map(CapabilitySummary::from).collect(), + )) +} + +/// Invoke a capability. Stub: MCP dispatch is Phase 3. +pub(crate) async fn invoke_capability( + Path((id, name)): Path<(String, String)>, + State(state): State>, + Json(request): Json, +) -> Result<(), AppError> { + let registry = state + .integrations + .registry + .lock() + .map_err(|_| AppError::internal("integrations registry lock poisoned"))?; + let Some(_capability) = registry.capability(&id, &name) else { + return Err(AppError::not_found(format!( + "capability '{name}' not found on integration '{id}'" + ))); + }; + let input = request.input; + drop(registry); + Err(AppError::not_implemented(format!( + "invoking capability '{name}' on integration '{id}' is not implemented yet; \ + MCP dispatch lands in Phase 3 (input: {input})" + ))) +} + +pub(crate) async fn list_events( + Path(id): Path, + State(state): State>, +) -> Result>, AppError> { + let registry = state + .integrations + .registry + .lock() + .map_err(|_| AppError::internal("integrations registry lock poisoned"))?; + let manifest = registry + .get(&id) + .ok_or_else(|| AppError::not_found(format!("integration not found: {id}")))?; + Ok(Json(manifest.events.iter().map(EventSummary::from).collect())) +} + +/// Build a router over the integrations routes, for callers that do not want +/// the full control-plane app. +pub(crate) fn integrations_routes() -> Router> { + Router::new() + .route("/v1/integrations", get(list_integrations)) + .route("/v1/integrations/{id}", get(get_integration)) + .route( + "/v1/integrations/{id}/capabilities", + get(list_capabilities), + ) + .route( + "/v1/integrations/{id}/capabilities/{name}/invoke", + post(invoke_capability), + ) + .route("/v1/integrations/{id}/events", get(list_events)) +} + +#[cfg(test)] +mod tests { + use super::*; + use code_integrations::{ + ContextFieldSpec, EventSpec, SignatureSpec, TransportConfig, + }; + use code_integrations::mcp::config::McpTransport; + use serde_json::json; + + fn sample_manifest() -> IntegrationManifest { + IntegrationManifest { + id: "github".to_string(), + version: "1.0.0".to_string(), + display_name: "GitHub".to_string(), + description: "GitHub integration".to_string(), + transport: McpTransport::Stdio, + transport_config: TransportConfig::Stdio { + command: "gh-mcp".to_string(), + args: vec!["serve".to_string()], + env: std::collections::BTreeMap::new(), + }, + capabilities: vec![code_integrations::CapabilitySpec { + name: "create_issue".to_string(), + description: "Create an issue".to_string(), + input_schema: json!({"type": "object"}), + output_schema: Some(json!({"type": "object"})), + permission_mode: PermissionMode::WorkspaceWrite, + idempotent: false, + }], + auth: Some(AuthSpec::ApiKey { + env_var: "GITHUB_TOKEN".to_string(), + header: None, + }), + events: vec![EventSpec { + name: "issue.opened".to_string(), + description: "An issue was opened".to_string(), + payload_schema: json!({"type": "object"}), + signature: Some(SignatureSpec::HmacSha256 { + secret_env: "GITHUB_WEBHOOK_SECRET".to_string(), + }), + }], + context_fields: vec![ContextFieldSpec { + name: "github.issue".to_string(), + description: "The linked GitHub issue".to_string(), + schema: json!({"type": "object"}), + }], + } + } + + #[test] + fn new_creates_an_empty_registry() { + let state = IntegrationsState::new(); + let registry = state + .registry + .lock() + .expect("registry is not poisoned"); + assert_eq!(registry.list().len(), 0); + } + + #[test] + fn from_json_reads_the_sample_json_over_builtins() { + let sample = sample_manifest(); + let raw = serde_json::to_string(&vec![sample]).expect("serialize sample"); + let base = code_integrations::builtin_providers().expect("built-ins validate"); + let state = IntegrationsState::from_json(&raw, base); + let registry = state + .registry + .lock() + .expect("registry is not poisoned"); + // The sample manifest overrides the built-in github (same id), and the + // other built-ins remain. + assert!(registry.get("github").is_some()); + assert_eq!(registry.list().len(), 4); + } + + #[test] + fn from_json_over_builtins_allows_a_custom_id_to_be_added() { + let custom = sample_manifest(); + let custom_raw = serde_json::to_string(&vec![custom]).expect("serialize"); + let base = code_integrations::builtin_providers().expect("built-ins validate"); + let state = IntegrationsState::from_json(&custom_raw, base); + let registry = state + .registry + .lock() + .expect("registry is not poisoned"); + assert_eq!(registry.list().len(), 4); + assert!(registry.get("sentry").is_some()); + } + + #[test] + fn from_json_with_empty_raw_keeps_only_builtins() { + let base = code_integrations::builtin_providers().expect("built-ins validate"); + let state = IntegrationsState::from_json("", base); + let registry = state + .registry + .lock() + .expect("registry is not poisoned"); + assert_eq!(registry.list().len(), 4); + for id in code_integrations::BUILTIN_PROVIDER_IDS { + assert!(registry.get(id).is_some(), "missing `{id}`"); + } + } + + static INTEGRATIONS_ENV_LOCK: std::sync::Mutex<()> = std::sync::Mutex::new(()); + + /// Build a state seeded with the built-in providers, wrapped in an + /// `Arc` for the integrations routes. + fn state_with_builtins() -> Arc { + Arc::new(crate::ServerState { + integrations: std::sync::Arc::new(IntegrationsState::with_builtins()), + ..crate::ServerState::default() + }) + } + + /// Fire a single request at a stateless router and return the response + /// status and body for assertions. The integrations router is built + /// per-call with the given state so each request sees the same snapshot. + async fn oneshot( + state: Arc, + method: &str, + uri: &str, + body: serde_json::Value, + ) -> (axum::http::StatusCode, Vec) { + use axum::body::Body; + use axum::http::Request; + use tower::ServiceExt; + + let router = integrations_routes().with_state(state); + let response = router + .oneshot( + Request::builder() + .method(method) + .uri(uri) + .header("content-type", "application/json") + .body(Body::from(serde_json::to_vec(&body).unwrap())) + .unwrap(), + ) + .await + .unwrap(); + let status = response.status(); + let bytes = axum::body::to_bytes(response.into_body(), usize::MAX) + .await + .unwrap() + .to_vec(); + (status, bytes) + } + + #[test] + fn load_from_env_reads_the_sample_json() { + let _guard = INTEGRATIONS_ENV_LOCK.lock().expect("env lock poisoned"); + let sample = sample_manifest(); + let raw = serde_json::to_string(&vec![sample]).expect("serialize sample"); + std::env::set_var(INTEGRATIONS_CONFIG_ENV, raw); + let state = IntegrationsState::load_from_env(); + std::env::remove_var(INTEGRATIONS_CONFIG_ENV); + let registry = state + .registry + .lock() + .expect("registry is not poisoned"); + // The sample manifest overrides the built-in github (same id), and the + // other built-ins remain. + assert!(registry.get("github").is_some()); + assert_eq!(registry.list().len(), 4); + } + + #[test] + fn load_from_env_skips_invalid_manifests() { + let _guard = INTEGRATIONS_ENV_LOCK.lock().expect("env lock poisoned"); + let raw = r#"[ + {"id": "Bad Id!", "version": "1.0.0", "display_name": "x", "description": "y", + "transport": "stdio", "transport_config": {"kind": "stdio", "command": "c", "args": [], "env": {}}, + "capabilities": [], "auth": null, "events": [], "context_fields": []}, + {"id": "good-one", "version": "2.0.0", "display_name": "Good", "description": "z", + "transport": "http", "transport_config": {"kind": "http", "url": "https://example.com", "headers": {}}, + "capabilities": [{"name": "ping", "description": "p", "input_schema": {"type": "object"}, + "permission_mode": "read_only", "idempotent": true}], + "auth": null, "events": [], "context_fields": []} + ]"#; + let base = code_integrations::builtin_providers().expect("built-ins validate"); + let state = IntegrationsState::from_json(raw, base); + let registry = state + .registry + .lock() + .expect("registry is not poisoned"); + // The bad manifest is skipped; the good one is added; built-ins remain. + assert!(registry.get("Bad Id!").is_none()); + assert!(registry.get("good-one").is_some()); + assert_eq!(registry.list().len(), 5); + } + + #[test] + fn with_builtins_seeds_all_four_providers() { + let state = IntegrationsState::with_builtins(); + let registry = state + .registry + .lock() + .expect("registry is not poisoned"); + assert_eq!(registry.list().len(), 4); + for id in code_integrations::BUILTIN_PROVIDER_IDS { + assert!(registry.get(id).is_some(), "missing `{id}`"); + } + } + + #[test] + fn summary_dto_serializes_with_expected_fields() { + let summary = IntegrationSummary::from(&sample_manifest()); + let value = serde_json::to_value(&summary).expect("serialize summary"); + assert_eq!(value["id"], "github"); + assert_eq!(value["version"], "1.0.0"); + assert_eq!(value["display_name"], "GitHub"); + assert_eq!(value["capability_count"], 1); + assert_eq!(value["auth_required"], true); + assert_eq!(value["event_count"], 1); + } + + #[test] + fn capability_dto_uses_snake_case_permission_labels() { + let spec = &sample_manifest().capabilities[0]; + let summary = CapabilitySummary::from(spec); + let value = serde_json::to_value(&summary).expect("serialize capability"); + assert_eq!(value["name"], "create_issue"); + assert_eq!(value["permission_mode"], "workspace_write"); + assert_eq!(value["idempotent"], false); + + let mut read_only = spec.clone(); + read_only.permission_mode = PermissionMode::ReadOnly; + assert_eq!( + CapabilitySummary::from(&read_only).permission_mode, + "read_only" + ); + let mut danger = spec.clone(); + danger.permission_mode = PermissionMode::DangerFullAccess; + assert_eq!( + CapabilitySummary::from(&danger).permission_mode, + "danger_full_access" + ); + } + + #[test] + fn event_dto_reports_signature_requirements() { + let event = &sample_manifest().events[0]; + let summary = EventSummary::from(event); + assert_eq!(summary.name, "issue.opened"); + assert!(summary.signature_required); + + let mut unsigned = event.clone(); + unsigned.signature = None; + assert!(!EventSummary::from(&unsigned).signature_required); + } + + #[test] + fn invoke_request_deserializes_an_input_value() { + let request: InvokeRequest = + serde_json::from_value(json!({"input": {"title": "bug", "body": "broken"}})) + .expect("deserialize invoke request"); + assert_eq!(request.input["title"], "bug"); + } + + #[tokio::test] + async fn routes_serve_the_manifest_surface() { + use axum::http::StatusCode; + + // The state is seeded with the built-in providers, so the list is + // non-empty and a built-in id (github) is present. + let state = state_with_builtins(); + let (status, bytes) = oneshot(state.clone(), "GET", "/v1/integrations", json!(null)).await; + assert_eq!(status, StatusCode::OK); + let body: Value = serde_json::from_slice(&bytes).unwrap(); + assert_eq!(body.as_array().expect("array").len(), 4); + + let (status, _) = oneshot(state.clone(), "GET", "/v1/integrations/github", json!(null)).await; + assert_eq!(status, StatusCode::OK); + + let (status, _) = oneshot(state.clone(), "GET", "/v1/integrations/github/capabilities", json!(null)).await; + assert_eq!(status, StatusCode::OK); + + let (status, _) = oneshot(state.clone(), "GET", "/v1/integrations/github/events", json!(null)).await; + assert_eq!(status, StatusCode::OK); + + // An unknown integration id still 404s. + let (status, _) = oneshot(state.clone(), "GET", "/v1/integrations/does-not-exist", json!(null)).await; + assert_eq!(status, StatusCode::NOT_FOUND); + + // ...and a known capability returns the 501 stub. + let (status, _) = oneshot( + state.clone(), + "POST", + "/v1/integrations/github/capabilities/create_pr/invoke", + json!({"input": {"title": "bug"}}), + ) + .await; + assert_eq!(status, StatusCode::NOT_IMPLEMENTED); + + // A capability that does not exist on the integration 404s. + let (status, _) = oneshot( + state.clone(), + "POST", + "/v1/integrations/github/capabilities/missing/invoke", + json!({"input": {}}), + ) + .await; + assert_eq!(status, StatusCode::NOT_FOUND); + } +} diff --git a/crates/code-server/src/lib.rs b/crates/code-server/src/lib.rs index f5044110..f7537f8b 100644 --- a/crates/code-server/src/lib.rs +++ b/crates/code-server/src/lib.rs @@ -15,6 +15,7 @@ use std::time::{Duration, Instant, SystemTime, UNIX_EPOCH}; mod audit; mod docker_worker; +mod integrations; mod publish; mod worker_access; mod worker_tokens; @@ -389,6 +390,7 @@ pub struct ServerState { publish_workspace_root: PathBuf, // Tasks with a publish in flight. Held so two requests cannot push the same task twice. publishing_tasks: Arc>>, + integrations: Arc, // Off unless configured. See `ServerConfig::allow_local_repos`. allow_local_repos: bool, } @@ -556,6 +558,7 @@ impl ServerState { .unwrap_or_default(), publish_workspace_root: default_server_workspace_root(), publishing_tasks: Arc::new(Mutex::new(HashSet::new())), + integrations: Arc::new(integrations::IntegrationsState::load_from_env()), allow_local_repos: false, }; state.recover_loaded_state(); @@ -1795,6 +1798,7 @@ pub fn app(state: Arc) -> Router { post(connector_interaction), ) .route("/v1/connectors/{connector}/events", post(connector_event)) + .merge(integrations::integrations_routes()) // Starting a login stores a pending state for the single tenant, so it needs the // control-plane key. It is a POST that returns the provider URL as JSON: a browser // navigation cannot send the `x-api-key` header, so the caller opens the returned @@ -5352,6 +5356,13 @@ impl AppError { message: message.into(), } } + + fn not_implemented(message: impl Into) -> Self { + Self { + status: StatusCode::NOT_IMPLEMENTED, + message: message.into(), + } + } } impl IntoResponse for AppError { diff --git a/docs/API_REFERENCES.md b/docs/API_REFERENCES.md index 52b8baec..b2d16540 100644 --- a/docs/API_REFERENCES.md +++ b/docs/API_REFERENCES.md @@ -14,6 +14,7 @@ This comprehensive reference covers the Frontal Code API for programmatic integr - [JavaScript API](#javascript-api) - [Error Handling](#error-handling) - [Rate Limiting](#rate-limiting) +- [Integrations API](#integrations-api) - [Examples](#examples) ## Overview @@ -246,6 +247,58 @@ PATCH /v1/config } ``` +#### Integrations + +List all registered integrations (built-ins + config overrides). + +```http +GET /v1/integrations +Authorization: Bearer +``` + +**Response:** `200 OK` — JSON array of integration summaries. + +Get a single integration manifest by id. + +```http +GET /v1/integrations/{id} +Authorization: Bearer +``` + +**Response:** `200 OK` — full `IntegrationManifest`. `404 Not Found` if the id is unknown. + +List capabilities for an integration. + +```http +GET /v1/integrations/{id}/capabilities +Authorization: Bearer +``` + +**Response:** `200 OK` — JSON array of capability summaries. `404` if the id is unknown. + +Invoke a capability. Stub in v1 — returns `501 Not Implemented`. + +```http +POST /v1/integrations/{id}/capabilities/{name}/invoke +Authorization: Bearer +Content-Type: application/json + +{ + "input": {} +} +``` + +**Response:** `501 Not Implemented`. MCP dispatch for capabilities is planned for a future release. + +List webhook events for an integration. + +```http +GET /v1/integrations/{id}/events +Authorization: Bearer +``` + +**Response:** `200 OK` — JSON array of event definitions. `404` if the id is unknown. + #### Status Get system status and health. diff --git a/docs/INTEGRATIONS.md b/docs/INTEGRATIONS.md new file mode 100644 index 00000000..f7536700 --- /dev/null +++ b/docs/INTEGRATIONS.md @@ -0,0 +1,274 @@ +# Integrations + +Frontal Code integrations are **fully typed, config-driven manifests**. The +server, CLI, and SDKs all consume the same `IntegrationManifest` shape — no +hardcoded provider code beyond the MCP transport layer. + +## Built-in providers + +Four first-party integrations ship as built-in manifests. They are seeded into +the registry on startup and can be overridden by project-level configuration: + +| id | display name | transport | auth | +| --- | --- | --- | --- | +| `github` | GitHub | `http` | API key (`GITHUB_TOKEN`) | +| `linear` | Linear | `http` | API key (`LINEAR_API_KEY`) | +| `posthog` | PostHog | `http` | API key (`POSTHOG_API_KEY`) | +| `sentry` | Sentry | `http` | API key (`SENTRY_AUTH_TOKEN`) | + +### GitHub + +| capability | permission | idempotent | +| --- | --- | --- | +| `create_pr` | `workspace_write` | no | +| `create_issue_comment` | `workspace_write` | no | +| `create_check_run` | `workspace_write` | no | + +### Linear + +| capability | permission | idempotent | +| --- | --- | --- | +| `create_issue_comment` | `workspace_write` | no | + +### PostHog + +| capability | permission | idempotent | +| --- | --- | --- | +| `capture_event` | `workspace_write` | yes | +| `capture_events_batch` | `workspace_write` | yes | + +### Sentry + +| capability | permission | idempotent | +| --- | --- | --- | +| `create_issue` | `workspace_write` | no | +| `create_issue_comment` | `workspace_write` | no | + +## Manifest schema + +An `IntegrationManifest` is a JSON document with the following shape: + +```json +{ + "id": "my-integration", + "version": "1.0.0", + "display_name": "My Integration", + "description": "What this integration does.", + "transport": "http", + "transport_config": { + "kind": "http", + "url": "https://api.example.com", + "headers": {} + }, + "capabilities": [ + { + "name": "do_thing", + "description": "Performs a thing.", + "input_schema": { "type": "object" }, + "output_schema": { "type": "object" }, + "permission_mode": "workspace_write", + "idempotent": false + } + ], + "auth": { + "kind": "api_key", + "env_var": "MY_API_KEY", + "header": "Authorization" + }, + "events": [], + "context_fields": [] +} +``` + +### Fields + +| field | type | required | description | +| --- | --- | --- | --- | +| `id` | `string` | yes | Unique identifier, lowercase alphanumeric + hyphens | +| `version` | `string` | yes | Semver version | +| `display_name` | `string` | yes | Human-readable name | +| `description` | `string` | yes | What the integration does | +| `transport` | `string` | yes | `stdio`, `http`, `sse`, `websocket`, `sdk`, or `managed_proxy` | +| `transport_config` | `object` | yes | Transport-specific config, tagged by `kind` | +| `capabilities` | `array` | yes | Capabilities exposed by the integration | +| `auth` | `object` | no | Auth spec: `none`, `oauth`, or `api_key` | +| `events` | `array` | no | Webhook events this integration can emit | +| `context_fields` | `array` | no | Fields written into task context | + +### Capability fields + +| field | type | required | description | +| --- | --- | --- | --- | +| `name` | `string` | yes | Capability identifier | +| `description` | `string` | yes | What the capability does | +| `input_schema` | `object` | yes | JSON Schema for input validation | +| `output_schema` | `object` | no | JSON Schema for output validation | +| `permission_mode` | `string` | yes | `read_only`, `workspace_write`, or `danger_full_access` | +| `idempotent` | `boolean` | yes | If true, safe to retry on failure | + +### Auth spec variants + +| kind | fields | +| --- | --- | +| `none` | — | +| `api_key` | `env_var` (string), `header` (string, optional) | +| `oauth` | `client_id_env`, `client_secret_env` (optional), `auth_url`, `token_url`, `scopes` (array), `redirect_path` (optional) | + +## Configuration + +### Environment variable + +Set `FRONTAL_CODE_INTEGRATIONS_CONFIG` to a JSON array of manifests. This is +layered **on top of** the built-in providers; a manifest whose `id` collides +with a built-in overrides it. + +```bash +export FRONTAL_CODE_INTEGRATIONS_CONFIG='[ + { + "id": "github", + "version": "2.0.0", + "display_name": "GitHub (custom)", + "description": "Custom GitHub config", + "transport": "http", + "transport_config": { "kind": "http", "url": "https://api.github.com", "headers": {} }, + "capabilities": [], + "auth": null, + "events": [], + "context_fields": [] + } +]' +``` + +### Settings file + +Declare integrations under `mcp.integrations` in `.frontal-code/settings.json`. +The CLI walks up from the current directory to find the settings file. Entries +with the same `id` as a built-in override it. + +```json +{ + "mcp": { + "integrations": { + "linear": { + "id": "linear", + "version": "2.0.0", + "display_name": "Linear (custom)", + "description": "Custom Linear config", + "transport": "http", + "transport_config": { "kind": "http", "url": "https://api.linear.app/graphql", "headers": {} }, + "capabilities": [], + "auth": { "kind": "api_key", "env_var": "LINEAR_API_KEY", "header": "Authorization" }, + "events": [], + "context_fields": [] + } + } + } +} +``` + +## CLI + +```bash +# List all integrations (built-ins + config overrides) +frontal-code integrations list + +# Show a single integration manifest +frontal-code integrations show github + +# List capabilities for an integration +frontal-code integrations capabilities github + +# Validate a manifest file +frontal-code integrations validate ./my-manifest.json +``` + +Add `--json` to any command for machine-readable output. + +## REST API + +| method | path | description | +| --- | --- | --- | +| `GET` | `/v1/integrations` | List all registered integrations | +| `GET` | `/v1/integrations/{id}` | Get a single manifest | +| `GET` | `/v1/integrations/{id}/capabilities` | List capabilities | +| `POST` | `/v1/integrations/{id}/capabilities/{name}/invoke` | Invoke a capability (501 stub in v1) | +| `GET` | `/v1/integrations/{id}/events` | List webhook events | + +### Examples + +```http +GET /v1/integrations +Authorization: Bearer +``` + +**Response:** +```json +[ + { + "id": "github", + "version": "1.0.0", + "display_name": "GitHub", + "description": "Manage pull requests, issues, and checks.", + "capability_count": 3, + "auth_required": true, + "event_count": 0 + } +] +``` + +```http +GET /v1/integrations/github/capabilities +Authorization: Bearer +``` + +**Response:** +```json +[ + { + "name": "create_pr", + "description": "Create a pull request.", + "permission_mode": "workspace_write", + "idempotent": false + } +] +``` + +## SDK clients + +### Rust + +```rust +use frontal_code_sdk::integrations::IntegrationClient; + +let client = IntegrationClient::new("http://localhost:8080"); +let integrations = client.list().await?; +let manifest = client.get("github").await?; +let capabilities = client.capabilities("github").await?; +``` + +### TypeScript + +```typescript +import { IntegrationClient } from "@frontal-labs/code-sdk"; + +const client = new IntegrationClient("http://localhost:8080"); +const integrations = await client.list(); +const manifest = await client.get("github"); +const capabilities = await client.capabilities("github"); +``` + +## Backward compatibility + +The legacy `IntegrationRegistry::call_*` methods in +`crates/code-integrations/src/mcp/integration.rs` remain as deprecated +adapters over the corresponding capabilities for one release. New code should +use the manifest-driven API. The deprecated wrappers currently cover: + +- `call_github_create_pr` → `github.create_pr` +- `call_github_create_issue_comment` → `github.create_issue_comment` +- `call_github_create_check_run` → `github.create_check_run` +- `call_linear_create_issue_comment` → `linear.create_issue_comment` +- `call_graphite_create_stack_comment` → (Graphite is not a built-in; this is + a legacy adapter only) +- `call_slack_post_message` → (Slack is not a built-in; this is a legacy + adapter only) diff --git a/docs/MCP.md b/docs/MCP.md index 056e9afa..019f650c 100644 --- a/docs/MCP.md +++ b/docs/MCP.md @@ -633,13 +633,18 @@ frontal-code prompt "Use Kubernetes to deploy the application and Docker to buil This MCP guide provides comprehensive coverage of MCP integration in Frontal Code, from basic usage to advanced custom server development. -## Native Integrations (GitHub, Linear, Graphite, Slack) +## Native Integrations -Frontal Code has **no hardcoded integrations**. Every external tracker (GitHub PRs, Linear -issues, Graphite stacks, Slack messages) is reached exclusively through an MCP server. -The server acts as an **MCP client**: it resolves a logical integration name -(`github`, `linear`, `graphite`, `slack`) to a configured MCP server and invokes that -server's tools. Adding a new provider requires **no code changes** — only config. +Frontal Code integrations are driven by **typed, declarative manifests** +(`IntegrationManifest`). The server, CLI, and SDKs all consume the same shape. +Four first-party providers ship as built-ins — `github`, `linear`, `posthog`, +and `sentry` — and can be overridden per-project via configuration. Adding a +new provider requires **no code changes** — only a manifest. + +Full reference: [docs/INTEGRATIONS.md](./INTEGRATIONS.md). + +The legacy MCP-based integration layer (used for Graphite and Slack) remains +as a deprecated adapter for one release; new code should use the manifest API. ### Configuration diff --git a/sdks/rust/Cargo.toml b/sdks/rust/Cargo.toml index c83a8f2d..a1db5fbb 100644 --- a/sdks/rust/Cargo.toml +++ b/sdks/rust/Cargo.toml @@ -15,9 +15,11 @@ rust-version = "1.80.0" [dependencies] tokio = { version = "1", features = ["process", "rt", "macros", "io-util", "sync"] } +serde = { version = "1", features = ["derive"] } serde_json = "1" thiserror = "1" futures-util = "0.3" +reqwest = { version = "0.13", default-features = false, features = ["json", "rustls"] } [dev-dependencies] tempfile = "3" diff --git a/sdks/rust/src/integrations.rs b/sdks/rust/src/integrations.rs new file mode 100644 index 00000000..83a48650 --- /dev/null +++ b/sdks/rust/src/integrations.rs @@ -0,0 +1,328 @@ +//! Typed client for the `Frontal Code` integrations HTTP API. +//! +//! The client talks to the `Frontal Code` server (the one the CLI wraps) and lets +//! SDK consumers discover registered integrations and invoke their capabilities +//! with full type safety. All types are self-contained; they mirror the server's +//! wire shape and do not depend on the server crate. + +use serde::{Deserialize, Serialize}; +use serde_json::Value; + +/// Summary of a registered integration (as returned by `GET /v1/integrations`). +#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)] +#[serde(rename_all = "snake_case")] +pub struct IntegrationSummary { + pub id: String, + pub version: String, + pub display_name: String, + pub description: String, + pub capability_count: usize, + pub auth_required: bool, + pub event_count: usize, +} + +/// Summary of a capability (as returned by `GET /v1/integrations/{id}/capabilities`). +#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)] +#[serde(rename_all = "snake_case")] +pub struct CapabilitySummary { + pub name: String, + pub description: String, + pub permission_mode: String, + pub idempotent: bool, +} + +/// A webhook event summary (as returned by `GET /v1/integrations/{id}/events`). +#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)] +#[serde(rename_all = "snake_case")] +pub struct EventSummary { + pub name: String, + pub description: String, + pub signature_required: bool, +} + +/// Authentication requirements declared by an integration. +#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)] +#[serde(rename_all = "snake_case")] +pub struct AuthSpec { + /// The auth kind: `"oauth"`, `"api_key"`, or `"none"`. + pub r#type: String, + #[serde(default, skip_serializing_if = "Option::is_none")] + pub client_id: Option, + #[serde(default, skip_serializing_if = "Option::is_none")] + pub token_url: Option, + #[serde(default, skip_serializing_if = "Option::is_none")] + pub authorize_url: Option, + #[serde(default, skip_serializing_if = "Option::is_none")] + pub scopes: Option>, +} + +/// The full integration manifest as returned by `GET /v1/integrations/{id}`. +/// +/// Fields beyond the well-known ones are preserved in [`Self::extra`] so the +/// client never fails on a newer server shape. +#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)] +#[serde(rename_all = "snake_case")] +pub struct IntegrationManifest { + pub id: String, + pub version: String, + pub display_name: String, + pub description: String, + pub transport: String, + #[serde(default, skip_serializing_if = "Option::is_none")] + pub transport_config: Option, + #[serde(default)] + pub capabilities: Vec, + #[serde(default, skip_serializing_if = "Option::is_none")] + pub auth: Option, + #[serde(default)] + pub events: Vec, + #[serde(flatten)] + pub extra: std::collections::BTreeMap, +} + +/// Errors surfaced by the [`IntegrationClient`]. +#[derive(Debug, thiserror::Error)] +pub enum IntegrationError { + #[error("http request failed: {0}")] + Http(#[from] reqwest::Error), + #[error("server returned status {status}: {body}")] + Server { status: u16, body: String }, + #[error("failed to parse response: {0}")] + Parse(String), +} + +impl IntegrationError { + /// The HTTP status code, when the error came from a non-2xx server response. + pub fn status(&self) -> Option { + match self { + Self::Server { status, .. } => Some(*status), + _ => None, + } + } + + /// The raw response body, when the error came from a non-2xx server response. + pub fn body(&self) -> Option<&str> { + match self { + Self::Server { body, .. } => Some(body), + _ => None, + } + } +} + +/// Typed client for the integrations API. +#[derive(Clone)] +pub struct IntegrationClient { + base_url: String, + http: reqwest::Client, +} + +impl std::fmt::Debug for IntegrationClient { + fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { + f.debug_struct("IntegrationClient") + .field("base_url", &self.base_url) + .finish_non_exhaustive() + } +} + +impl IntegrationClient { + /// Create a client pointing at the given server URL. + /// + /// A trailing slash is normalized away. + pub fn new(base_url: &str) -> Self { + Self { + base_url: base_url.trim_end_matches('/').to_string(), + http: reqwest::Client::new(), + } + } + + /// Create a client with a caller-supplied HTTP client (useful for tests and + /// custom TLS configuration). The base URL is normalized the same way as in + /// [`Self::new`]. + pub fn with_client(base_url: &str, http: reqwest::Client) -> Self { + Self { + base_url: base_url.trim_end_matches('/').to_string(), + http, + } + } + + /// The server URL this client is bound to, without a trailing slash. + pub fn base_url(&self) -> &str { + &self.base_url + } + + /// List all registered integrations. + pub async fn list(&self) -> Result, IntegrationError> { + let response = self.http.get(self.url("/v1/integrations")).send().await?; + let value = parse_json(response).await?; + serde_json::from_value(value).map_err(|e| IntegrationError::Parse(e.to_string())) + } + + /// Get the full manifest for one integration. + pub async fn get(&self, id: &str) -> Result { + let response = self + .http + .get(self.url(&format!("/v1/integrations/{id}"))) + .send() + .await?; + let value = parse_json(response).await?; + serde_json::from_value(value).map_err(|e| IntegrationError::Parse(e.to_string())) + } + + /// List capabilities for an integration. + pub async fn capabilities( + &self, + integration_id: &str, + ) -> Result, IntegrationError> { + let response = self + .http + .get(self.url(&format!("/v1/integrations/{integration_id}/capabilities"))) + .send() + .await?; + let value = parse_json(response).await?; + serde_json::from_value(value).map_err(|e| IntegrationError::Parse(e.to_string())) + } + + /// Invoke a capability with the given input. + pub async fn invoke( + &self, + integration_id: &str, + capability: &str, + input: &Value, + ) -> Result { + let response = self + .http + .post(self.url(&format!( + "/v1/integrations/{integration_id}/capabilities/{capability}/invoke" + ))) + .json(input) + .send() + .await?; + let status = response.status().as_u16(); + let body = response.text().await?; + if !(200..300).contains(&status) { + return Err(IntegrationError::Server { status, body }); + } + serde_json::from_str(&body).map_err(|e| IntegrationError::Parse(e.to_string())) + } + + /// List webhook events for an integration. + pub async fn events(&self, integration_id: &str) -> Result, IntegrationError> { + let response = self + .http + .get(self.url(&format!("/v1/integrations/{integration_id}/events"))) + .send() + .await?; + let value = parse_json(response).await?; + serde_json::from_value(value).map_err(|e| IntegrationError::Parse(e.to_string())) + } + + fn url(&self, path: &str) -> String { + format!("{}{path}", self.base_url) + } +} + +/// Send a response and, on success, parse the body as JSON. Non-2xx responses +/// become [`IntegrationError::Server`] with the raw body captured. +async fn parse_json( + response: reqwest::Response, +) -> Result { + let status = response.status().as_u16(); + let body = response.text().await?; + if !(200..300).contains(&status) { + return Err(IntegrationError::Server { status, body }); + } + serde_json::from_str(&body).map_err(|e| IntegrationError::Parse(e.to_string())) +} + +#[cfg(test)] +mod tests { + use super::*; + + const SUMMARY_JSON: &str = r#"{ + "id": "github", + "version": "1.2.0", + "display_name": "GitHub", + "description": "Issues, PRs, and repos", + "capability_count": 4, + "auth_required": true, + "event_count": 2 + }"#; + + #[test] + fn integration_summary_deserializes_from_sample_json() { + let summary: IntegrationSummary = serde_json::from_str(SUMMARY_JSON).expect("parses"); + assert_eq!(summary.id, "github"); + assert_eq!(summary.version, "1.2.0"); + assert_eq!(summary.display_name, "GitHub"); + assert_eq!(summary.description, "Issues, PRs, and repos"); + assert_eq!(summary.capability_count, 4); + assert!(summary.auth_required); + assert_eq!(summary.event_count, 2); + } + + #[test] + fn capability_summary_deserializes_from_sample_json() { + let json = r#"{ + "name": "create_issue", + "description": "Open an issue", + "permission_mode": "workspace_write", + "idempotent": false + }"#; + let cap: CapabilitySummary = serde_json::from_str(json).expect("parses"); + assert_eq!(cap.name, "create_issue"); + assert_eq!(cap.permission_mode, "workspace_write"); + assert!(!cap.idempotent); + } + + #[test] + fn manifest_preserves_unknown_fields_in_extra() { + let json = r#"{ + "id": "github", + "version": "1.2.0", + "display_name": "GitHub", + "description": "Issues, PRs, and repos", + "transport": "stdio", + "capabilities": [], + "events": [], + "context_fields": [{"name": "owner"}] + }"#; + let manifest: IntegrationManifest = serde_json::from_str(json).expect("parses"); + assert_eq!(manifest.id, "github"); + assert_eq!(manifest.transport, "stdio"); + assert!(manifest.auth.is_none()); + assert_eq!( + manifest.extra.get("context_fields").and_then(Value::as_array).map(Vec::len), + Some(1) + ); + } + + #[test] + fn client_new_strips_trailing_slash_and_exposes_base_url() { + let client = IntegrationClient::new("http://localhost:8790/"); + assert_eq!(client.base_url(), "http://localhost:8790"); + } + + #[test] + fn client_new_keeps_base_url_without_trailing_slash() { + let client = IntegrationClient::new("http://localhost:8790"); + assert_eq!(client.base_url(), "http://localhost:8790"); + } + + #[test] + fn server_error_exposes_status_and_body() { + let error = IntegrationError::Server { + status: 404, + body: "not found".to_string(), + }; + assert_eq!(error.status(), Some(404)); + assert_eq!(error.body(), Some("not found")); + assert_eq!(error.to_string(), "server returned status 404: not found"); + } + + #[test] + fn parse_error_exposes_detail() { + let error = IntegrationError::Parse("bad json".to_string()); + assert_eq!(error.status(), None); + assert_eq!(error.to_string(), "failed to parse response: bad json"); + } +} diff --git a/sdks/rust/src/lib.rs b/sdks/rust/src/lib.rs index 454d49e5..7035ffc1 100644 --- a/sdks/rust/src/lib.rs +++ b/sdks/rust/src/lib.rs @@ -14,11 +14,16 @@ mod code; mod config; +mod integrations; mod protocol; mod spawn; mod thread; pub use code::FrontalCode; +pub use integrations::{ + AuthSpec, CapabilitySummary, EventSummary, IntegrationClient, IntegrationError, + IntegrationManifest, IntegrationSummary, +}; pub use config::{config_to_args, flatten_config, merge_config, to_toml_literal}; pub use protocol::{ FrontalCodeEvent, FrontalCodeOptions, InputEntry, ThreadInput, ThreadItem, ThreadOptions, diff --git a/sdks/typescript/src/index.ts b/sdks/typescript/src/index.ts index d41aff31..7e1126a6 100644 --- a/sdks/typescript/src/index.ts +++ b/sdks/typescript/src/index.ts @@ -4,7 +4,15 @@ export { toTomlLiteral, } from "./config.js"; export { FrontalCode } from "./frontal-code.js"; +export { IntegrationClient, IntegrationError } from "./integrations.js"; export * from "./protocol.js"; +export type { + AuthSpec, + CapabilitySummary, + EventSummary, + IntegrationManifest, + IntegrationSummary, +} from "./integrations.js"; export type { BufferedTurn } from "./spawn.js"; export { collectTurn, FrontalCodeCliError, streamEvents } from "./spawn.js"; export { Thread } from "./thread.js"; diff --git a/sdks/typescript/src/integrations.ts b/sdks/typescript/src/integrations.ts new file mode 100644 index 00000000..189b37eb --- /dev/null +++ b/sdks/typescript/src/integrations.ts @@ -0,0 +1,172 @@ +/** + * HTTP client for the Frontal Code integration API. + * + * Talks to a running `frontal-code` server over HTTP using the global + * `fetch` (Node 18+). The endpoints and shapes mirror the server's + * `/v1/integrations` routes. + */ + +/** A lightweight listing entry for a registered integration. */ +export interface IntegrationSummary { + id: string; + version: string; + display_name: string; + description: string; + capability_count: number; + auth_required: boolean; + event_count: number; +} + +/** A single capability exposed by an integration. */ +export interface CapabilitySummary { + name: string; + description: string; + permission_mode: "read_only" | "workspace_write" | "danger_full_access"; + idempotent: boolean; +} + +/** A single event emitted by an integration. */ +export interface EventSummary { + name: string; + description: string; + signature_required: boolean; +} + +/** Authentication requirements for an integration, if any. */ +export interface AuthSpec { + type: "oauth" | "api_key" | "none"; + [key: string]: unknown; +} + +/** The full manifest describing an integration. */ +export interface IntegrationManifest { + id: string; + version: string; + display_name: string; + description: string; + transport: string; + capabilities: CapabilitySummary[]; + auth: AuthSpec | null; + events: EventSummary[]; +} + +/** Error raised when an integration API request fails. */ +export class IntegrationError extends Error { + readonly code: "http" | "server" | "parse"; + readonly status?: number; + readonly body?: string; + constructor(message: string, code: "http" | "server" | "parse", status?: number, body?: string) { + super(message); + this.name = "IntegrationError"; + this.code = code; + this.status = status; + this.body = body; + } +} + +/** + * A typed client for the Frontal Code integration API. + * + * The base URL is normalized (trailing slashes stripped) and each method + * throws {@link IntegrationError} on transport, server, or parse failures. + */ +export class IntegrationClient { + private readonly baseUrl: string; + + constructor(baseUrl: string) { + this.baseUrl = baseUrl.replace(/\/+$/, ""); + } + + /** List all registered integrations. `GET /v1/integrations` */ + async list(): Promise { + return this.getJson("/v1/integrations"); + } + + /** Fetch the manifest for a single integration. `GET /v1/integrations/{id}` */ + async get(id: string): Promise { + return this.getJson(`/v1/integrations/${encodeURIComponent(id)}`); + } + + /** List the capabilities of an integration. `GET /v1/integrations/{id}/capabilities` */ + async capabilities(integrationId: string): Promise { + return this.getJson( + `/v1/integrations/${encodeURIComponent(integrationId)}/capabilities`, + ); + } + + /** List the events of an integration. `GET /v1/integrations/{id}/events` */ + async events(integrationId: string): Promise { + return this.getJson( + `/v1/integrations/${encodeURIComponent(integrationId)}/events`, + ); + } + + /** + * Invoke a capability on an integration. `POST /v1/integrations/{id}/invoke` + * + * @param integrationId The integration to invoke against. + * @param capability The capability name to invoke. + * @param input The capability input payload. + */ + async invoke( + integrationId: string, + capability: string, + input: Record, + ): Promise { + const url = `${this.baseUrl}/v1/integrations/${encodeURIComponent(integrationId)}/invoke`; + let res: Response; + try { + res = await fetch(url, { + method: "POST", + headers: { "content-type": "application/json", accept: "application/json" }, + body: JSON.stringify({ capability, input }), + }); + } catch (err) { + throw new IntegrationError( + `integration request to ${url} failed: ${String(err)}`, + "http", + ); + } + + const body = await res.text(); + if (!res.ok) { + throw new IntegrationError( + `integration invoke failed with status ${res.status}: ${body}`, + "server", + res.status, + body, + ); + } + try { + return JSON.parse(body) as unknown; + } catch { + throw new IntegrationError("integration invoke response was not valid JSON", "parse", res.status, body); + } + } + + /** Perform a `GET` request and decode the JSON body. */ + private async getJson(path: string): Promise { + const url = `${this.baseUrl}${path}`; + let res: Response; + try { + res = await fetch(url, { headers: { accept: "application/json" } }); + } catch (err) { + throw new IntegrationError(`integration request to ${url} failed: ${String(err)}`, "http"); + } + + const body = await res.text(); + if (!res.ok) { + throw new IntegrationError( + `integration request failed with status ${res.status}: ${body}`, + "server", + res.status, + body, + ); + } + try { + return JSON.parse(body) as T; + } catch { + throw new IntegrationError("integration response was not valid JSON", "parse", res.status, body); + } + } +} diff --git a/sdks/typescript/tests/integrations.test.ts b/sdks/typescript/tests/integrations.test.ts new file mode 100644 index 00000000..bad3ab23 --- /dev/null +++ b/sdks/typescript/tests/integrations.test.ts @@ -0,0 +1,57 @@ +import { describe, expect, it, vi } from "vitest"; +import { IntegrationClient, IntegrationError } from "../src/integrations.js"; + +describe("IntegrationClient", () => { + it("normalizes a trailing slash on the base URL", async () => { + const client = new IntegrationClient("http://localhost:8080/"); + let capturedUrl = ""; + vi.stubGlobal( + "fetch", + vi.fn(async (url: RequestInfo | URL) => { + capturedUrl = String(url); + return new Response(JSON.stringify([]), { status: 200 }); + }), + ); + + await client.list(); + + expect(capturedUrl).toBe("http://localhost:8080/v1/integrations"); + vi.unstubAllGlobals(); + }); + + it("strips multiple trailing slashes", async () => { + const client = new IntegrationClient("http://localhost:8080///"); + let capturedUrl = ""; + vi.stubGlobal( + "fetch", + vi.fn(async (url: RequestInfo | URL) => { + capturedUrl = String(url); + return new Response(JSON.stringify([]), { status: 200 }); + }), + ); + + await client.list(); + + expect(capturedUrl).toBe("http://localhost:8080/v1/integrations"); + vi.unstubAllGlobals(); + }); +}); + +describe("IntegrationError", () => { + it("carries the error code, status, and body", () => { + const err = new IntegrationError("boom", "server", 500, '{"error":"boom"}'); + expect(err).toBeInstanceOf(Error); + expect(err.name).toBe("IntegrationError"); + expect(err.message).toBe("boom"); + expect(err.code).toBe("server"); + expect(err.status).toBe(500); + expect(err.body).toBe('{"error":"boom"}'); + }); + + it("leaves status and body undefined for http errors", () => { + const err = new IntegrationError("refused", "http"); + expect(err.code).toBe("http"); + expect(err.status).toBeUndefined(); + expect(err.body).toBeUndefined(); + }); +});