use std::{
env,
io::{self, IsTerminal as _, Write as _},
path::Path,
sync::{
Arc, Mutex,
atomic::{AtomicU64, Ordering},
},
time::{Duration, Instant},
};
use serde_json::{Map, Value, json};
use crate::{args::ColorMode, error::CliError, process::CommandSpec, project::Project};
use self::terminal::{
LiveActivity, LiveDisplay, LiveProgress, PHASE_WIDTH, StreamCapabilities, TerminalCapabilities,
Tone, clear_line, command_action, format_duration, friendly_path, osc_progress,
progress_percent, render_live, styled,
};
mod terminal;
const EVENT_SCHEMA_VERSION: u8 = 1;
#[derive(Clone)]
pub struct Reporter {
inner: Arc<ReporterInner>,
}
struct ReporterInner {
format: OutputFormat,
quiet: bool,
verbose: bool,
terminal: TerminalCapabilities,
started: Instant,
sequence: AtomicU64,
stdout: Mutex<Box<dyn io::Write + Send>>,
human: Mutex<HumanOutput>,
}
#[derive(Clone, Copy, Eq, PartialEq)]
enum OutputFormat {
Human,
Json,
}
struct HumanOutput {
writer: Box<dyn io::Write + Send>,
live: Option<LiveDisplay>,
}
impl Reporter {
pub fn new(json: bool, quiet: bool, verbose: bool, color: ColorMode) -> Self {
let stdout_terminal = io::stdout().is_terminal();
let stderr_terminal = io::stderr().is_terminal();
let terminal_features =
stderr_terminal && env::var_os("TERM").is_none_or(|term| term != "dumb");
let colors_allowed = env::var_os("NO_COLOR").is_none() && terminal_features;
let stderr_color = !json
&& match color {
ColorMode::Auto => colors_allowed,
ColorMode::Always => true,
ColorMode::Never => false,
};
let stdout_color = !json
&& match color {
ColorMode::Auto => stdout_terminal && colors_allowed,
ColorMode::Always => true,
ColorMode::Never => false,
};
Self::with_writers(
json,
quiet,
verbose,
TerminalCapabilities {
stderr: StreamCapabilities {
color: stderr_color,
live: terminal_features,
},
stdout: StreamCapabilities {
color: stdout_color,
live: stdout_terminal,
},
},
Box::new(io::stdout()),
Box::new(io::stderr()),
)
}
fn with_writers(
json: bool,
quiet: bool,
verbose: bool,
terminal: TerminalCapabilities,
stdout: Box<dyn io::Write + Send>,
stderr: Box<dyn io::Write + Send>,
) -> Self {
Self {
inner: Arc::new(ReporterInner {
format: if json {
OutputFormat::Json
} else {
OutputFormat::Human
},
quiet,
verbose,
terminal,
started: Instant::now(),
sequence: AtomicU64::new(1),
stdout: Mutex::new(stdout),
human: Mutex::new(HumanOutput {
writer: stderr,
live: None,
}),
}),
}
}
pub fn is_json(&self) -> bool {
self.inner.format == OutputFormat::Json
}
pub fn uses_color(&self) -> bool {
self.inner.terminal.stderr.color
}
pub fn is_verbose(&self) -> bool {
self.inner.verbose
}
pub fn begin(&self, command: &str, dry_run: bool) {
if self.is_json() || self.inner.quiet {
return;
}
let brand = styled(self.inner.terminal.stderr.color, Tone::Accent, "kayro");
let command = styled(self.inner.terminal.stderr.color, Tone::Strong, command);
let suffix = if dry_run {
format!(
" {}",
styled(self.inner.terminal.stderr.color, Tone::Warning, "dry run")
)
} else {
String::new()
};
self.write_human(&format!(" {brand} {command}{suffix}\n"));
}
pub fn project(&self, project: &Project) {
if self.is_json() {
self.emit(
"project_resolved",
json!({
"root": project.root,
"config": project.config_path,
"frontend_dir": project.frontend_dir,
"native_manifest": project.native_manifest,
}),
);
} else if !self.inner.quiet {
self.status(
"◆",
Tone::Accent,
"project",
&friendly_path(&project.root),
None,
);
}
}
pub fn command_planned(&self, command: &CommandSpec) {
if self.is_json() {
self.emit("command_planned", command.json());
} else if !self.inner.quiet {
self.status(
"→",
Tone::Warning,
&command.phase,
&format!("Would {}", command_action(command).to_lowercase()),
None,
);
self.command_detail(command);
}
}
pub fn command_started(&self, command: &CommandSpec) {
if self.is_json() {
self.emit("command_started", command.json());
} else if !self.inner.quiet {
if self.inner.terminal.stderr.live {
self.set_activity(&command.phase, command_action(command));
} else {
self.status(
"◇",
Tone::Accent,
&command.phase,
command_action(command),
None,
);
}
if self.inner.verbose {
self.command_detail(command);
}
}
}
pub fn command_output(&self, phase: &str, stream: &str, line: &str) {
if self.inner.quiet {
return;
}
if !self.is_json() && line.trim().is_empty() {
return;
}
if self.is_json() {
self.emit(
"command_output",
json!({ "phase": phase, "stream": stream, "line": line }),
);
} else {
let phase = styled(
self.inner.terminal.stderr.color,
Tone::Muted,
&format!("{phase:<PHASE_WIDTH$}"),
);
let divider = styled(self.inner.terminal.stderr.color, Tone::Muted, "│");
self.write_human(&format!(" {phase} {divider} {line}\n"));
}
}
pub fn command_finished(&self, phase: &str, code: i32, elapsed: Duration) {
self.finish_live(code == 0);
if self.is_json() {
self.emit(
"command_finished",
json!({
"phase": phase,
"exit_code": code,
"duration_ms": millis(elapsed),
"success": code == 0,
}),
);
} else if !self.inner.quiet {
let duration = format_duration(elapsed);
match code {
0 => self.status("✓", Tone::Success, phase, "Done", Some(&duration)),
130 | 143 => self.status("·", Tone::Muted, phase, "Stopped", Some(&duration)),
_ => self.status(
"✕",
Tone::Error,
phase,
&format!("Failed with exit code {code}"),
Some(&duration),
),
}
}
}
pub fn compile_progress_started(&self, phase: &str, total: Option<usize>) {
if self.inner.quiet {
return;
}
if self.is_json() {
self.emit(
"compile_progress",
json!({
"phase": phase,
"completed": 0,
"total": total,
"percent": total.map(|_| 0),
"package": Value::Null,
}),
);
} else if self.inner.terminal.stderr.live {
self.update_progress(LiveProgress {
phase: phase.to_owned(),
completed: 0,
total,
package: Some("Preparing build graph".to_owned()),
});
}
}
pub fn compile_progress(
&self,
phase: &str,
completed: usize,
total: Option<usize>,
package: Option<&str>,
) {
if self.inner.quiet {
return;
}
let percent = total.map(|total| progress_percent(completed, total));
if self.is_json() {
self.emit(
"compile_progress",
json!({
"phase": phase,
"completed": completed,
"total": total,
"percent": percent,
"package": package,
}),
);
} else if self.inner.terminal.stderr.live {
self.update_progress(LiveProgress {
phase: phase.to_owned(),
completed,
total,
package: package.map(str::to_owned),
});
}
}
pub fn compile_progress_complete(
&self,
phase: &str,
completed: usize,
total: Option<usize>,
continuation: Option<&str>,
) {
if self.inner.quiet {
return;
}
let final_total = total.unwrap_or_else(|| completed.max(1));
if self.is_json() {
self.emit(
"compile_progress",
json!({
"phase": phase,
"completed": final_total,
"total": final_total,
"percent": 100,
"package": Value::Null,
}),
);
} else if self.inner.terminal.stderr.live {
self.update_progress(LiveProgress {
phase: phase.to_owned(),
completed: final_total,
total: Some(final_total),
package: Some("Compilation complete".to_owned()),
});
self.finish_live(true);
if let Some(message) = continuation {
self.set_activity(phase, message);
}
}
}
pub fn dev_server_ready(&self, url: &str, elapsed: Duration) {
if self.is_json() {
self.emit(
"dev_server_ready",
json!({ "url": url, "duration_ms": millis(elapsed) }),
);
} else if !self.inner.quiet {
self.finish_live(true);
let duration = format_duration(elapsed);
self.status(
"✓",
Tone::Success,
"web",
&format!("Ready at {url}"),
Some(&duration),
);
}
}
pub fn artifact(&self, path: &Path, target: Option<&str>, profile: &str) {
if self.is_json() {
self.emit(
"artifact",
json!({ "path": path, "target": target, "profile": profile }),
);
} else if self.inner.terminal.stdout.live && !self.inner.quiet {
self.status_to_stdout("✓", Tone::Success, "artifact", &friendly_path(path));
} else {
self.write_stdout(&format!("{}\n", path.display()));
}
}
pub fn bundle_planned(&self, formats: &[&str]) {
if self.is_json() {
self.emit("bundle_planned", json!({ "formats": formats }));
} else if !self.inner.quiet {
let formats = formats.join(", ");
self.status(
"→",
Tone::Warning,
"bundle",
&format!("Would create {formats}"),
None,
);
}
}
pub fn bundle_started(&self, formats: &[&str]) {
let message = format!("Creating {}", formats.join(", "));
if self.is_json() {
self.emit("bundle_started", json!({ "formats": formats }));
} else if !self.inner.quiet {
if self.inner.terminal.stderr.live {
self.set_activity("bundle", &message);
} else {
self.status("◇", Tone::Accent, "bundle", &message, None);
}
}
}
pub fn bundle_finished(&self, formats: &[&str], elapsed: Duration) {
self.finish_live(true);
if self.is_json() {
self.emit(
"bundle_finished",
json!({
"formats": formats,
"duration_ms": millis(elapsed),
"success": true,
}),
);
} else if !self.inner.quiet {
let duration = format_duration(elapsed);
self.status("✓", Tone::Success, "bundle", "Done", Some(&duration));
}
}
pub fn bundle_artifact(&self, path: &Path, format: &str, target: Option<&str>, profile: &str) {
if self.is_json() {
self.emit(
"bundle_artifact",
json!({
"path": path,
"format": format,
"target": target,
"profile": profile,
}),
);
} else if self.inner.terminal.stdout.live && !self.inner.quiet {
self.status_to_stdout("✓", Tone::Success, format, &friendly_path(path));
} else {
self.write_stdout(&format!("{}\n", path.display()));
}
}
pub fn scaffold_file(&self, path: &Path, dry_run: bool) {
if self.is_json() {
self.emit(
if dry_run {
"file_planned"
} else {
"file_written"
},
json!({ "action": "create", "path": path }),
);
} else if !self.inner.quiet {
let (symbol, tone, action) = if dry_run {
("→", Tone::Warning, "plan")
} else {
("+", Tone::Success, "create")
};
self.status(symbol, tone, action, &friendly_path(path), None);
}
}
pub fn scaffold_skipped(&self, path: &Path) {
if self.is_json() {
self.emit(
"file_skipped",
json!({ "path": path, "reason": "already_exists" }),
);
} else if !self.inner.quiet {
self.status("·", Tone::Muted, "keep", &friendly_path(path), None);
}
}
pub fn scaffold_created(&self, root: &Path, initialized_existing: bool, dry_run: bool) {
if self.is_json() {
self.emit(
if dry_run {
"project_planned"
} else {
"project_created"
},
json!({
"root": root,
"initialized_existing": initialized_existing,
}),
);
} else if self.inner.terminal.stdout.live && !self.inner.quiet {
let message = if dry_run {
format!("Would create {}", friendly_path(root))
} else if initialized_existing {
format!("Initialized {}", friendly_path(root))
} else {
format!("Created {}", friendly_path(root))
};
self.status_to_stdout("✓", Tone::Success, "project", &message);
} else {
self.write_stdout(&format!("{}\n", root.display()));
}
}
pub fn completed(&self, command: &str, dry_run: bool) {
if self.is_json() {
self.emit(
"completed",
json!({
"command": command,
"success": true,
"dry_run": dry_run,
"duration_ms": millis(self.inner.started.elapsed()),
}),
);
} else if !self.inner.quiet {
let duration = format_duration(self.inner.started.elapsed());
let message = if dry_run { "Plan complete" } else { "Finished" };
self.write_human("\n");
self.status("✓", Tone::Success, command, message, Some(&duration));
}
}
pub fn error(&self, error: &CliError) {
self.finish_live(false);
if self.is_json() {
self.emit(
"error",
json!({
"code": error.code(),
"message": error.to_string(),
"exit_code": error.exit_code(),
}),
);
} else {
let symbol = styled(self.inner.terminal.stderr.color, Tone::Error, "✕");
let heading = styled(self.inner.terminal.stderr.color, Tone::Error, "Error");
let code = styled(
self.inner.terminal.stderr.color,
Tone::Muted,
&format!("code {}", error.code()),
);
self.write_human(&format!(
"\n {symbol} {heading}\n {error}\n {code}\n"
));
}
}
pub fn argument_error(message: &str) {
let reporter = Self::new(true, false, false, ColorMode::Never);
reporter.emit(
"error",
json!({ "code": "invalid_arguments", "message": message, "exit_code": 2 }),
);
}
pub fn clap_display(event: &str, text: &str) {
let reporter = Self::new(true, false, false, ColorMode::Never);
reporter.emit(event, json!({ "text": text }));
}
fn command_detail(&self, command: &CommandSpec) {
let detail = styled(
self.inner.terminal.stderr.color,
Tone::Muted,
&format!("$ {}", command.display()),
);
self.write_human(&format!(" {detail}\n"));
}
fn status(&self, symbol: &str, tone: Tone, phase: &str, message: &str, trailing: Option<&str>) {
let symbol = styled(self.inner.terminal.stderr.color, tone, symbol);
let phase = styled(
self.inner.terminal.stderr.color,
Tone::Strong,
&format!("{phase:<PHASE_WIDTH$}"),
);
let trailing = trailing.map_or_else(String::new, |value| {
format!(
" {}",
styled(self.inner.terminal.stderr.color, Tone::Muted, value)
)
});
self.write_human(&format!(" {symbol} {phase} {message}{trailing}\n"));
}
fn status_to_stdout(&self, symbol: &str, tone: Tone, phase: &str, message: &str) {
let symbol = styled(self.inner.terminal.stdout.color, tone, symbol);
let phase = styled(
self.inner.terminal.stdout.color,
Tone::Strong,
&format!("{phase:<PHASE_WIDTH$}"),
);
self.write_stdout(&format!(" {symbol} {phase} {message}\n"));
}
fn update_progress(&self, progress: LiveProgress) {
let Ok(mut human) = self.inner.human.lock() else {
return;
};
if human.live.is_some() {
let _ = human.writer.write_all(clear_line().as_bytes());
}
let percent = progress
.total
.map(|total| progress_percent(progress.completed, total));
let osc = osc_progress(percent.map_or(3, |_| 1), percent.unwrap_or(0));
let display = LiveDisplay::Progress(progress);
let line = render_live(&display, self.inner.terminal.stderr.color);
human.live = Some(display);
let _ = human.writer.write_all(osc.as_bytes());
let _ = human.writer.write_all(line.as_bytes());
let _ = human.writer.flush();
}
fn set_activity(&self, phase: &str, message: &str) {
let Ok(mut human) = self.inner.human.lock() else {
return;
};
if human.live.is_some() {
let _ = human.writer.write_all(clear_line().as_bytes());
}
let display = LiveDisplay::Activity(LiveActivity {
phase: phase.to_owned(),
message: message.to_owned(),
});
let line = render_live(&display, self.inner.terminal.stderr.color);
human.live = Some(display);
let _ = human.writer.write_all(line.as_bytes());
let _ = human.writer.flush();
}
fn finish_live(&self, success: bool) {
if self.is_json() || !self.inner.terminal.stderr.live {
return;
}
let Ok(mut human) = self.inner.human.lock() else {
return;
};
let Some(display) = human.live.take() else {
return;
};
let _ = human.writer.write_all(clear_line().as_bytes());
if let LiveDisplay::Progress(progress) = display {
let percent = progress
.total
.map_or(0, |total| progress_percent(progress.completed, total));
let state = if success { 1 } else { 2 };
let _ = human
.writer
.write_all(osc_progress(state, if success { 100 } else { percent }).as_bytes());
let _ = human.writer.write_all(osc_progress(0, 0).as_bytes());
}
let _ = human.writer.flush();
}
fn write_stdout(&self, output: &str) {
if let Ok(mut writer) = self.inner.stdout.lock() {
let _ = writer.write_all(output.as_bytes());
let _ = writer.flush();
}
}
fn write_human(&self, output: &str) {
let Ok(mut human) = self.inner.human.lock() else {
return;
};
let live_display = human.live.clone();
if live_display.is_some() {
let _ = human.writer.write_all(clear_line().as_bytes());
}
let _ = human.writer.write_all(output.as_bytes());
if let Some(live_display) = live_display {
let rendered = render_live(&live_display, self.inner.terminal.stderr.color);
let _ = human.writer.write_all(rendered.as_bytes());
}
let _ = human.writer.flush();
}
fn emit(&self, event: &str, data: Value) {
let Ok(mut writer) = self.inner.stdout.lock() else {
return;
};
let sequence = self.inner.sequence.fetch_add(1, Ordering::Relaxed);
let mut object = Map::new();
object.insert("schema_version".to_owned(), json!(EVENT_SCHEMA_VERSION));
object.insert("sequence".to_owned(), json!(sequence));
object.insert(
"elapsed_ms".to_owned(),
json!(millis(self.inner.started.elapsed())),
);
object.insert("event".to_owned(), json!(event));
if let Value::Object(data) = data {
object.extend(data);
}
if serde_json::to_writer(&mut *writer, &object).is_ok() {
let _ = writer.write_all(b"\n");
let _ = writer.flush();
}
}
}
fn millis(duration: Duration) -> u64 {
u64::try_from(duration.as_millis()).unwrap_or(u64::MAX)
}
#[cfg(test)]
mod tests {
use std::{
path::PathBuf,
sync::{Arc, Mutex},
};
use super::*;
#[derive(Clone)]
struct SharedBuffer(Arc<Mutex<Vec<u8>>>);
type CapturedBuffer = Arc<Mutex<Vec<u8>>>;
impl io::Write for SharedBuffer {
fn write(&mut self, buffer: &[u8]) -> io::Result<usize> {
self.0.lock().unwrap().extend_from_slice(buffer);
Ok(buffer.len())
}
fn flush(&mut self) -> io::Result<()> {
Ok(())
}
}
fn reporter(
json: bool,
quiet: bool,
terminal: TerminalCapabilities,
) -> (Reporter, CapturedBuffer, CapturedBuffer) {
let stdout = Arc::new(Mutex::new(Vec::new()));
let stderr = Arc::new(Mutex::new(Vec::new()));
let reporter = Reporter::with_writers(
json,
quiet,
false,
terminal,
Box::new(SharedBuffer(Arc::clone(&stdout))),
Box::new(SharedBuffer(Arc::clone(&stderr))),
);
(reporter, stdout, stderr)
}
fn text(buffer: &Mutex<Vec<u8>>) -> String {
String::from_utf8(buffer.lock().unwrap().clone()).unwrap()
}
#[test]
fn json_output_is_versioned_json_lines() {
let (reporter, stdout, stderr) = reporter(true, false, TerminalCapabilities::default());
reporter.begin("build", false);
reporter.completed("build", true);
let output = text(&stdout);
let event: Value = serde_json::from_str(output.trim()).unwrap();
assert_eq!(event["schema_version"], 1);
assert_eq!(event["event"], "completed");
assert_eq!(event["dry_run"], true);
assert!(text(&stderr).is_empty());
}
#[test]
fn quiet_json_omits_chatty_child_output() {
let (reporter, stdout, _) = reporter(true, true, TerminalCapabilities::default());
reporter.command_output("native", "stderr", "compiling");
reporter.completed("build", false);
let output = text(&stdout);
assert_eq!(output.lines().count(), 1);
assert!(output.contains("\"event\":\"completed\""));
}
#[test]
fn human_output_has_a_compact_status_hierarchy() {
let (reporter, stdout, stderr) = reporter(false, false, TerminalCapabilities::default());
let mut command = CommandSpec::new("types", "cargo", PathBuf::from("."));
command.arg("run").arg("--quiet");
reporter.begin("dev", false);
reporter.command_started(&command);
reporter.command_output("types", "stdout", "generated 3 bindings");
reporter.command_finished("types", 0, Duration::from_millis(54));
assert!(text(&stdout).is_empty());
assert_eq!(
text(&stderr),
" kayro dev\n ◇ types Generating TypeScript bindings\n types │ generated 3 bindings\n ✓ types Done 54ms\n"
);
}
#[test]
fn terminal_progress_uses_osc_9_4_and_clears_it() {
let (reporter, stdout, stderr) = reporter(
false,
false,
TerminalCapabilities {
stderr: StreamCapabilities {
color: false,
live: true,
},
stdout: StreamCapabilities {
color: false,
live: true,
},
},
);
reporter.compile_progress_started("native", Some(4));
reporter.compile_progress("native", 2, Some(4), Some("gpui"));
reporter.command_finished("native", 0, Duration::from_secs(1));
assert!(text(&stdout).is_empty());
let output = text(&stderr);
assert!(output.contains("\u{1b}]9;4;1;50\u{7}"));
assert!(output.contains("50%"));
assert!(output.contains("gpui"));
assert!(output.contains("\u{1b}]9;4;0;0\u{7}"));
}
#[test]
fn json_progress_is_structured_and_has_no_escape_codes() {
let (reporter, stdout, stderr) = reporter(
true,
false,
TerminalCapabilities {
stderr: StreamCapabilities {
color: true,
live: true,
},
stdout: StreamCapabilities {
color: true,
live: true,
},
},
);
reporter.compile_progress("native", 2, Some(4), Some("gpui"));
let output = text(&stdout);
let event: Value = serde_json::from_str(output.trim()).unwrap();
assert_eq!(event["event"], "compile_progress");
assert_eq!(event["percent"], 50);
assert_eq!(event["package"], "gpui");
assert!(!output.contains('\u{1b}'));
assert!(text(&stderr).is_empty());
}
}