smix_simctl/registry.rs
1//! `.smix/sims.json` device registry — deterministic device addressing.
2//!
3//! Every smix device operation targets either an explicit UDID or an
4//! alias recorded in this file. Resolution never consults the live
5//! simulator set: the registry file is the only mapping source, so a
6//! given input always resolves to the same device regardless of what
7//! happens to be booted on the machine.
8
9use serde::Deserialize;
10use std::collections::BTreeMap;
11use std::path::{Path, PathBuf};
12use thiserror::Error;
13
14/// Failure variants for registry load / device-ref resolution.
15#[derive(Debug, Error)]
16pub enum RegistryError {
17 /// Registry file could not be read.
18 #[error("cannot read sim registry {path}: {source}")]
19 Io {
20 /// Path that failed to read.
21 path: String,
22 /// Underlying I/O error.
23 source: std::io::Error,
24 },
25 /// Registry file is not valid registry JSON.
26 #[error("malformed sim registry {path}: {detail}")]
27 Malformed {
28 /// Path that failed to parse.
29 path: String,
30 /// Parser-side detail.
31 detail: String,
32 },
33 /// Input is neither a UDID nor a recorded alias.
34 #[error(
35 "unknown device ref {device_ref:?} — pass an explicit UDID or one of \
36 the recorded aliases: {}",
37 known.join(", ")
38 )]
39 UnknownDevice {
40 /// The input that failed to resolve.
41 device_ref: String,
42 /// Alias keys and device names available in the registry.
43 known: Vec<String>,
44 },
45}
46
47/// One registered simulator (a row of `.smix/sims.json`).
48#[derive(Debug, Clone, Deserialize)]
49pub struct RegisteredSim {
50 /// Human-chosen device name (also usable as an alias).
51 #[serde(rename = "deviceName")]
52 pub device_name: String,
53 /// CoreSimulator UDID.
54 pub udid: String,
55 /// Runtime identifier.
56 pub runtime: String,
57 /// Device type identifier.
58 #[serde(rename = "deviceType")]
59 pub device_type: String,
60 /// v6.10 c2 — desired BCP 47 locale tag (e.g. `"en-US"`, `"ja-JP"`).
61 /// When set, `smix sim boot` enforces it via
62 /// `defaults write -g AppleLanguages + AppleLocale` and reboots the
63 /// sim if the current locale differs. Closes insight gol-611 §3
64 /// (sim-managed sims default to zh-Hans → SpringBoard / app text
65 /// mismatches English yaml matchers). `None` (field absent) =
66 /// honor whatever locale the sim boots with, no enforcement.
67 #[serde(default)]
68 pub locale: Option<String>,
69}
70
71#[derive(Debug, Deserialize)]
72struct RegistryFile {
73 #[allow(dead_code)]
74 version: u32,
75 sims: BTreeMap<String, RegisteredSim>,
76}
77
78/// Loaded view of `.smix/sims.json`, keyed by alias.
79#[derive(Debug)]
80pub struct SimRegistry {
81 sims: BTreeMap<String, RegisteredSim>,
82}
83
84/// Whether `s` has CoreSimulator UDID form (8-4-4-4-12 hex).
85///
86/// UDID-form input is always treated as a deliberate instruction and
87/// never requires registry membership.
88pub fn is_udid(s: &str) -> bool {
89 let bytes = s.as_bytes();
90 if bytes.len() != 36 {
91 return false;
92 }
93 for (i, b) in bytes.iter().enumerate() {
94 match i {
95 8 | 13 | 18 | 23 => {
96 if *b != b'-' {
97 return false;
98 }
99 }
100 _ => {
101 if !b.is_ascii_hexdigit() {
102 return false;
103 }
104 }
105 }
106 }
107 true
108}
109
110impl SimRegistry {
111 /// Parse the registry file at `path`.
112 pub fn load(path: &Path) -> Result<Self, RegistryError> {
113 let text = std::fs::read_to_string(path).map_err(|source| RegistryError::Io {
114 path: path.display().to_string(),
115 source,
116 })?;
117 let file: RegistryFile =
118 serde_json::from_str(&text).map_err(|e| RegistryError::Malformed {
119 path: path.display().to_string(),
120 detail: e.to_string(),
121 })?;
122 Ok(Self { sims: file.sims })
123 }
124
125 /// Walk up from `start` looking for `.smix/sims.json`.
126 pub fn discover(start: &Path) -> Option<PathBuf> {
127 let mut dir = Some(start);
128 while let Some(d) = dir {
129 let candidate = d.join(".smix/sims.json");
130 if candidate.is_file() {
131 return Some(candidate);
132 }
133 dir = d.parent();
134 }
135 None
136 }
137
138 /// Resolve a device ref to a UDID.
139 ///
140 /// An explicit UDID passes through (normalized to uppercase) whether
141 /// or not it is registered — UDID-form input is always a deliberate
142 /// instruction. Otherwise the ref must match an alias key or a
143 /// `deviceName` exactly; anything else errors listing what exists.
144 pub fn resolve(&self, device_ref: &str) -> Result<String, RegistryError> {
145 if is_udid(device_ref) {
146 return Ok(device_ref.to_ascii_uppercase());
147 }
148 if let Some(sim) = self.sims.get(device_ref) {
149 return Ok(sim.udid.to_ascii_uppercase());
150 }
151 if let Some(sim) = self.sims.values().find(|s| s.device_name == device_ref) {
152 return Ok(sim.udid.to_ascii_uppercase());
153 }
154 let mut known: Vec<String> = Vec::with_capacity(self.sims.len() * 2);
155 for (alias, sim) in &self.sims {
156 known.push(alias.clone());
157 known.push(sim.device_name.clone());
158 }
159 Err(RegistryError::UnknownDevice {
160 device_ref: device_ref.to_string(),
161 known,
162 })
163 }
164
165 /// All registered sims, keyed by alias.
166 pub fn sims(&self) -> &BTreeMap<String, RegisteredSim> {
167 &self.sims
168 }
169
170 /// v6.10 c2 — look up a [`RegisteredSim`] by alias key, device name,
171 /// or UDID. Returns `None` if no entry matches any of the three.
172 /// Mirrors [`Self::resolve`]'s match precedence so cli callers can
173 /// fetch the full spec (e.g. `locale` field) after they already
174 /// resolved the UDID.
175 pub fn lookup(&self, device_ref: &str) -> Option<&RegisteredSim> {
176 if let Some(sim) = self.sims.get(device_ref) {
177 return Some(sim);
178 }
179 self.sims
180 .values()
181 .find(|sim| sim.device_name == device_ref || sim.udid.eq_ignore_ascii_case(device_ref))
182 }
183}