feat: add tbdflow json output for the radar command and update README

Intent Log:
- Working on the json output for the radar command
- It will be used in tbdflow-ui along with info and status
- Pre-sync safety snapshot

Author: cladam

README.md

@@ -165,11 +165,11 @@ tbdflow init --yes --main-branch trunk
 tbdflow init --yes --remote git@github.com:org/repo.git
 ```
 
-| Flag           | Description                                              |
-|----------------|----------------------------------------------------------|
-| -y, --yes      | Accept defaults, skip all interactive prompts.           |
-| --main-branch  | Set the main branch name (default: `main`).              |
-| --remote       | Link a remote repository URL and push the initial commit.|
+| Flag          | Description                                               |
+|---------------|-----------------------------------------------------------|
+| -y, --yes     | Accept defaults, skip all interactive prompts.            |
+| --main-branch | Set the main branch name (default: `main`).               |
+| --remote      | Link a remote repository URL and push the initial commit. |
 
 `.tbdflow.yml`
 This file controls the core workflow of the tool. You can customise:
@@ -349,11 +349,11 @@ the safety net.
 
 ## Global options
 
-| Flag      | Description                                              | Required |
-|-----------|----------------------------------------------------------|----------|
-| --verbose | Prints the underlying Git commands as they are executed. | No       |
-| --dry-run | Simulate the command without making any changes.         | No       |
-| --json    | Emit machine-readable JSON output instead of human-readable text. Supported by `info` and `status`. | No |
+| Flag      | Description                                                                                                   | Required |
+|-----------|---------------------------------------------------------------------------------------------------------------|----------|
+| --verbose | Prints the underlying Git commands as they are executed.                                                      | No       |
+| --dry-run | Simulate the command without making any changes.                                                              | No       |
+| --json    | Emit machine-readable JSON output instead of human-readable text. Supported by `info`, `status`, and `radar`. | No       |
 
 ## Commands
 
@@ -374,19 +374,19 @@ tbdflow commit [options]
 
 **Options:**
 
-| Flag | Option                 | Description                                              | Required |
-|------|------------------------|----------------------------------------------------------|----------|
-| -t   | --type                 | The type of commit (e.g., feat, fix, chore).             | Yes      |
-| -s   | --scope                | The scope of the changes (e.g., api, ui).                | No       |
-| -m   | --message              | The descriptive commit message (subject line).           | Yes      |
-|      | --message-file         | Read the subject from a file (`-` for stdin). Conflicts with --message. | No |
-|      | --body                 | Optional multi-line body for the commit message.         | No       |
-|      | --body-file            | Read the body from a file (`-` for stdin). Conflicts with --body. | No |
-| -b   | --breaking             | Mark the commit as a breaking change.                    | No       |
-|      | --breaking-description | Provide a description for the 'BREAKING CHANGE:' footer. | No       |
-|      | --tag                  | Optionally add and push an annotated tag to this commit. | No       |
-|      | --issue                | Optionally add an issue reference to the footer.         | No       |
-|      | --no-verify            | Bypass the interactive DoD checklist.                    | No       |
+| Flag | Option                 | Description                                                             | Required |
+|------|------------------------|-------------------------------------------------------------------------|----------|
+| -t   | --type                 | The type of commit (e.g., feat, fix, chore).                            | Yes      |
+| -s   | --scope                | The scope of the changes (e.g., api, ui).                               | No       |
+| -m   | --message              | The descriptive commit message (subject line).                          | Yes      |
+|      | --message-file         | Read the subject from a file (`-` for stdin). Conflicts with --message. | No       |
+|      | --body                 | Optional multi-line body for the commit message.                        | No       |
+|      | --body-file            | Read the body from a file (`-` for stdin). Conflicts with --body.       | No       |
+| -b   | --breaking             | Mark the commit as a breaking change.                                   | No       |
+|      | --breaking-description | Provide a description for the 'BREAKING CHANGE:' footer.                | No       |
+|      | --tag                  | Optionally add and push an annotated tag to this commit.                | No       |
+|      | --issue                | Optionally add an issue reference to the footer.                        | No       |
+|      | --no-verify            | Bypass the interactive DoD checklist.                                   | No       |
 
 **Example:**
 
@@ -951,6 +951,40 @@ trunk CI status (when `ci_check` is enabled):
 }
 ```
 
+**Radar data:**
+
+The `radar` command returns trunk health, file churn hotspots, and overlap detection in a single payload:
+
+```json
+{
+  "success": true,
+  "data": {
+    "trunk": {
+      "branch_name": "main",
+      "status": "green",
+      "last_integrated_minutes_ago": 12
+    },
+    "hotspots": [
+      { "file": "src/auth/logic.rs", "changes_count": 14 },
+      { "file": "src/db/schema.sql", "changes_count": 8 }
+    ],
+    "overlaps": [
+      {
+        "branch": "feat/API-42-user-auth",
+        "author": "@alicia",
+        "commits_ahead": 2,
+        "files": [
+          { "file": "src/auth/handler.rs", "level": "line" },
+          { "file": "src/auth/middleware.rs", "level": "file" }
+        ]
+      }
+    ],
+    "branches_scanned": 4,
+    "local_files_count": 3
+  }
+}
+```
+
 #### `undo`
 
 In TBD, the rule is simple: if the trunk breaks, fix it or revert it immediately. `tbdflow undo` is a smart wrapper

src/commands.rs

@@ -142,6 +142,44 @@ pub struct MonorepoStatusResponse {
     pub current_project: Option<String>,
 }
 
+/// JSON payload for `tbdflow radar --json`.
+#[derive(Serialize)]
+pub struct RadarResponse {
+    pub trunk: TrunkStatusResponse,
+    pub hotspots: Vec<HotspotResponse>,
+    pub overlaps: Vec<OverlapResponse>,
+    pub branches_scanned: usize,
+    pub local_files_count: usize,
+}
+
+#[derive(Serialize)]
+pub struct TrunkStatusResponse {
+    pub branch_name: String,
+    pub status: String,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub last_integrated_minutes_ago: Option<i64>,
+}
+
+#[derive(Serialize)]
+pub struct HotspotResponse {
+    pub file: String,
+    pub changes_count: usize,
+}
+
+#[derive(Serialize)]
+pub struct OverlapResponse {
+    pub branch: String,
+    pub author: String,
+    pub commits_ahead: u32,
+    pub files: Vec<OverlapFileResponse>,
+}
+
+#[derive(Serialize)]
+pub struct OverlapFileResponse {
+    pub file: String,
+    pub level: String,
+}
+
 pub fn handle_update_command() -> Result<(), anyhow::Error> {
     println!("{}", "--- Checking for updates ---".blue());
     let status = self_update::backends::github::Update::configure()

src/main.rs

@@ -180,7 +180,7 @@ fn main() -> anyhow::Result<()> {
             commands::handle_sync(opts, &config)?;
         }
         Commands::Radar => {
-            radar::handle_radar(opts, &config)?;
+            radar::handle_radar(opts, &config, json)?;
         }
         Commands::Status => {
             commands::handle_status(opts, &config, json)?;

src/radar.rs

@@ -1,3 +1,7 @@
+use crate::commands::{
+    HotspotResponse, OverlapFileResponse, OverlapResponse, RadarResponse, TbdResponse,
+    TrunkStatusResponse,
+};
 use crate::config::{Config, RadarLevel, RadarOnCommit};
 use crate::git::RunOpts;
 use crate::{git, intent};
@@ -247,7 +251,11 @@ fn should_ignore(file: &str, patterns: &[String]) -> bool {
     false
 }
 
-pub fn handle_radar(opts: RunOpts, config: &Config) -> Result<()> {
+pub fn handle_radar(opts: RunOpts, config: &Config, json: bool) -> Result<()> {
+    if json {
+        return handle_radar_json(opts, config);
+    }
+
     println!("{}", "--- Trunk Status ---".blue());
     let trunk = get_trunk_status(config, opts);
     print_trunk_status(&trunk, &config.main_branch_name);
@@ -336,6 +344,74 @@ pub fn handle_radar(opts: RunOpts, config: &Config) -> Result<()> {
     Ok(())
 }
 
+fn handle_radar_json(opts: RunOpts, config: &Config) -> Result<()> {
+    let trunk = get_trunk_status(config, opts);
+
+    let trunk_status_str = match &trunk.ci {
+        git::CiStatus::Green => "green",
+        git::CiStatus::Failed => "failed",
+        git::CiStatus::Pending => "pending",
+        git::CiStatus::Unknown(_) => "unknown",
+    };
+
+    let last_integrated_minutes_ago = git::get_latest_commit_time(&config.main_branch_name, opts)
+        .ok()
+        .flatten()
+        .map(|dt| Utc::now().signed_duration_since(dt).num_minutes());
+
+    git::fetch_origin(opts)?;
+    let hotspots = get_hotspots(config, opts)?;
+
+    let (overlaps, branches_scanned, local_files_count) = if config.radar.enabled {
+        let result = scan(config, opts)?;
+        let overlaps: Vec<OverlapResponse> = result
+            .overlaps
+            .iter()
+            .map(|o| OverlapResponse {
+                branch: o.branch_name.clone(),
+                author: format!("@{}", o.author),
+                commits_ahead: o.commits_ahead,
+                files: o
+                    .overlapping_files
+                    .iter()
+                    .map(|f| OverlapFileResponse {
+                        file: f.file_path.clone(),
+                        level: match &f.overlap_kind {
+                            OverlapKind::LineOverlap { .. } => "line".to_string(),
+                            OverlapKind::SameFile => "file".to_string(),
+                        },
+                    })
+                    .collect(),
+            })
+            .collect();
+        (overlaps, result.branches_scanned, result.local_files_count)
+    } else {
+        (vec![], 0, 0)
+    };
+
+    let response = RadarResponse {
+        trunk: TrunkStatusResponse {
+            branch_name: config.main_branch_name.clone(),
+            status: trunk_status_str.to_string(),
+            last_integrated_minutes_ago,
+        },
+        hotspots: hotspots
+            .into_iter()
+            .map(|(file, changes_count)| HotspotResponse {
+                file,
+                changes_count,
+            })
+            .collect(),
+        overlaps,
+        branches_scanned,
+        local_files_count,
+    };
+
+    let json_output = serde_json::to_string_pretty(&TbdResponse::ok(response))?;
+    println!("{}", json_output);
+    Ok(())
+}
+
 /// Silently captures a WIP snapshot if the working directory is dirty
 /// and the last snapshot with a hash is more than 30 minutes old.
 fn radar_snapshot(opts: RunOpts) {