refactor(session): improve CLI error rendering and extract TaskErrorHints

crates/vite_task/src/lib.rs

@@ -5,7 +5,9 @@ pub mod session;
 
 // Public exports for vite_task_bin
 pub use cli::{CacheSubcommand, Command, RunCommand, RunFlags};
-pub use session::{CommandHandler, ExitStatus, HandledCommand, Session, SessionConfig};
+pub use session::{
+ CommandHandler, ExitStatus, HandledCommand, Session, SessionConfig, TaskErrorHints,
+};
 pub use vite_task_graph::{
  config::{
  self,

crates/vite_task/src/session/mod.rs

@@ -4,12 +4,18 @@ mod execute;
 pub(crate) mod reporter;
 
 // Re-export types that are part of the public API
-use std::{ffi::OsStr, fmt::Debug, io::IsTerminal, sync::Arc};
+use std::{
+ ffi::OsStr,
+ fmt::Debug,
+ io::{IsTerminal, Write as _},
+ sync::Arc,
+};
 
 use cache::ExecutionCache;
 pub use cache::{CacheMiss, FingerprintMismatch};
 use clap::Parser as _;
 use once_cell::sync::OnceCell;
+use owo_colors::{OwoColorize as _, Stream, Style};
 pub use reporter::ExitStatus;
 use reporter::{
  GroupedReporterBuilder, InterleavedReporterBuilder, LabeledReporterBuilder,
@@ -80,6 +86,11 @@ impl TaskGraphLoader for LazyTaskGraph<'_> {
  }
 }
 
+pub struct TaskErrorHints {
+ pub task_list_hint: Str,
+ pub task_source_hint: Str,
+}
+
 pub struct SessionConfig<'a> {
  pub command_handler: &'a mut (dyn CommandHandler + 'a),
  pub user_config_loader: &'a mut (dyn UserConfigLoader + 'a),
@@ -110,6 +121,9 @@ pub trait CommandHandler: Debug {
  &mut self,
  command: &mut ScriptCommand,
  ) -> anyhow::Result<HandledCommand>;
+
+ /// Returns hints shown to the user when a task is not found.
+ fn task_error_hints(&self) -> TaskErrorHints;
 }
 
 #[derive(derive_more::Debug)]
@@ -165,6 +179,7 @@ pub struct Session<'a> {
  plan_request_parser: PlanRequestParser<'a>,
 
  program_name: Str,
+ task_error_hints: TaskErrorHints,
 
  /// Cache is lazily initialized to avoid `SQLite` race conditions when multiple
  /// processes (e.g., parallel `vt lib` commands) start simultaneously.
@@ -227,6 +242,7 @@ impl<'a> Session<'a> {
  prepend_path_env(&mut envs, &workspace_node_modules_bin)?;
 
  // Cache is lazily initialized on first access to avoid SQLite race conditions
+ let task_error_hints = config.command_handler.task_error_hints();
  Ok(Self {
  workspace_path: Arc::clone(&workspace_root.path),
  lazy_task_graph: LazyTaskGraph::Uninitialized {
@@ -237,6 +253,7 @@ impl<'a> Session<'a> {
  cwd,
  plan_request_parser: PlanRequestParser { command_handler: config.command_handler },
  program_name: config.program_name,
+ task_error_hints,
  cache: OnceCell::new(),
  cache_path,
  })
@@ -246,13 +263,17 @@ impl<'a> Session<'a> {
  ///
  /// # Errors
  ///
- /// Returns an error if planning or execution fails.
+ /// Prints user-facing CLI errors and returns an exit status.
  #[tracing::instrument(level = "debug", skip_all)]
- pub async fn main(mut self, command: Command) -> anyhow::Result<ExitStatus> {
+ pub async fn main(mut self, command: Command) -> ExitStatus {
+ let verbose = matches!(&command, Command::Run(run) if run.flags.verbose);
  match self.main_inner(command).await {
- Ok(()) => Ok(ExitStatus::SUCCESS),
- Err(SessionError::EarlyExit(status)) => Ok(status),
- Err(SessionError::Anyhow(err)) => Err(err),
+ Ok(()) => ExitStatus::SUCCESS,
+ Err(SessionError::EarlyExit(status)) => status,
+ Err(SessionError::Anyhow(err)) => {
+ self.print_cli_error(&err, verbose);
+ ExitStatus::FAILURE
+ }
  }
  }
 
@@ -383,6 +404,87 @@ impl<'a> Session<'a> {
  Ok(())
  }
 
+ fn print_cli_error(&self, err: &anyhow::Error, verbose: bool) {
+ let mut stderr = std::io::stderr();
+
+ if let Some(plan_error) = err.downcast_ref::<vite_task_plan::Error>() {
+ if let Some(nested) = plan_error.nested_missing_task() {
+ let _ = writeln!(
+ stderr,
+ "{}",
+ vite_str::format!("Task \"{}\" not found.", nested.task_name)
+ .if_supports_color(Stream::Stderr, |text| {
+ text.style(Style::new().red().bold())
+ })
+ );
+ let _ = writeln!(
+ stderr,
+ "{} depends on \"{}\" via `{}`.",
+ nested.parent_task, nested.task_name, nested.command
+ );
+ let _ = writeln!(stderr, "Next steps:");
+ let _ = writeln!(stderr, " {}", self.task_error_hints.task_list_hint);
+ let _ = writeln!(stderr, " {}", self.task_error_hints.task_source_hint);
+ if verbose {
+ let _ = writeln!(stderr);
+ let _ = writeln!(
+ stderr,
+ "{}",
+ "Raw details:".if_supports_color(Stream::Stderr, |text| text.bold())
+ );
+ let _ = writeln!(stderr, "{err:#}");
+ let _ = writeln!(stderr, "Exit code: {}", ExitStatus::FAILURE.0);
+ }
+ let _ = stderr.flush();
+ return;
+ }
+
+ if let vite_task_plan::Error::NoTasksMatched(task_name) = plan_error {
+ let _ = writeln!(
+ stderr,
+ "{}",
+ vite_str::format!("Task \"{}\" not found.", task_name)
+ .if_supports_color(Stream::Stderr, |text| text
+ .style(Style::new().red().bold()))
+ );
+ let _ = writeln!(stderr, "Next steps:");
+ let _ = writeln!(stderr, " {}", self.task_error_hints.task_list_hint);
+ let _ = writeln!(stderr, " {}", self.task_error_hints.task_source_hint);
+ if verbose {
+ let _ = writeln!(stderr);
+ let _ = writeln!(
+ stderr,
+ "{}",
+ "Raw details:".if_supports_color(Stream::Stderr, |text| text.bold())
+ );
+ let _ = writeln!(stderr, "{err:#}");
+ let _ = writeln!(stderr, "Exit code: {}", ExitStatus::FAILURE.0);
+ }
+ let _ = stderr.flush();
+ return;
+ }
+ }
+
+ let _ = writeln!(
+ stderr,
+ "{} {}",
+ "✗".if_supports_color(Stream::Stderr, |text| text.style(Style::new().red().bold())),
+ err.to_string()
+ .if_supports_color(Stream::Stderr, |text| text.style(Style::new().red()))
+ );
+ if verbose {
+ let _ = writeln!(stderr);
+ let _ = writeln!(
+ stderr,
+ "{}",
+ "Raw details:".if_supports_color(Stream::Stderr, |text| text.bold())
+ );
+ let _ = writeln!(stderr, "{err:#}");
+ let _ = writeln!(stderr, "Exit code: {}", ExitStatus::FAILURE.0);
+ }
+ let _ = stderr.flush();
+ }
+
  /// Show the task selector or list, and return a plan request for the selected task.
  ///
  /// In interactive mode, shows a fuzzy-searchable selection list. On selection,

crates/vite_task_bin/src/lib.rs

@@ -9,8 +9,8 @@ use clap::Parser;
 use vite_path::AbsolutePath;
 use vite_str::Str;
 use vite_task::{
- Command, EnabledCacheConfig, HandledCommand, ScriptCommand, SessionConfig, UserCacheConfig,
- get_path_env, plan_request::SyntheticPlanRequest,
+ Command, EnabledCacheConfig, HandledCommand, ScriptCommand, SessionConfig, TaskErrorHints,
+UserCacheConfig, get_path_env, plan_request::SyntheticPlanRequest,
 };
 
 #[derive(Debug, Default)]
@@ -105,6 +105,15 @@ impl vite_task::CommandHandler for CommandHandler {
  Args::Task(parsed) => Ok(HandledCommand::ViteTaskCommand(parsed)),
  }
  }
+
+ fn task_error_hints(&self) -> TaskErrorHints {
+ TaskErrorHints {
+ task_list_hint: Str::from("Run `vt run` to browse available tasks."),
+ task_source_hint: Str::from(
+ "Check `vite-task.json` and `package.json` scripts where tasks are defined.",
+ ),
+ }
+ }
 }
 
 /// A `UserConfigLoader` implementation that only loads `vite-task.json`.

crates/vite_task_bin/src/main.rs

@@ -22,5 +22,5 @@ async fn run() -> anyhow::Result<ExitStatus> {
  let args = Command::parse();
  let mut owned_config = OwnedSessionConfig::default();
  let session = Session::init(owned_config.as_config())?;
- session.main(args).await
+Ok(session.main(args).await)
 }

crates/vite_task_bin/tests/e2e_snapshots/fixtures/error_cycle_dependency/snapshots/cycle dependency error.snap

@@ -3,4 +3,4 @@ source: crates/vite_task_bin/tests/e2e_snapshots/main.rs
 expression: e2e_outputs
 ---
 [1]> vt run task-a # task-a -> task-b -> task-a cycle
-Error: Cycle dependency detected: error-cycle-dependency-test#task-a -> error-cycle-dependency-test#task-b -> error-cycle-dependency-test#task-a
+✗ Cycle dependency detected: error-cycle-dependency-test#task-a -> error-cycle-dependency-test#task-b -> error-cycle-dependency-test#task-a

crates/vite_task_bin/tests/e2e_snapshots/fixtures/nested-task-not-found/package.json

@@ -0,0 +1,5 @@
+{
+ "name": "nested-task-not-found-test",
+ "private": true,
+ "workspaces": []
+}

crates/vite_task_bin/tests/e2e_snapshots/fixtures/nested-task-not-found/snapshots.toml

@@ -0,0 +1,7 @@
+[[e2e]]
+name = "nested task not found"
+steps = [["vt", "run", "repro"]]
+
+[[e2e]]
+name = "nested task not found verbose"
+steps = [["vt", "run", "repro", "--verbose"]]

crates/vite_task_bin/tests/e2e_snapshots/fixtures/nested-task-not-found/snapshots/nested task not found verbose.snap

@@ -0,0 +1,10 @@
+---
+source: crates/vite_task_bin/tests/e2e_snapshots/main.rs
+expression: e2e_outputs
+---
+[1]> vt run repro --verbose
+Task "missing-task" not found.
+nested-task-not-found-test#repro depends on "missing-task" via `vt run missing-task`.
+Next steps:
+ Run `vt run` to browse available tasks.
+ Check `vite-task.json` and `package.json` scripts where tasks are defined.

crates/vite_task_bin/tests/e2e_snapshots/fixtures/nested-task-not-found/snapshots/nested task not found.snap

@@ -0,0 +1,10 @@
+---
+source: crates/vite_task_bin/tests/e2e_snapshots/main.rs
+expression: e2e_outputs
+---
+[1]> vt run repro
+Task "missing-task" not found.
+nested-task-not-found-test#repro depends on "missing-task" via `vt run missing-task`.
+Next steps:
+ Run `vt run` to browse available tasks.
+ Check `vite-task.json` and `package.json` scripts where tasks are defined.

crates/vite_task_bin/tests/e2e_snapshots/fixtures/nested-task-not-found/vite-task.json

@@ -0,0 +1,7 @@
+{
+ "tasks": {
+ "repro": {
+ "command": "vt run missing-task"
+ }
+ }
+}

crates/vite_task_bin/tests/e2e_snapshots/fixtures/task-select/snapshots/non-interactive recursive typo errors.snap

@@ -3,4 +3,7 @@ source: crates/vite_task_bin/tests/e2e_snapshots/main.rs
 expression: e2e_outputs
 ---
 [1]> vtt pipe-stdin -- vt run -r buid
-Error: Task "buid" not found
+Task "buid" not found.
+Next steps:
+ Run `vt run` to browse available tasks.
+ Check `vite-task.json` and `package.json` scripts where tasks are defined.

crates/vite_task_bin/tests/e2e_snapshots/fixtures/task-select/snapshots/recursive without task errors.snap

@@ -5,4 +5,4 @@ info:
  cwd: packages/app
 ---
 [1]> vt run -r
-Error: No task specifier provided for 'run' command
+✗ No task specifier provided for 'run' command

crates/vite_task_bin/tests/e2e_snapshots/fixtures/task-select/snapshots/transitive typo errors.snap

@@ -5,4 +5,7 @@ info:
  cwd: packages/app
 ---
 [1]> vt run -t buid
-Error: Task "buid" not found
+Task "buid" not found.
+Next steps:
+ Run `vt run` to browse available tasks.
+ Check `vite-task.json` and `package.json` scripts where tasks are defined.

crates/vite_task_bin/tests/e2e_snapshots/fixtures/task-select/snapshots/typo in task script fails without list.snap

@@ -3,7 +3,8 @@ source: crates/vite_task_bin/tests/e2e_snapshots/main.rs
 expression: e2e_outputs
 ---
 [1]> vt run run-typo-task
-Error: Failed to plan tasks from `vt run nonexistent-xyz` in task task-select-test#run-typo-task
-
-Caused by:
- Task "nonexistent-xyz" not found
+Task "nonexistent-xyz" not found.
+task-select-test#run-typo-task depends on "nonexistent-xyz" via `vt run nonexistent-xyz`.
+Next steps:
+ Run `vt run` to browse available tasks.
+ Check `vite-task.json` and `package.json` scripts where tasks are defined.

crates/vite_task_bin/tests/e2e_snapshots/fixtures/task-select/snapshots/verbose without task errors.snap

@@ -5,4 +5,8 @@ info:
  cwd: packages/app
 ---
 [1]> vt run --verbose
-Error: No task specifier provided for 'run' command
+✗ No task specifier provided for 'run' command
+
+Raw details:
+No task specifier provided for 'run' command
+Exit code: 1

crates/vite_task_plan/src/error.rs

@@ -11,6 +11,13 @@ use vite_task_graph::display::TaskDisplay;
 
 use crate::{context::TaskRecursionError, envs::ResolveEnvError};
 
+#[derive(Debug, Clone)]
+pub struct NestedMissingTaskError<'a> {
+ pub parent_task: &'a TaskDisplay,
+ pub command: &'a Str,
+ pub task_name: &'a Str,
+}
+
 #[derive(Debug, thiserror::Error)]
 pub enum CdCommandError {
  #[error("No home directory found for 'cd' command with no arguments")]
@@ -165,3 +172,18 @@ pub enum Error {
  #[error("Cycle dependency detected: {}", _0.iter().map(std::string::ToString::to_string).collect::<Vec<_>>().join(" -> "))]
  CycleDependencyDetected(Vec<TaskDisplay>),
 }
+
+impl Error {
+ #[must_use]
+ pub fn nested_missing_task(&self) -> Option<NestedMissingTaskError<'_>> {
+ match self {
+ Self::NestPlan { task_display, command, error } => match error.as_ref() {
+ Self::NoTasksMatched(task_name) => {
+ Some(NestedMissingTaskError { parent_task: task_display, command, task_name })
+ }
+ inner => inner.nested_missing_task(),
+ },
+ _ => None,
+ }
+ }
+}