car_integrations/contacts/

mod.rs

//! Contacts capability — enumerate containers, query contacts.

use serde::{Deserialize, Serialize};
#[cfg(target_os = "macos")]
use std::process::Command;

use super::{Availability, IntegrationError};

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct Container {
    pub id: String,
    pub name: String,
    /// Source label (account / provider) when available.
    pub source: Option<String>,
}

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct Contact {
    pub id: String,
    pub container_id: Option<String>,
    pub display_name: String,
    #[serde(default)]
    pub emails: Vec<String>,
    #[serde(default)]
    pub phone_numbers: Vec<String>,
    pub organization: Option<String>,
}

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ContainerListing {
    #[serde(flatten)]
    pub availability: Availability,
    pub containers: Vec<Container>,
}

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ContactListing {
    #[serde(flatten)]
    pub availability: Availability,
    pub contacts: Vec<Contact>,
    /// Total match count, which may be larger than `contacts.len()` when
    /// the backend paginates.
    pub total: usize,
}

pub fn list_containers() -> Result<ContainerListing, IntegrationError> {
    backend::list_containers()
}

/// Query contacts with a free-text `query` (name, email, phone substring).
/// When `container_ids` is empty, searches all accessible containers.
pub fn list_contacts(
    query: &str,
    container_ids: &[String],
    limit: usize,
) -> Result<ContactListing, IntegrationError> {
    backend::list_contacts(query, container_ids, limit)
}

#[cfg(target_os = "macos")]
mod backend {
    use super::*;

    // Bump on any SCRIPT edit. ensure_helper()'s on-disk cache is keyed on
    // this string so stale binaries are superseded automatically — without
    // it, the helper compiled on first use is reused forever even after
    // bug fixes ship in the Rust source.
    const HELPER_VERSION: &str = "v4";

    const SCRIPT: &str = r#"
import Contacts
import Foundation
import Dispatch

struct ContainerOut: Codable {
    let id: String
    let name: String
    let source: String?
}

struct ContactOut: Codable {
    let id: String
    let container_id: String?
    let display_name: String
    let emails: [String]
    let phone_numbers: [String]
    let organization: String?
}

struct ContainerListing: Codable {
    let available: Bool
    let backend: String
    let reason: String?
    let containers: [ContainerOut]
}

struct ContactListing: Codable {
    let available: Bool
    let backend: String
    let reason: String?
    let contacts: [ContactOut]
    let total: Int
}

func emit<T: Encodable>(_ value: T) {
    let data = try! JSONEncoder().encode(value)
    FileHandle.standardOutput.write(data)
}

func ensureAccess(_ store: CNContactStore) -> String? {
    let status = CNContactStore.authorizationStatus(for: .contacts)
    switch status {
    case .authorized:
        return nil
    case .notDetermined:
        let semaphore = DispatchSemaphore(value: 0)
        var granted = false
        store.requestAccess(for: .contacts) { ok, _ in
            granted = ok
            semaphore.signal()
        }
        _ = semaphore.wait(timeout: .now() + 60)
        return granted ? nil : "Contacts permission was not granted"
    case .restricted:
        return "Contacts permission is restricted by system policy"
    case .denied:
        return "Contacts permission is denied"
    case .limited:
        return nil
    @unknown default:
        return "Contacts permission is unavailable"
    }
}

func displayName(_ contact: CNContact) -> String {
    if let formatted = CNContactFormatter.string(from: contact, style: .fullName), !formatted.isEmpty {
        return formatted
    }
    if !contact.nickname.isEmpty { return contact.nickname }
    if !contact.organizationName.isEmpty { return contact.organizationName }
    if let first = contact.emailAddresses.first { return first.value as String }
    return contact.identifier
}

let args = CommandLine.arguments
let mode = args.count > 1 ? args[1] : "containers"
let store = CNContactStore()
if let reason = ensureAccess(store) {
    if mode == "contacts" {
        emit(ContactListing(available: false, backend: "contacts_framework", reason: reason, contacts: [], total: 0))
    } else {
        emit(ContainerListing(available: false, backend: "contacts_framework", reason: reason, containers: []))
    }
    exit(0)
}

do {
    if mode == "contacts" {
        let query = args.count > 2 ? args[2].lowercased() : ""
        let limit = args.count > 3 ? (Int(args[3]) ?? 50) : 50
        let requested = Set(args.dropFirst(4))
        let containers = try store.containers(matching: nil).filter { requested.isEmpty || requested.contains($0.identifier) }
        // CNContactFormatter.descriptorForRequiredKeys(for: .fullName)
        // covers given/family/middle/prefix/suffix and anything else the
        // formatter reads internally. Hand-rolling the key list previously
        // omitted CNContactMiddleNameKey, which crashed displayName() with
        // EXC_CRASH (SIGABRT) via -[CNContact middleName] → NSException
        // when the formatter touched a contact with a middle name set.
        let keys: [CNKeyDescriptor] = [
            CNContactFormatter.descriptorForRequiredKeys(for: .fullName),
            CNContactIdentifierKey as CNKeyDescriptor,
            CNContactNicknameKey as CNKeyDescriptor,
            CNContactOrganizationNameKey as CNKeyDescriptor,
            CNContactEmailAddressesKey as CNKeyDescriptor,
            CNContactPhoneNumbersKey as CNKeyDescriptor
        ]
        var contacts: [ContactOut] = []
        var total = 0
        for container in containers {
            let predicate = CNContact.predicateForContactsInContainer(withIdentifier: container.identifier)
            for contact in try store.unifiedContacts(matching: predicate, keysToFetch: keys) {
                let name = displayName(contact)
                let emails = contact.emailAddresses.map { $0.value as String }
                let phones = contact.phoneNumbers.map { $0.value.stringValue }
                let haystack = ([name, contact.organizationName] + emails + phones).joined(separator: " ").lowercased()
                if !query.isEmpty && !haystack.contains(query) { continue }
                total += 1
                if contacts.count < limit {
                    contacts.append(ContactOut(
                        id: contact.identifier,
                        container_id: container.identifier,
                        display_name: name,
                        emails: emails,
                        phone_numbers: phones,
                        organization: contact.organizationName.isEmpty ? nil : contact.organizationName
                    ))
                }
            }
        }
        emit(ContactListing(available: true, backend: "contacts_framework", reason: nil, contacts: contacts, total: total))
    } else {
        let containers = try store.containers(matching: nil).map { container in
            ContainerOut(id: container.identifier, name: container.name, source: nil)
        }
        emit(ContainerListing(available: true, backend: "contacts_framework", reason: nil, containers: containers))
    }
} catch {
    if mode == "contacts" {
        emit(ContactListing(available: false, backend: "contacts_framework", reason: String(describing: error), contacts: [], total: 0))
    } else {
        emit(ContainerListing(available: false, backend: "contacts_framework", reason: String(describing: error), containers: []))
    }
}
"#;

    pub fn list_containers() -> Result<ContainerListing, IntegrationError> {
        run_swift(&["containers"])
    }

    pub fn list_contacts(
        query: &str,
        container_ids: &[String],
        limit: usize,
    ) -> Result<ContactListing, IntegrationError> {
        let limit = limit.to_string();
        let mut args = vec!["contacts", query, limit.as_str()];
        args.extend(container_ids.iter().map(String::as_str));
        run_swift(&args)
    }

    fn run_swift<T: serde::de::DeserializeOwned>(args: &[&str]) -> Result<T, IntegrationError> {
        let helper = ensure_helper()?;
        let output = Command::new(helper)
            .env(
                "SWIFT_MODULE_CACHE_PATH",
                std::env::temp_dir().join("car-swift-module-cache"),
            )
            .env(
                "CLANG_MODULE_CACHE_PATH",
                std::env::temp_dir().join("car-clang-module-cache"),
            )
            .args(args)
            .output()
            .map_err(|e| IntegrationError::Backend(format!("swift: {e}")))?;

        if !output.status.success() {
            let stderr = String::from_utf8_lossy(&output.stderr).trim().to_string();
            return Err(IntegrationError::Backend(format!(
                "contacts swift failed: {stderr}"
            )));
        }

        serde_json::from_slice(&output.stdout)
            .map_err(|e| IntegrationError::Backend(format!("contacts json: {e}")))
    }

    fn ensure_helper() -> Result<std::path::PathBuf, IntegrationError> {
        let dir = helper_cache_dir();
        let app = dir.join(format!("CAR Contacts Helper {HELPER_VERSION}.app"));
        let contents = app.join("Contents");
        let macos = contents.join("MacOS");
        let helper = macos.join("CAR Contacts Helper");
        if helper.exists() {
            return Ok(helper);
        }

        std::fs::create_dir_all(&macos)
            .map_err(|e| IntegrationError::Backend(format!("helper cache: {e}")))?;
        let source = dir.join(format!("car-contacts-helper-{HELPER_VERSION}.swift"));
        let plist = contents.join("Info.plist");
        let entitlements = dir.join(format!("car-contacts-helper-{HELPER_VERSION}.entitlements"));
        std::fs::write(&source, SCRIPT)
            .map_err(|e| IntegrationError::Backend(format!("contacts helper source: {e}")))?;
        std::fs::write(
            &plist,
            r#"<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>CFBundleIdentifier</key>
  <string>ai.parslee.car.contacts-helper</string>
  <key>CFBundleExecutable</key>
  <string>CAR Contacts Helper</string>
  <key>CFBundleName</key>
  <string>CAR Contacts Helper</string>
  <key>CFBundlePackageType</key>
  <string>APPL</string>
  <key>CFBundleShortVersionString</key>
  <string>0.9.0</string>
  <key>CFBundleVersion</key>
  <string>1</string>
  <key>NSContactsUsageDescription</key>
  <string>CAR reads contacts when an agent uses the contacts capability.</string>
</dict>
</plist>
"#,
        )
        .map_err(|e| IntegrationError::Backend(format!("contacts helper plist: {e}")))?;
        std::fs::write(
            &entitlements,
            r#"<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>com.apple.security.personal-information.addressbook</key>
  <true/>
</dict>
</plist>
"#,
        )
        .map_err(|e| IntegrationError::Backend(format!("contacts helper entitlements: {e}")))?;

        let status = Command::new("/usr/bin/swiftc")
            .env(
                "SWIFT_MODULE_CACHE_PATH",
                std::env::temp_dir().join("car-swift-module-cache"),
            )
            .env(
                "CLANG_MODULE_CACHE_PATH",
                std::env::temp_dir().join("car-clang-module-cache"),
            )
            .arg(&source)
            .arg("-o")
            .arg(&helper)
            .arg("-Xlinker")
            .arg("-sectcreate")
            .arg("-Xlinker")
            .arg("__TEXT")
            .arg("-Xlinker")
            .arg("__info_plist")
            .arg("-Xlinker")
            .arg(&plist)
            .status()
            .map_err(|e| IntegrationError::Backend(format!("swiftc: {e}")))?;

        if !status.success() {
            return Err(IntegrationError::Backend(format!(
                "contacts helper compile failed with status {status}"
            )));
        }

        sign_helper(&app, &entitlements)?;
        Ok(helper)
    }

    fn helper_cache_dir() -> std::path::PathBuf {
        if let Some(path) = std::env::var_os("CAR_NATIVE_HELPER_DIR") {
            return std::path::PathBuf::from(path);
        }
        if let Some(home) = std::env::var_os("HOME") {
            return std::path::PathBuf::from(home)
                .join("Library")
                .join("Application Support")
                .join("CAR")
                .join("NativeHelpers");
        }
        std::env::temp_dir().join("car-native-helpers")
    }

    fn sign_helper(
        app: &std::path::Path,
        entitlements: &std::path::Path,
    ) -> Result<(), IntegrationError> {
        let status = Command::new("/usr/bin/codesign")
            .arg("--force")
            .arg("--sign")
            .arg("-")
            .arg("--entitlements")
            .arg(entitlements)
            .arg(app)
            .status()
            .map_err(|e| IntegrationError::Backend(format!("codesign: {e}")))?;
        if !status.success() {
            return Err(IntegrationError::Backend(format!(
                "contacts helper codesign failed with status {status}"
            )));
        }
        Ok(())
    }
}

#[cfg(not(target_os = "macos"))]
mod backend {
    use super::*;

    pub fn list_containers() -> Result<ContainerListing, IntegrationError> {
        // Native Windows read (WinRT ContactManager) is the local answer; fall
        // through to Graph / pending only when it can't reach the store.
        #[cfg(target_os = "windows")]
        if let Ok(listing) = win_read::list_containers() {
            return Ok(listing);
        }
        // With Graph configured, the signed-in account is the one "container".
        if crate::msgraph::is_configured() {
            return Ok(ContainerListing {
                availability: Availability::available("msgraph"),
                containers: vec![Container {
                    id: "msgraph".into(),
                    name: "Microsoft 365".into(),
                    source: Some("microsoft".into()),
                }],
            });
        }
        Ok(ContainerListing {
            availability: current_backend_pending(),
            containers: vec![],
        })
    }

    pub fn list_contacts(
        query: &str,
        _container_ids: &[String],
        limit: usize,
    ) -> Result<ContactListing, IntegrationError> {
        // Native Windows read (WinRT ContactManager) is the local answer — but
        // only when it actually has one. Someone whose contacts live solely in
        // a configured M365 tenant, unsynced into the Windows People aggregate
        // store, would otherwise get `available` with zero contacts and Graph
        // never queried (car#683). See `crate::local_first`.
        #[cfg(target_os = "windows")]
        if let Some(listing) = crate::local_first::LocalRead::classify(
            win_read::list_contacts(query, _container_ids, limit),
            |listing| !listing.contacts.is_empty(),
        )
        .final_answer(crate::msgraph::is_configured())
        {
            return Ok(listing);
        }
        // Microsoft Graph backend (car#520) when configured; else pending.
        if crate::msgraph::is_configured() {
            match crate::msgraph::contacts(query, if limit == 0 { 200 } else { limit }) {
                Ok(contacts) => {
                    let total = contacts.len();
                    return Ok(ContactListing {
                        availability: Availability::available("msgraph"),
                        contacts,
                        total,
                    });
                }
                // A live failure (auth/network) is surfaced truthfully as
                // pending-with-reason, not a hard error.
                Err(e) => {
                    return Ok(ContactListing {
                        availability: Availability::pending("msgraph", e.to_string()),
                        contacts: vec![],
                        total: 0,
                    })
                }
            }
        }
        Ok(ContactListing {
            availability: current_backend_pending(),
            contacts: vec![],
            total: 0,
        })
    }

    // Native Windows Contacts read via WinRT. Verified to work from unpackaged
    // Win32 (no MSIX/package identity): `AllContactsReadOnly` returns the real
    // aggregate address book. Read-only — the unpackaged writable app store is
    // unstable across launches, so writes stay on Graph.
    #[cfg(target_os = "windows")]
    mod win_read {
        use super::*;
        use windows::ApplicationModel::Contacts::{
            ContactManager, ContactStore, ContactStoreAccessType,
        };

        fn open_store() -> Result<ContactStore, IntegrationError> {
            ContactManager::RequestStoreAsyncWithAccessType(
                ContactStoreAccessType::AllContactsReadOnly,
            )
            .and_then(|o| o.get())
            .map_err(|e| IntegrationError::Backend(format!("windows contacts store: {e}")))
        }

        pub fn list_containers() -> Result<ContainerListing, IntegrationError> {
            let store = open_store()?;
            let lists = store
                .FindContactListsAsync()
                .and_then(|o| o.get())
                .map_err(|e| IntegrationError::Backend(format!("contact lists: {e}")))?;
            let mut containers = Vec::new();
            for list in lists {
                let id = list.Id().map(|s| s.to_string_lossy()).unwrap_or_default();
                let name = list
                    .DisplayName()
                    .map(|s| s.to_string_lossy())
                    .unwrap_or_default();
                containers.push(Container {
                    id,
                    name,
                    source: Some("windows".into()),
                });
            }
            Ok(ContainerListing {
                availability: Availability::available("windows_contacts"),
                containers,
            })
        }

        pub fn list_contacts(
            query: &str,
            container_ids: &[String],
            limit: usize,
        ) -> Result<ContactListing, IntegrationError> {
            let store = open_store()?;
            let contacts = store
                .FindContactsAsync()
                .and_then(|o| o.get())
                .map_err(|e| IntegrationError::Backend(format!("find contacts: {e}")))?;
            let q = query.to_lowercase();
            let cap = if limit == 0 { usize::MAX } else { limit };
            let want: std::collections::HashSet<&str> =
                container_ids.iter().map(String::as_str).collect();
            let mut out = Vec::new();
            let mut total = 0usize;
            for c in contacts {
                let display_name = c
                    .DisplayName()
                    .map(|s| s.to_string_lossy())
                    .unwrap_or_default();
                let container_id = c
                    .ContactListId()
                    .map(|s| s.to_string_lossy())
                    .ok()
                    .filter(|s| !s.is_empty());
                if !want.is_empty()
                    && !container_id
                        .as_deref()
                        .map(|c| want.contains(c))
                        .unwrap_or(false)
                {
                    continue;
                }
                let emails: Vec<String> = c
                    .Emails()
                    .map(|v| {
                        v.into_iter()
                            .filter_map(|e| e.Address().ok().map(|s| s.to_string_lossy()))
                            .filter(|s| !s.is_empty())
                            .collect()
                    })
                    .unwrap_or_default();
                let phone_numbers: Vec<String> = c
                    .Phones()
                    .map(|v| {
                        v.into_iter()
                            .filter_map(|p| p.Number().ok().map(|s| s.to_string_lossy()))
                            .filter(|s| !s.is_empty())
                            .collect()
                    })
                    .unwrap_or_default();
                let organization = c.JobInfo().ok().and_then(|v| {
                    v.into_iter().find_map(|j| {
                        j.CompanyName()
                            .ok()
                            .map(|s| s.to_string_lossy())
                            .filter(|s| !s.is_empty())
                    })
                });
                if !q.is_empty() {
                    let hay = format!(
                        "{display_name} {} {} {}",
                        emails.join(" "),
                        phone_numbers.join(" "),
                        organization.clone().unwrap_or_default()
                    )
                    .to_lowercase();
                    if !hay.contains(&q) {
                        continue;
                    }
                }
                total += 1;
                if out.len() < cap {
                    let id = c.Id().map(|s| s.to_string_lossy()).unwrap_or_default();
                    out.push(Contact {
                        id,
                        container_id,
                        display_name,
                        emails,
                        phone_numbers,
                        organization,
                    });
                }
            }
            Ok(ContactListing {
                availability: Availability::available("windows_contacts"),
                contacts: out,
                total,
            })
        }
    }

    fn current_backend_pending() -> Availability {
        #[cfg(target_os = "windows")]
        {
            Availability::pending(
                "windows_contacts",
                "Windows contacts store unreachable; set CAR_MSGRAPH_CLIENT_ID \
             (Azure AD app) for the Microsoft Graph backend (car#520).",
            )
        }
        #[cfg(target_os = "linux")]
        {
            Availability::pending(
                "eds",
                "Evolution Data Server + CardDAV backends not yet wired. \
             API shape is stable; downstream apps can code against it now.",
            )
        }
        #[cfg(not(any(target_os = "macos", target_os = "windows", target_os = "linux")))]
        {
            Availability::pending("none", "Unsupported OS — no contacts backend modeled.")
        }
    }
}