Skip to main content

iphone_cli/
human.rs

1//! `--human`: the same results, laid out for a person reading a terminal.
2
3use serde_json::Value;
4
5fn s(v: &Value) -> String {
6    match v {
7        Value::String(s) => s.clone(),
8        Value::Null => String::new(),
9        other => other.to_string(),
10    }
11}
12
13fn element_line(e: &Value) -> String {
14    let mut line = format!("{:<13}", s(&e["role"]));
15    if let Some(l) = e["label"].as_str() {
16        line.push_str(&format!(" \"{l}\""));
17    }
18    if let Some(v) = e["value"].as_str() {
19        line.push_str(&format!(" = \"{v}\""));
20    }
21    if let Some(i) = e["identifier"].as_str() {
22        line.push_str(&format!(" #{i}"));
23    }
24    if let f @ Value::Object(_) = &e["frame"] {
25        line.push_str(&format!(
26            "  @{},{} {}x{}",
27            s(&f["x"]),
28            s(&f["y"]),
29            s(&f["w"]),
30            s(&f["h"])
31        ));
32    }
33    if e["enabled"] == false {
34        line.push_str("  (disabled)");
35    }
36    if e["selected"] == true {
37        line.push_str("  (selected)");
38    }
39    if e["focused"] == true {
40        line.push_str("  (focused)");
41    }
42    if e["on_screen"] == false {
43        line.push_str("  (off screen)");
44    }
45    line.push_str(&format!("  [{}]", s(&e["id"])));
46    line
47}
48
49fn type_observation(v: &Value, out: &mut Vec<String>) {
50    if v.get("value_changed").is_some() {
51        let parts: Vec<String> = [
52            "verified",
53            "value_before",
54            "value",
55            "value_changed",
56            "screen_changed",
57            "submit_sent",
58        ]
59        .iter()
60        .map(|key| format!("{key}={}", v[*key]))
61        .collect();
62        out.push(format!("  {}", parts.join("  ")));
63    }
64    if let Some(message) = v["warning"]["message"].as_str() {
65        out.push(format!("  ⚠ {}: {message}", s(&v["warning"]["code"])));
66        if let Some(hint) = v["warning"]["hint"].as_str() {
67            out.push(format!("  → {hint}"));
68        }
69    }
70}
71
72fn size(bytes: u64) -> String {
73    match bytes {
74        b if b < 1024 => format!("{b} B"),
75        b if b < 1024 * 1024 => format!("{} KiB", b / 1024),
76        b => format!("{:.1} MiB", b as f64 / (1024.0 * 1024.0)),
77    }
78}
79
80fn syslog_entry(e: &Value) -> String {
81    let mut line = format!("  {:>7} {} {:<6} {}[{}]", s(&e["seq"]), s(&e["time"]), s(&e["level"]), s(&e["process"]), s(&e["pid"]));
82    if let Some(sub) = e["subsystem"].as_str() {
83        line.push_str(&format!(" {sub}/{}", s(&e["category"])));
84    }
85    line.push_str(&format!(": {}", s(&e["message"]).replace('\n', " ⏎ ")));
86    if e["message_cut"] == true {
87        line.push_str(" …");
88    }
89    line
90}
91
92/// What a capture is and holds: `start`, `status` and `stop`.
93fn syslog_status(v: &Value, out: &mut Vec<String>) {
94    if v["state"] == "none" {
95        out.push("✓ syslog: no capture".into());
96        return;
97    }
98    out.push(format!(
99        "✓ syslog {}  seen {}  kept {}  unparsed {}",
100        s(&v["state"]),
101        s(&v["seen"]),
102        s(&v["kept"]),
103        s(&v["unparsed"])
104    ));
105    let b = &v["buffer"];
106    let mut buffer = format!(
107        "  buffer {}/{} entries, {} of {}",
108        s(&b["entries"]),
109        s(&b["max_entries"]),
110        size(b["bytes"].as_u64().unwrap_or(0)),
111        size(b["max_bytes"].as_u64().unwrap_or(0))
112    );
113    if let (Some(oldest), Some(newest)) = (b["oldest_seq"].as_u64(), b["newest_seq"].as_u64()) {
114        buffer.push_str(&format!(", seq {oldest} to {newest}"));
115    }
116    buffer.push_str(&format!(", {} evicted", s(&b["evicted"])));
117    out.push(buffer);
118    let mut only = Vec::new();
119    if let Some(a) = v["app"].as_array() {
120        only.push(format!("app {}", a.iter().map(s).collect::<Vec<_>>().join(", ")));
121    }
122    if let Some(p) = v["process"].as_array() {
123        only.push(format!("process {}", p.iter().map(s).collect::<Vec<_>>().join(", ")));
124    }
125    if !v["pid"].is_null() {
126        only.push(format!("pid {}", s(&v["pid"])));
127    }
128    if !v["level"].is_null() {
129        only.push(format!("level {} and up", s(&v["level"])));
130    }
131    if !only.is_empty() {
132        out.push(format!("  only {}", only.join("  ")));
133    }
134    if let Some(path) = v["path"].as_str() {
135        out.push(format!("  file {path}  {} rotations", s(&v["rotations"])));
136    }
137    syslog_tail(v, out);
138}
139
140fn syslog_tail(v: &Value, out: &mut Vec<String>) {
141    if let Some(reason) = v["ended_reason"].as_str() {
142        out.push(format!("  ended: {reason}"));
143    }
144    if let Some(hint) = v["hint"].as_str() {
145        out.push(format!("  → {hint}"));
146    }
147}
148
149pub fn render(cmd: &str, v: &Value) -> String {
150    let mut out = Vec::new();
151    if v["ok"] != true {
152        out.push(format!(
153            "✗ {} ({}): {}",
154            s(&v["error"]["code"]),
155            s(&v["outcome"]),
156            s(&v["error"]["message"])
157        ));
158        if let Some(h) = v["error"]["hint"].as_str() {
159            out.push(format!("  → {h}"));
160        }
161        if let Some(c) = v["candidates"].as_array() {
162            for e in c {
163                out.push(format!("  · {}", element_line(e)));
164            }
165        }
166        if let step @ Value::Object(_) = &v["failed_step"] {
167            out.push(format!("  step {} ({})", s(&step["index"]), s(&step["kind"])));
168        }
169        if let call @ Value::Object(_) = &v["failed_call"] {
170            out.push(match call["line"].as_u64() {
171                Some(line) => format!("  line {line}: {}", s(&call["cmd"])),
172                None => format!("  in {}", s(&call["cmd"])),
173            });
174        }
175        if let Some(line) = v["line"].as_u64() {
176            out.push(format!("  line {line}"));
177        }
178        if let Some(sent) = v["inputs_sent"].as_u64().filter(|n| *n > 0) {
179            out.push(format!("  {sent} calls had already sent input"));
180        }
181        if let Some(labels) = v["screen_summary"]["labels"].as_array() {
182            let l: Vec<String> = labels.iter().map(s).collect();
183            out.push(format!("  on screen: {}", l.join(" · ")));
184        }
185        type_observation(v, &mut out);
186        out.push(format!("  {} ms", s(&v["elapsed_ms"])));
187        return out.join("\n");
188    }
189    match cmd {
190        "connect" => {
191            out.push(format!("✓ {}  wifi  {}  UDID verified, address saved", s(&v["udid"]), s(&v["ip"])));
192            out.push(s(&v["hint"]));
193        }
194        "read" | "find" => {
195            if cmd == "read" {
196                let apps: Vec<String> = v["apps"]
197                    .as_array()
198                    .map(|a| a.iter().map(|x| s(&x["name"])).collect())
199                    .unwrap_or_default();
200                out.push(format!(
201                    "{}  {}x{}  {} elements",
202                    apps.join(", "),
203                    s(&v["screen"]["width"]),
204                    s(&v["screen"]["height"]),
205                    s(&v["count"])
206                ));
207            } else {
208                out.push(format!("{} match(es) for {}", s(&v["count"]), s(&v["selector"])));
209            }
210            for e in v["elements"].as_array().into_iter().flatten() {
211                let indent = "  ".repeat(e["depth"].as_u64().unwrap_or(0) as usize);
212                out.push(format!("{indent}{}", element_line(e)));
213            }
214        }
215        "diagnose" => {
216            out.push(s(&v["report"]));
217            for finding in v["findings"].as_array().into_iter().flatten() {
218                out.push(format!("  {}", s(finding)));
219            }
220            out.push(s(&v["hint"]));
221        }
222        "doctor" => {
223            for c in v["checks"].as_array().into_iter().flatten() {
224                let mark = match c["status"].as_str() {
225                    Some("ok") => "✓",
226                    Some("fail") => "✗",
227                    Some("warn") => "!",
228                    Some("skipped") => "-",
229                    _ => "·",
230                };
231                let req = if c["required"] == true { "required" } else { "recommended" };
232                let mut line = format!("{mark} {:<22} {req}", s(&c["check"]));
233                if let Some(d) = c["detail"].as_str() {
234                    line.push_str(&format!("  ({d})"));
235                }
236                out.push(line);
237                if c["status"] != "ok"
238                    && let Some(a) = c["user_action"].as_str() {
239                        out.push(format!("    → {a}"));
240                    }
241            }
242            out.push(if v["ready"] == true { "ready".into() } else { "not ready".to_string() });
243        }
244        "devices" => {
245            for d in v["devices"].as_array().into_iter().flatten() {
246                out.push(format!(
247                    "{}  {}  iOS {}  {}  {}",
248                    s(&d["udid"]),
249                    s(&d["connection"]),
250                    s(&d["ios_version"]),
251                    s(&d["model"]),
252                    s(&d["state"])
253                ));
254            }
255            if out.is_empty() {
256                out.push("no devices".into());
257            }
258        }
259        "apps" => {
260            for a in v["apps"].as_array().into_iter().flatten() {
261                out.push(format!("{:<44} {}", s(&a["bundle_id"]), s(&a["name"])));
262            }
263        }
264        "scripts" => {
265            for r in v["scripts"].as_array().into_iter().flatten() {
266                out.push(format!("{:<24} {}  [{}]", s(&r["name"]), s(&r["description"]), s(&r["source"])));
267            }
268        }
269        "syslog" => match v["entries"].as_array() {
270            Some(entries) if v.get("cursor").is_some() => {
271                let mut head = format!("✓ syslog {}  {} entries  cursor {}", s(&v["state"]), entries.len(), s(&v["cursor"]));
272                if v["more"] == true {
273                    head.push_str("  more waiting");
274                }
275                if let Some(dropped) = v["dropped"].as_u64().filter(|d| *d > 0) {
276                    head.push_str(&format!("  {dropped} dropped before this read"));
277                }
278                out.push(head);
279                out.extend(entries.iter().map(syslog_entry));
280                syslog_tail(v, &mut out);
281            }
282            Some(entries) => {
283                syslog_status(v, &mut out);
284                out.push(format!("  matched {}, the latest {} below", s(&v["matched"]), entries.len()));
285                out.extend(entries.iter().map(syslog_entry));
286            }
287            None => syslog_status(v, &mut out),
288        },
289        "script" | "batch" => {
290            for line in v["logs"].as_array().into_iter().flatten() {
291                out.push(format!("  {}", s(line)));
292            }
293            for st in v["steps"].as_array().into_iter().flatten() {
294                out.push(format!(
295                    "✓ {:>2} {:<13} {:>5} ms",
296                    s(&st["index"]),
297                    s(&st["kind"]),
298                    s(&st["elapsed_ms"])
299                ));
300                if st["kind"] == "type" {
301                    type_observation(st, &mut out);
302                }
303            }
304            if let Some(o) = v["outputs"].as_object() {
305                for (k, val) in o {
306                    out.push(format!("{k} = {}", match val {
307                        Value::String(x) => x.clone(),
308                        other => serde_json::to_string_pretty(other).unwrap_or_default(),
309                    }));
310                }
311            }
312            out.push(format!("{} ms", s(&v["elapsed_ms"])));
313        }
314        _ => {
315            let mut parts = vec!["✓".to_string()];
316            for key in ["screen_changed", "foreground", "found", "scrolls", "value", "clipboard_restored", "path", "state", "stopped", "on", "focus", "set_by_iph"] {
317                if v.get("value_changed").is_some() && matches!(key, "value" | "screen_changed") {
318                    continue;
319                }
320                if !v[key].is_null() {
321                    parts.push(format!("{key}={}", s(&v[key])));
322                }
323            }
324            let e = &v["element"];
325            if e.is_object() {
326                let name = ["label", "value", "role"].iter().map(|k| s(&e[*k])).find(|n| !n.is_empty()).unwrap_or_default();
327                parts.push(format!("element=\"{name}\""));
328            }
329            parts.push(format!("{} ms", s(&v["elapsed_ms"])));
330            out.push(parts.join("  "));
331        }
332    }
333    type_observation(v, &mut out);
334    out.join("\n")
335}
336
337#[cfg(test)]
338mod tests {
339    use super::*;
340    use serde_json::json;
341
342    #[test]
343    fn type_warnings_and_unknown_observations_are_visible() {
344        let mut value = json!({
345            "ok": true, "value_before": "", "value": "", "verified": true,
346            "value_changed": false, "screen_changed": false, "submit_sent": false,
347            "warning": {"code": "value_unchanged", "message": "value is unchanged", "hint": "check paste permission"},
348        });
349        let text = render("type", &value);
350        assert!(text.contains("value_before=\"\""));
351        assert!(text.contains("value_changed=false"));
352        assert!(text.contains("value_unchanged: value is unchanged"));
353        assert!(text.contains("check paste permission"));
354        let mut step = value.clone();
355        step["kind"] = json!("type");
356        let batch = json!({"ok": true, "steps": [step]});
357        assert!(render("batch", &batch).contains("value_unchanged: value is unchanged"));
358        value["value"] = Value::Null;
359        value["value_changed"] = Value::Null;
360        value["screen_changed"] = Value::Null;
361        value["verified"] = json!(false);
362        let text = render("type", &value);
363        assert!(text.contains("value=null"));
364        assert!(text.contains("screen_changed=null"));
365        value["ok"] = json!(false);
366        value["error"] = json!({"code": "type_not_verified", "message": "Return withheld"});
367        let text = render("type", &value);
368        assert!(text.contains("Return withheld"));
369        assert!(text.contains("value_changed=null"));
370        assert!(text.contains("value_unchanged: value is unchanged"));
371    }
372
373    #[test]
374    fn syslog_prints_counts_a_page_and_the_matches_of_a_stop() {
375        let status = json!({
376            "ok": true, "state": "running", "seen": 5000, "kept": 1234, "unparsed": 0,
377            "buffer": {"entries": 1234, "bytes": 700_000, "max_entries": 100_000, "max_bytes": 67_108_864,
378                       "oldest_seq": 1, "newest_seq": 1234, "evicted": 0},
379            "started_at": "2026-11-19T01:00:00Z", "app": ["com.naver.papago"], "process": ["Preferences"], "level": "info",
380            "path": "/tmp/cap.jsonl", "rotations": 2,
381        });
382        let text = render("syslog", &status);
383        assert!(text.contains("syslog running  seen 5000  kept 1234  unparsed 0"));
384        assert!(text.contains("buffer 1234/100000 entries, 683 KiB of 64.0 MiB, seq 1 to 1234, 0 evicted"));
385        assert!(text.contains("only app com.naver.papago  process Preferences  level info and up"));
386        assert!(text.contains("file /tmp/cap.jsonl  2 rotations"));
387        assert!(render("syslog", &json!({"ok": true, "state": "none"})).contains("no capture"));
388
389        let entry = json!({"seq": 12, "time": "2026-11-19T01:02:03.004005Z", "pid": 412, "process": "Papago", "level": "error",
390                           "subsystem": "com.naver.papago", "category": "ui", "message": "line one\nline two", "message_cut": true});
391        let page = json!({"ok": true, "state": "ended", "count": 1, "entries": [entry], "cursor": 12, "more": true, "dropped": 3,
392                          "ended_reason": "the connection to the phone was reset"});
393        let text = render("syslog", &page);
394        assert!(text.starts_with("✓ syslog ended  1 entries  cursor 12  more waiting  3 dropped before this read"));
395        assert!(text.contains("12 2026-11-19T01:02:03.004005Z error  Papago[412] com.naver.papago/ui: line one ⏎ line two …"));
396        assert!(text.contains("ended: the connection to the phone was reset"));
397
398        let mut stopped = status.clone();
399        stopped["state"] = json!("ended");
400        stopped["matched"] = json!(7);
401        stopped["entries"] = json!([entry]);
402        let text = render("syslog", &stopped);
403        assert!(text.contains("syslog ended  seen 5000"));
404        assert!(text.contains("matched 7, the latest 1 below"));
405        assert!(text.contains("Papago[412]"));
406
407        let empty = json!({"ok": true, "state": "running", "count": 0, "entries": [], "cursor": 0, "more": false, "dropped": 0,
408                           "hint": "No entries yet."});
409        let text = render("syslog", &empty);
410        assert!(text.starts_with("✓ syslog running  0 entries  cursor 0\n"));
411        assert!(!text.contains("dropped") && text.contains("→ No entries yet."));
412    }
413
414    #[test]
415    fn element_without_label() {
416        let v = json!({"ok": true, "element": {"role": "search_field", "value": "검색"}, "elapsed_ms": 5});
417        assert_eq!(render("tap", &v), "✓  element=\"검색\"  5 ms");
418        let v = json!({"ok": false, "error": {"code": "x", "message": "m"}, "failed_step": {}, "failed_call": {}});
419        render("script", &v);
420    }
421}