1use serde_json::{Value, json};
2
3use crate::error;
4
5fn field(name: &str, kind: &str) -> Value {
6 json!({"name": name, "type": kind})
7}
8fn array_field(name: &str, item_kind: &str) -> Value {
9 json!({"name": name, "type": "array", "items": {"type": item_kind}})
10}
11fn nullable_field(name: &str, kind: &str) -> Value {
12 json!({"name": name, "type": kind, "nullable": true})
13}
14fn nullable_array_field(name: &str, item_kind: &str) -> Value {
15 json!({"name": name, "type": "array", "items": {"type": item_kind}, "nullable": true})
16}
17fn object_field(name: &str, nullable: bool, description: &str, fields: Vec<Value>) -> Value {
18 json!({"name": name, "type": "object", "nullable": nullable, "description": description, "fields": fields})
19}
20fn described(mut field: Value, description: &str) -> Value {
21 field["description"] = json!(description);
22 field
23}
24fn debugging_setup() -> Value {
25 object_field(
26 "debugging_setup",
27 true,
28 "Managed connection commands, available when no endpoint listens. Restart commands require confirmation and pass debugging flags only to the Teams launch; recover clears an interrupted setup; clear-flags removes debugging flags from the user-wide WebView2 setting after confirmation",
29 vec![
30 described(
31 field("shell", "string"),
32 "zsh, bash, wsl or powershell: where the commands run",
33 ),
34 field("open", "string"),
35 field("close", "string"),
36 ],
37 )
38}
39fn sender() -> Value {
40 object_field(
41 "from",
42 true,
43 "Sender; null for system events",
44 vec![object_field(
45 "user",
46 true,
47 "The sending user",
48 vec![
49 field("id", "string"),
50 nullable_field("displayName", "string"),
51 ],
52 )],
53 )
54}
55fn body() -> Value {
56 object_field(
57 "body",
58 false,
59 "Message content",
60 vec![
61 json!({"name": "contentType", "type": "string", "enum": ["text", "html"]}),
62 field("content", "string"),
63 ],
64 )
65}
66fn arg(name: &str, kind: &str, description: &str) -> Value {
67 json!({"name": name, "type": kind, "description": description})
68}
69fn required_arg(name: &str, kind: &str, description: &str) -> Value {
70 json!({"name": name, "type": kind, "description": description, "required": true})
71}
72
73fn single(name: &str, description: &str, effects: &str, fields: Vec<Value>) -> Value {
74 json!({"name": name, "description": description, "effects": effects, "cardinality": "single", "output_fields": fields})
75}
76
77fn paged(name: &str, description: &str, fields: Vec<Value>) -> Value {
78 json!({
79 "name": name, "description": description, "effects": "read_only", "cardinality": "unbounded",
80 "pagination": {"style": "cursor", "cursor_field": "next_cursor", "cursor_arg": "--cursor", "limit_arg": "--limit"},
81 "fields_arg": "--fields",
82 "args": [
83 {"name": "--limit", "type": "integer", "default": 50, "x-minimum": 1, "x-maximum": 50, "description": "Maximum records in this page"},
84 arg("--cursor", "string", "Opaque next_cursor value from the previous page; omit for the newest page"),
85 arg("--fields", "string", "Comma-separated top-level output fields to keep; unknown names are omitted")
86 ],
87 "output_fields": fields
88 })
89}
90
91fn offset_paged(name: &str, description: &str, fields: Vec<Value>) -> Value {
92 json!({
93 "name": name, "description": description, "effects": "read_only", "cardinality": "unbounded",
94 "pagination": {"style": "offset", "offset_arg": "--offset", "limit_arg": "--limit"},
95 "fields_arg": "--fields",
96 "args": [
97 {"name": "--limit", "type": "integer", "default": 50, "x-minimum": 1, "x-maximum": 100, "description": "Maximum records in this page"},
98 {"name": "--offset", "type": "integer", "default": 0, "x-minimum": 0, "description": "Number of records to skip; use next_offset from the previous page"},
99 arg("--fields", "string", "Comma-separated top-level output fields to keep; unknown names are omitted")
100 ],
101 "output_fields": fields
102 })
103}
104
105fn conversation_args() -> Vec<Value> {
106 vec![
107 json!({"name": "--chat", "type": "string", "x-conflicts": ["--team", "--channel"], "description": "Chat ID from chats list; give this, or --team with --channel"}),
108 json!({"name": "--team", "type": "string", "x-requires": ["--channel"], "description": "Team ID (Graph only)"}),
109 json!({"name": "--channel", "type": "string", "x-requires": ["--team"], "description": "Channel ID within --team (Graph only)"}),
110 ]
111}
112
113fn command_errors(name: &str) -> &'static [&'static str] {
116 const GRAPH_READ: &[&str] = &[
117 "auth",
118 "permission_denied",
119 "not_found",
120 "rate_limit",
121 "api_error",
122 "unsupported",
123 ];
124 const CONVERSATION_READ: &[&str] = &[
125 "auth",
126 "permission_denied",
127 "not_found",
128 "rate_limit",
129 "api_error",
130 "unsupported",
131 "desktop_error",
132 ];
133 match name {
134 "init" => &[
135 "auth",
136 "tty_required",
137 "confirmation_required",
138 "unsupported",
139 "desktop_error",
140 ],
141 "auth login" => &["auth", "tty_required", "unsupported"],
142 "auth logout" => &["unsupported"],
143 "auth status" => &["auth", "rate_limit", "api_error", "desktop_error"],
144 "profile remove" => &["confirmation_required"],
145 "whoami" | "list" | "channels list" => GRAPH_READ,
146 "chats list" | "messages list" | "people search" => CONVERSATION_READ,
147 "messages send" | "chats create" => &[
148 "auth",
149 "read_only",
150 "permission_denied",
151 "not_found",
152 "rate_limit",
153 "api_error",
154 "confirmation_required",
155 "unconfirmed",
156 "unsupported",
157 "desktop_error",
158 ],
159 "messages status" => &["unsupported", "desktop_error"],
160 "desktop status" => &["desktop_error", "unsupported"],
161 "desktop login" | "desktop connect" | "desktop disconnect" | "desktop recover" => {
162 &["desktop_error", "unsupported", "confirmation_required"]
163 }
164 "tui" => &["tty_required"],
165 "doctor" => &["unhealthy"],
166 "schema" => &["not_found"],
167 _ => &[],
168 }
169}
170
171fn example(name: &str) -> Value {
172 let (args, stdin): (&[&str], Option<&str>) = match name {
173 "init" => (&["init", "--no-login"], None),
174 "auth login" => (&["auth", "login", "--device-code"], None),
175 "auth logout" => (&["auth", "logout"], None),
176 "auth status" => (&["auth", "status", "--offline"], None),
177 "profile list" => (&["profile", "list"], None),
178 "profile use" => (&["profile", "use", "work"], None),
179 "profile remove" => (&["profile", "remove", "old", "--yes"], None),
180 "config show" => (&["config", "show"], None),
181 "config path" => (&["config", "path"], None),
182 "whoami" => (&["whoami"], None),
183 "list" => (&["list", "--limit", "20"], None),
184 "channels list" => (&["channels", "list", "TEAM_ID"], None),
185 "chats list" => (
186 &[
187 "chats",
188 "list",
189 "--limit",
190 "20",
191 "--fields",
192 "id,topic,lastUpdatedDateTime",
193 ],
194 None,
195 ),
196 "people search" => (&["people", "search", "Alex", "--limit", "20"], None),
197 "chats create" => (
198 &["chats", "create", "--recipient", "PERSON_ID", "--yes"],
199 None,
200 ),
201 "messages list" => (
202 &["messages", "list", "--chat", "CHAT_ID", "--limit", "20"],
203 None,
204 ),
205 "messages send" => (
206 &[
207 "messages", "send", "--chat", "CHAT_ID", "--body", "-", "--yes",
208 ],
209 Some("On it."),
210 ),
211 "messages status" => (
212 &[
213 "messages",
214 "status",
215 "--chat",
216 "CHAT_ID",
217 "--client-message-id",
218 "100000000000000001",
219 ],
220 None,
221 ),
222 "desktop status" => (&["desktop", "status", "--port", "9222"], None),
223 "desktop login" => (
224 &["desktop", "login", "--desktop-client", "browser", "--yes"],
225 None,
226 ),
227 "desktop connect" => (&["desktop", "connect", "--port", "9222", "--yes"], None),
228 "desktop disconnect" => (&["desktop", "disconnect", "--port", "9222", "--yes"], None),
229 "desktop recover" => (&["desktop", "recover", "--port", "9222"], None),
230 "tui" => (&["tui", "--demo", "--snapshot"], None),
231 "doctor" => (&["doctor", "--offline"], None),
232 "capabilities" => (&["capabilities"], None),
233 "schema" => (&["schema", "--command", "messages send"], None),
234 "completions" => (&["completions", "bash"], None),
235 _ => return Value::Null,
236 };
237 let mut value = json!({"args": args});
238 if let Some(stdin) = stdin {
239 value["stdin"] = json!(stdin);
240 }
241 value
242}
243
244pub fn generate(command_filter: Option<&str>) -> Value {
245 let identity = vec![
246 field("id", "string"),
247 field("displayName", "string"),
248 field("userPrincipalName", "string"),
249 nullable_field("mail", "string"),
250 ];
251 let mut commands = vec![
252 {
253 let mut value = single(
254 "init",
255 "Configure a Graph or experimental desktop profile; desktop init opens Teams' debugging port (restarting Teams after confirmation) and verifies a chat read",
256 "non_idempotent",
257 vec![
258 field("profile", "string"),
259 field("backend", "string"),
260 field("config_path", "string"),
261 nullable_field("signed_in", "boolean"),
262 field("client_id", "string"),
263 field("tenant", "string"),
264 field("channel_history_requested", "boolean"),
265 field("read_only", "boolean"),
266 nullable_field("desktop_port", "integer"),
267 nullable_field("desktop_account", "string"),
268 nullable_field("desktop_client", "string"),
269 nullable_field("endpoint_available", "boolean"),
270 nullable_field("connection", "object"),
271 field("session_verified", "boolean"),
272 nullable_field("teams_restarted", "boolean"),
273 nullable_field("browser_started", "boolean"),
274 nullable_field("chat_list_empty", "boolean"),
275 ],
276 );
277 value["args"] = json!([
278 {"name":"--backend","type":"string","enum":["graph","desktop"],"default":"graph","description":"Connection method; desktop supports diagnostics, chats and opt-in chat sending"},
279 {"name":"--desktop-port","type":"integer","description":"Loopback endpoint port (desktop only; native/browser default 9222, browser-core default 9223)","x-minimum":1024,"x-maximum":65535},
280 {"name":"--desktop-client","type":"string","enum":["native","browser","browser-core"],"default":"native","description":"Native Teams, installed Chrome/Edge, or a managed lightweight browser; core defaults to personal and downloads a matching browser pair on first sign-in"},
281 {"name":"--desktop-account","type":"string","enum":["auto","personal","work-school"],"default":"auto","description":"Select the Teams account surface; defaults to personal for browser-core, auto otherwise; multiple cached accounts remain unsupported"},
282 arg(
283 "--client-id",
284 "string",
285 "Override the maintained teams-cli public-client application ID"
286 ),
287 arg("--tenant", "string", "Tenant ID, domain, or organizations"),
288 arg(
289 "--no-login",
290 "boolean",
291 "Save configuration without sign-in or contacting Teams"
292 ),
293 arg("--device-code", "boolean", "Use device-code sign-in"),
294 arg(
295 "--channel-history",
296 "boolean",
297 "Request admin-consented channel-history access"
298 ),
299 {"name":"--read-only","type":"boolean","x-conflicts":["--allow-send"],"description":"Block remote write operations"},
300 {"name":"--allow-send","type":"boolean","x-requires":{"--backend":"desktop"},"x-conflicts":["--read-only"],"description":"Allow a desktop profile to send chat messages (desktop profiles are read-only otherwise)"}
301 ]);
302 value["confirmation_bypass_arg"] = json!("--yes");
303 value
304 },
305 {
306 let mut value = single(
307 "auth login",
308 "Sign in with delegated Microsoft OAuth and protect credentials in the OS store",
309 "idempotent",
310 vec![
311 field("profile", "string"),
312 field("expires_at", "integer"),
313 nullable_field("scope", "string"),
314 field("channel_history_requested", "boolean"),
315 ],
316 );
317 value["args"] = json!([
318 arg(
319 "--device-code",
320 "boolean",
321 "Use device-code sign-in for headless and remote environments"
322 ),
323 arg(
324 "--channel-history",
325 "boolean",
326 "Request admin-consented channel-history access"
327 )
328 ]);
329 value
330 },
331 single(
332 "auth logout",
333 "Remove locally stored delegated credentials",
334 "idempotent",
335 vec![field("profile", "string"), field("signed_in", "boolean")],
336 ),
337 {
338 let mut value = single(
339 "auth status",
340 "Verify authentication and inspect credential state",
341 "read_only",
342 vec![
343 field("profile", "string"),
344 field("configured", "boolean"),
345 field("backend", "string"),
346 nullable_field("signed_in", "boolean"),
347 field("verified", "boolean"),
348 nullable_field("identity", "object"),
349 field("config_path", "string"),
350 field("read_only", "boolean"),
351 nullable_array_field("granted_scopes", "string"),
352 nullable_field("channel_history", "boolean"),
353 nullable_field("endpoint_available", "boolean"),
354 nullable_field("connection", "object"),
355 field("session_verified", "boolean"),
356 ],
357 );
358 value["args"] = json!([arg(
359 "--offline",
360 "boolean",
361 "Inspect local state without contacting Graph or the desktop endpoint"
362 )]);
363 value
364 },
365 single(
366 "profile list",
367 "List configured profiles and identify the active one",
368 "read_only",
369 vec![
370 json!({"name": "items", "type": "array", "items": {"type": "object", "fields": [
371 field("name", "string"),
372 field("active", "boolean"),
373 json!({"name": "backend", "type": "string", "enum": ["graph", "desktop"]}),
374 field("client_id", "string"),
375 field("tenant", "string"),
376 field("read_only", "boolean")
377 ]}}),
378 field("total", "integer"),
379 ],
380 ),
381 {
382 let mut value = single(
383 "profile use",
384 "Select the default profile for future commands",
385 "idempotent",
386 vec![field("profile", "string"), field("active", "boolean")],
387 );
388 value["args"] = json!([required_arg("name", "string", "Profile name")]);
389 value
390 },
391 {
392 let mut value = single(
393 "profile remove",
394 "Remove a profile and its stored credential",
395 "idempotent",
396 vec![field("profile", "string"), field("removed", "boolean")],
397 );
398 value["args"] = json!([required_arg("name", "string", "Profile name")]);
399 value["confirmation_bypass_arg"] = json!("--yes");
400 value
401 },
402 single(
403 "config show",
404 "Print the resolved profile without credentials",
405 "read_only",
406 vec![
407 field("profile", "string"),
408 field("backend", "string"),
409 nullable_field("desktop_port", "integer"),
410 nullable_field("desktop_account", "string"),
411 nullable_field("desktop_client", "string"),
412 field("client_id", "string"),
413 field("tenant", "string"),
414 field("read_only", "boolean"),
415 field("config_path", "string"),
416 ],
417 ),
418 single(
419 "config path",
420 "Print the absolute configuration file path",
421 "read_only",
422 vec![],
423 ),
424 single(
425 "whoami",
426 "Show the signed-in Microsoft 365 identity",
427 "read_only",
428 identity,
429 ),
430 offset_paged(
431 "list",
432 "List teams joined by the signed-in user",
433 vec![
434 field("id", "string"),
435 field("displayName", "string"),
436 nullable_field("description", "string"),
437 ],
438 ),
439 {
440 let mut value = offset_paged(
441 "channels list",
442 "List channels in a team",
443 vec![
444 field("id", "string"),
445 field("displayName", "string"),
446 nullable_field("description", "string"),
447 field("membershipType", "string"),
448 ],
449 );
450 value["args"]
451 .as_array_mut()
452 .unwrap()
453 .insert(0, required_arg("team", "string", "Team ID"));
454 value
455 },
456 {
457 let mut value = single(
458 "people search",
459 "Find up to 50 verified people by name or email; refine the query when truncated; never sends or creates a chat",
460 "read_only",
461 vec![
462 field("id", "string"),
463 field("displayName", "string"),
464 nullable_field("email", "string"),
465 field("source", "string"),
466 ],
467 );
468 value["cardinality"] = json!("bounded");
469 value["args"] = json!([
470 {"name":"query","type":"string","required":true,"x-min-length":2,"x-max-length":256,"description":"Name or email prefix; 2–256 characters, no control characters"},
471 {"name":"--limit","type":"integer","default":20,"x-minimum":1,"x-maximum":50,"description":"Maximum matching people; refine the query for more specific results"}
472 ]);
473 value
474 },
475 {
476 let mut value = single(
477 "chats create",
478 "Create or reuse a one-to-one conversation with a verified person; requires a writable profile and confirmation; sends no message",
479 "idempotent",
480 vec![
481 field("id", "string"),
482 field("chatType", "string"),
483 nullable_field("topic", "string"),
484 nullable_field("source", "string"),
485 ],
486 );
487 value["args"] = json!([required_arg(
488 "--recipient",
489 "string",
490 "Exact person ID from people search in the same profile"
491 )]);
492 value["confirmation_bypass_arg"] = json!("--yes");
493 value
494 },
495 paged(
496 "chats list",
497 "List one-to-one, group, and meeting chats",
498 vec![
499 described(
500 field("id", "string"),
501 "Chat ID for messages list/send; the chat with yourself is 48:notes on desktop",
502 ),
503 json!({"name": "chatType", "type": "string", "enum": ["oneOnOne", "group", "meeting"]}),
504 nullable_field("topic", "string"),
505 described(field("lastUpdatedDateTime", "string"), "RFC 3339"),
506 json!({"name": "members", "type": "array", "items": {"type": "object", "fields": [
507 field("userId", "string"),
508 nullable_field("displayName", "string"),
509 described(field("avatarData", "string"), "Optional desktop-only raster data URI, from a photo already loaded by the selected Teams page; absent when unavailable")
510 ]}}),
511 described(
512 field("avatarData", "string"),
513 "Optional desktop-only one-to-one chat avatar as a raster data URI; member photos may be available for groups",
514 ),
515 object_field(
516 "viewpoint",
517 true,
518 "The signed-in user's read state",
519 vec![nullable_field("lastMessageReadDateTime", "string")],
520 ),
521 object_field(
522 "lastMessagePreview",
523 true,
524 "Latest message; desktop only",
525 vec![
526 field("id", "string"),
527 field("createdDateTime", "string"),
528 sender(),
529 body(),
530 ],
531 ),
532 ],
533 ),
534 {
535 let mut value = paged(
536 "messages list",
537 "List messages from one chat, or from a channel with optional admin-consented access",
538 vec![
539 field("id", "string"),
540 described(
541 field("createdDateTime", "string"),
542 "RFC 3339; pages are newest first",
543 ),
544 sender(),
545 body(),
546 described(nullable_field("deleted", "boolean"), "Desktop only"),
547 described(
548 nullable_field("clientMessageId", "string"),
549 "Desktop cache only; exact send correlation ID",
550 ),
551 described(
552 nullable_field("status", "string"),
553 "Desktop cache only; raw Teams status",
554 ),
555 ],
556 );
557 let args = value["args"].as_array_mut().unwrap();
558 args.splice(0..0, conversation_args());
559 value
560 },
561 {
562 let mut value = single(
563 "messages send",
564 "Send one plain-text message as the signed-in user",
565 "non_idempotent",
566 vec![
567 described(field("id", "string"), "Message ID"),
568 nullable_field("createdDateTime", "string"),
569 nullable_field("webUrl", "string"),
570 nullable_field("chatId", "string"),
571 described(
572 nullable_field("source", "string"),
573 "\"desktop\" for desktop sends",
574 ),
575 described(
576 nullable_field("clientMessageId", "string"),
577 "Desktop only; correlation ID, not an idempotency key",
578 ),
579 described(
580 nullable_field("delivery_state", "string"),
581 "Desktop only: submitted, queued, delivered, failed or unknown",
582 ),
583 described(
584 nullable_field("status", "string"),
585 "Desktop only; Teams' own delivery label, e.g. Delivered",
586 ),
587 ],
588 );
589 let mut args = conversation_args();
590 args.push(json!({"name": "--body", "type": "string", "required": true, "x-max-length": crate::desktop::MAX_BODY,
591 "description": "Plain-text message body, or - to read it from stdin; must not be blank"}));
592 value["args"] = json!(args);
593 value["confirmation_bypass_arg"] = json!("--yes");
594 value
595 },
596 json!({"name":"tui", "description":"Open the keyboard-first terminal interface; offers a confirmed Teams debugging restart on WSL when no endpoint listens; Enter sends a chat message on a profile that allows writes", "effects":"non_idempotent", "output_kind":"opaque", "media_type":"text/plain", "requires_tty":true, "args":[arg("--demo", "boolean", "Use deterministic sample data"), arg("--snapshot", "boolean", "Print one ANSI-free demo frame")]}),
597 {
598 let mut value = single(
599 "doctor",
600 "Check configuration and the selected backend's access (desktop checks endpoint metadata)",
601 "read_only",
602 vec![
603 field("backend", "string"),
604 array_field("checks", "object"),
605 field("healthy", "boolean"),
606 nullable_field("connection", "object"),
607 nullable_field("endpoint_available", "boolean"),
608 field("session_verified", "boolean"),
609 debugging_setup(),
610 ],
611 );
612 value["args"] = json!([arg(
613 "--offline",
614 "boolean",
615 "Check local state without contacting Graph or the desktop endpoint"
616 )]);
617 value
618 },
619 single(
620 "capabilities",
621 "Describe supported and deliberately unsupported capabilities",
622 "read_only",
623 vec![
624 array_field("supported", "string"),
625 array_field("unsupported", "string"),
626 array_field("account_types", "string"),
627 field("api", "string"),
628 array_field("notes", "string"),
629 field("backends", "object"),
630 ],
631 ),
632 json!({
633 "name":"schema",
634 "description":"Emit the offline CLI Spec v0.3 contract",
635 "effects":"read_only",
636 "cardinality":"single",
637 "stdout_schema":{},
638 "args":[arg("--command", "string", "Return only one complete command path")]
639 }),
640 json!({"name":"completions", "description":"Generate a shell completion script", "effects":"read_only", "output_kind":"opaque", "media_type":"text/plain", "args":[arg("shell", "string", "Shell name")]}),
641 ];
642 let mut status = single(
643 "messages status",
644 "Reconcile one client message ID against the newest 50 cached desktop messages; absence remains unknown",
645 "read_only",
646 vec![
647 field("chatId", "string"),
648 field("clientMessageId", "string"),
649 field("found", "boolean"),
650 nullable_field("id", "string"),
651 nullable_field("status", "string"),
652 field("delivery_state", "string"),
653 field("source", "string"),
654 field("scope", "string"),
655 field("retryable", "boolean"),
656 ],
657 );
658 status["args"] = json!([
659 required_arg("--chat", "string", "Chat ID"),
660 required_arg(
661 "--client-message-id",
662 "string",
663 "18-digit correlation ID returned by send or unconfirmed error"
664 )
665 ]);
666 commands.push(status);
667 for (name, description, effects) in [
668 (
669 "desktop login",
670 "Sign in visibly, verify chats, then restart headless with the same dedicated profile; browser only, requires confirmation",
671 "non_idempotent",
672 ),
673 (
674 "desktop status",
675 "Inspect endpoint metadata and managed-session state; does not verify sign-in",
676 "read_only",
677 ),
678 (
679 "desktop connect",
680 "Open a dedicated browser, or restart native Teams with debugging; requires confirmation",
681 "non_idempotent",
682 ),
683 (
684 "desktop disconnect",
685 "Close the verified dedicated browser, or restart managed native Teams normally; requires confirmation",
686 "non_idempotent",
687 ),
688 (
689 "desktop recover",
690 "Restore interrupted native settings; browser recovery may close a verified dedicated browser and requires confirmation",
691 "idempotent",
692 ),
693 ] {
694 let mut value = single(
695 name,
696 description,
697 effects,
698 vec![
699 field("port", "integer"),
700 nullable_field("endpoint_available", "boolean"),
701 field("session_verified", "boolean"),
702 field("management", "object"),
703 nullable_field("connection", "object"),
704 nullable_field("browser_profile", "string"),
705 ],
706 );
707 value["args"] = json!([{"name":"--desktop-client","type":"string","enum":["native","browser","browser-core"],"description":"Override the configured desktop client"},{"name":"--port","type":"integer","x-minimum":1024,"x-maximum":65535,"description":"Override selected profile port"}]);
708 if name == "desktop connect" {
709 value["args"].as_array_mut().expect("args").push(arg(
710 "--visible",
711 "boolean",
712 "Open the browser visibly for sign-in; browser client only",
713 ));
714 }
715 if matches!(
716 name,
717 "desktop login" | "desktop connect" | "desktop disconnect" | "desktop recover"
718 ) {
719 value["confirmation_bypass_arg"] = json!("--yes");
720 }
721 commands.push(value);
722 }
723 for command in &mut commands {
724 let name = command["name"].as_str().unwrap_or_default().to_string();
725 let mut errors = vec!["invalid_input", "unexpected_error"];
726 errors.extend(command_errors(&name));
727 command["errors"] = json!(errors);
728 let example = example(&name);
729 if !example.is_null() {
730 command["example"] = example;
731 }
732 command["extensions"] = json!({"backends": match command["name"].as_str().unwrap_or_default() {
733 "auth login" | "auth logout" | "whoami" | "list" | "channels list" => vec!["graph"],
734 "desktop status" | "desktop login" | "desktop connect" | "desktop disconnect" | "desktop recover" | "messages status" => vec!["desktop"],
735 _ => vec!["graph", "desktop"],
736 }});
737 match command["name"].as_str().unwrap_or_default() {
738 "tui" => {
739 command["extensions"]["desktop"] = json!(
740 "macOS/Windows/WSL (browser client also on Linux); chats and chat messages from the Teams client's local cache; sending needs a profile created with --allow-send"
741 )
742 }
743 "chats list" | "messages list" => {
744 command["extensions"]["desktop"] = json!(
745 "macOS/Windows/WSL (browser client also on Linux); chats, not channels; read from the Teams client's local cache; pages carry source \"desktop_cache\""
746 )
747 }
748 "messages send" => {
749 command["extensions"]["desktop"] = json!(
750 "macOS/Windows/WSL (browser client also on Linux); plain-text chat messages through the running Teams window; needs a profile created with `init --allow-send`; prompts on a terminal and needs --yes otherwise; results carry source \"desktop\", clientMessageId and Teams' status"
751 )
752 }
753 "people search" => {
754 command["extensions"]["graph"] = json!(
755 "Work/school directory profiles; User.ReadBasic.All consent required; guest callers and personal accounts unsupported"
756 );
757 command["extensions"]["desktop"] = json!(
758 "Uses the selected Teams client's own people search; IDs belong to that account and must not be reused with another profile"
759 );
760 }
761 "chats create" => {
762 command["extensions"]["graph"] = json!(
763 "Chat.Create; includes the signed-in user and verified recipient; returns an existing one-on-one chat when present; no automatic retry after an unconfirmed response"
764 );
765 command["extensions"]["desktop"] = json!(
766 "Needs a profile created with --allow-send; opens or creates a one-to-one chat through the selected Teams client; requires --yes without a terminal; sends no message"
767 );
768 }
769 _ => {}
770 }
771 }
772 if let Some(filter) = command_filter {
773 commands.retain(|value| value["name"] == filter);
774 }
775 json!({
776 "$schema": "https://clispec.dev/schema/v0.3.json",
777 "clispec": "0.3",
778 "name": "teams",
779 "version": env!("CARGO_PKG_VERSION"),
780 "description": "A Microsoft Teams CLI and TUI designed equally for humans and agents",
781 "output": {"tty": "text", "piped": "json"},
782 "global_args": [
783 {"name":"--output", "short":"-o", "type":"string", "enum":["auto","text","json"], "default":"auto", "description":"Output format"},
784 {"name":"--profile", "type":"string", "x-env":"TEAMS_PROFILE", "description":"Configuration profile; defaults to the active one"},
785 {"name":"--quiet", "type":"boolean", "description":"Suppress informational stderr output"},
786 {"name":"--yes", "short":"-y", "type":"boolean", "description":"Confirm without prompting (conversation creation, desktop sends, profile removal)"}
787 ],
788 "commands": commands,
789 "errors": error::ALL.iter().map(|e| json!({"kind":e.kind,"exit_code":e.exit_code,"retryable":e.retryable,"description":e.description})).collect::<Vec<_>>(),
790 "extensions": {
791 "backends":backend_capabilities(),
792 "authentication":"delegated_oauth",
793 "api":"Microsoft Graph v1.0",
794 "default_client_id": crate::config::DEFAULT_CLIENT_ID,
795 "login_modes":["browser_pkce","device_code"],
796 "read_only_env":"TEAMS_READ_ONLY",
797 "environment":{
798 "TEAMS_PROFILE":"Profile to use when --profile is not given",
799 "TEAMS_READ_ONLY":"true blocks every remote write; false cannot unlock a desktop profile",
800 "TEAMS_ACCESS_TOKEN":"Graph access token that overrides the stored credential for this run",
801 "TEAMS_CLIENT_ID":"Graph application ID override",
802 "TEAMS_TENANT":"Graph tenant override",
803 "TEAMS_DESKTOP_HELPER":"Path to a teams.exe speaking the same helper protocol to use as the WSL desktop helper"
804 },
805 "collection_envelope":{
806 "items":"array of records described by the command's output_fields",
807 "next_cursor":"cursor-paged commands: pass to --cursor for the next page; absent on the last page",
808 "next_offset":"offset-paged commands: pass to --offset for the next page; absent on the last page",
809 "truncated":"true when more records exist",
810 "source":"\"desktop_cache\" when records come from the Teams client's local cache; absent for Graph"
811 },
812 "error_envelope":"stderr carries {\"error\":{\"kind\",\"message\",\"retryable\"}} when stdout is not a terminal or --output json is given; rate_limit adds retry_after_seconds when Microsoft sends it; uncertain desktop sends add chatId, clientMessageId and delivery_state unknown",
813 "idempotency":"Sends cannot be made idempotent: neither Graph nor Teams accepts a caller-supplied key. Never resend after unconfirmed without reading the conversation first.",
814 "baseline_scopes": crate::auth::BASE_SCOPES.split_whitespace().collect::<Vec<_>>(),
815 "privileged_scopes":[crate::auth::CHANNEL_HISTORY_SCOPE]
816 }
817 })
818}
819
820pub fn backend_capabilities() -> Value {
821 json!({
822 "graph":{"default":true,"authentication":"delegated_oauth","api":"Microsoft Graph v1.0","account_types":["Microsoft 365 work or school"]},
823 "desktop":{"experimental":true,"read_only_by_default":true,"platforms":["macos","windows","wsl","linux"],"clients":{"native":["macos","windows","wsl"],"browser":["macos","linux","wsl"],"browser-core":["macos","linux","wsl"]},"browser_validation":"experimental; core personal messaging validated on macOS only","browser_core":{"account_types":["personal"],"bootstrap":"build-pinned; unknown builds refused","browser_versions":"automatically installed matching Chrome for Testing and chrome-headless-shell; paired path overrides supported","live_validation":["macos-personal"]},
824 "account_types":["Microsoft 365 work or school","personal Microsoft accounts"],"account_selection":"account_type_then_single_account_only",
825 "authentication":"teams_desktop_session_unverified","supported":["configuration","connection metadata","doctor","auth status","managed connect/status/disconnect/recover","delivery reconciliation by client message ID","people search","create or reuse one-to-one chats (opt-in)","chats (macos, windows, wsl; browser also on linux)","chat messages (macos, windows, wsl; browser also on linux)","send plain-text chat messages (macos, windows, wsl; browser also on linux; opt-in)","TUI (macos, windows, wsl; browser also on linux)"],
826 "unsupported":["teams and channels","identity","channel messages, replies, mentions, attachments and edits","subscriptions","unconfirmed Teams launch or restart"],
827 "requires":"native: Teams-owned loopback debugging endpoint (WSL needs Windows interop); browser: installed Chrome/Chromium/Edge with a dedicated profile and visible initial sign-in",
828 "transport":{"macos":"native_loopback","windows":"windows_native","wsl":"windows_helper_stdio","browser":"dedicated_chromium_loopback"},
829 "chat_source":"desktop_cache","session_verified":false,"default_port":crate::config::DEFAULT_DESKTOP_PORT}
830 })
831}