refactor: simplify CLI and Session API by removing generic type parameters

Remove generic CustomSubcommand type parameter from Session, SessionCallbacks,
PlanRequestParser, and TaskSynthesizer. The CLI only supports `run` as a
top-level subcommand; synthetic tasks (lint, test, env-test) are now handled
purely by TaskSynthesizer via string matching on program name and args.

Key changes:
- TaskSynthesizer trait takes (program, args) directly instead of a typed subcommand
- Session/SessionCallbacks/PlanRequestParser no longer parameterized by subcommand type
- plan_from_cli accepts BuiltInCommand directly (removed CLIArgs, TaskCLIArgs, ParsedTaskCLIArgs)
- Binary crate owns its top-level Cli parser wrapping BuiltInCommand
- E2E test fixtures converted from `vite lint`/`vite env-test` to `vite run <task>`
- Removed same-name-as-builtin fixture (tested now-removed CLI lint vs run distinction)
- Added diagnostic block sorting in E2E output redaction for deterministic snapshots

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Author: branchseer

Cargo.lock

@@ -611,10 +611,10 @@ CommandFingerprint {
 }
 ```
 
-### Example: Built-in Task Cache Key
+### Example: Synthetic Task Cache Key
 
 ```rust
-// Built-in task: vite lint
+// Synthetic task (e.g., "vite lint" in a task script)
 TaskRunKey {
     task_id: TaskId {
         task_group_id: TaskGroupId {
@@ -830,20 +830,20 @@ Cache hit, replaying
 b
 ```
 
-### Example 3: Built-in Task Caching by Working Directory
+### Example 3: Task Caching by Working Directory
 
 ```bash
-# Different directories create separate caches for built-in tasks
-> cd folder1 && vite lint
+# Different directories create separate caches for tasks
+> cd folder1 && vite run lint
 Cache not found
 Found 0 warnings and 0 errors.
 
-> cd folder2 && vite lint
+> cd folder2 && vite run lint
 Cache not found  # Different cwd = different cache
 Found 0 warnings and 0 errors.
 
 # Each directory maintains its own cache
-> cd folder1 && vite lint
+> cd folder1 && vite run lint
 Cache hit, replaying
 Found 0 warnings and 0 errors.
 ```

crates/vite_task/docs/task-cache.md

@@ -1,90 +1,14 @@
-use std::{ffi::OsStr, sync::Arc};
+use std::sync::Arc;
 
-use clap::{Parser, Subcommand};
+use clap::Subcommand;
 use vite_path::AbsolutePath;
 use vite_str::Str;
 use vite_task_graph::{TaskSpecifier, query::TaskQueryKind};
 use vite_task_plan::plan_request::{PlanOptions, PlanRequest, QueryPlanRequest};
 
-/// Represents the CLI arguments handled by vite-task, including both built-in (like run) and custom subcommands (like lint).
-#[derive(Debug)]
-pub struct TaskCLIArgs<CustomSubcommand: Subcommand> {
-    pub(crate) original: Arc<[Str]>,
-    pub(crate) parsed: ParsedTaskCLIArgs<CustomSubcommand>,
-}
-
-impl<CustomSubcommand: Subcommand> TaskCLIArgs<CustomSubcommand> {
-    /// Inspect the custom subcommand (like lint/install). Returns `None` if it's built-in subcommand
-    /// The caller should not use this method to actually handle the custom subcommand. Instead, it should
-    /// private TaskSynthesizer to Session so that vite-task can handle custom subcommands consistently from
-    /// both direct CLI invocations and invocations in task scripts.
-    ///
-    /// This method is provided only to make it possible for the caller to behave differently BEFORE and AFTER the session.
-    /// For example, vite+ needs this method to skip auto-install when the custom subcommand is already `install`.
-    pub fn custom_subcommand(&self) -> Option<&CustomSubcommand> {
-        match &self.parsed {
-            ParsedTaskCLIArgs::BuiltIn(_) => None,
-            ParsedTaskCLIArgs::Custom(custom) => Some(custom),
-        }
-    }
-}
-
-/// Represents the overall CLI arguments, containing three kinds of subcommands:
-/// 1. Built-in subcommands handled by vite-task (like run)
-/// 2. Custom subcommands handled by vite-task with the help of TaskSyntheizer (like lint)
-/// 3. Custom subcommands not handled by vite-task (like vite+ commands without cache)
-pub enum CLIArgs<CustomSubcommand: Subcommand, NonTaskSubcommand: Subcommand> {
-    /// Subcommands handled by vite task, including built-in (like run) and custom (like lint)
-    Task(TaskCLIArgs<CustomSubcommand>),
-    /// Custom subcommands not handled by vite task (like vite+ commands without cache)
-    NonTask(NonTaskSubcommand),
-}
-
-impl<CustomSubcommand: Subcommand, NonTaskSubcommand: Subcommand>
-    CLIArgs<CustomSubcommand, NonTaskSubcommand>
-{
-    /// Get the original CLI arguments
-    pub fn try_parse_from(
-        args: impl Iterator<Item = impl AsRef<str>>,
-    ) -> Result<Self, clap::Error> {
-        #[derive(Debug, clap::Parser)]
-        enum ParsedCLIArgs<CustomSubcommand: Subcommand, NonTaskSubcommand: Subcommand> {
-            /// subcommands handled by vite task
-            #[command(flatten)]
-            Task(ParsedTaskCLIArgs<CustomSubcommand>),
-
-            /// subcommands that are not handled by vite task
-            #[command(flatten)]
-            NonTask(NonTaskSubcommand),
-        }
-
-        let args = args.map(|arg| Str::from(arg.as_ref())).collect::<Arc<[Str]>>();
-        let parsed_cli_args = ParsedCLIArgs::<CustomSubcommand, NonTaskSubcommand>::try_parse_from(
-            args.iter().map(|s| OsStr::new(s.as_str())),
-        )?;
-
-        Ok(match parsed_cli_args {
-            ParsedCLIArgs::Task(parsed_task_cli_args) => {
-                Self::Task(TaskCLIArgs { original: args, parsed: parsed_task_cli_args })
-            }
-            ParsedCLIArgs::NonTask(non_task_subcommand) => Self::NonTask(non_task_subcommand),
-        })
-    }
-}
-
-#[derive(Debug, Parser)]
-pub(crate) enum ParsedTaskCLIArgs<CustomSubcommand: Subcommand> {
-    /// subcommands provided by vite task, like `run`
-    #[clap(flatten)]
-    BuiltIn(BuiltInCommand),
-    /// custom subcommands provided by vite+, like `lint`
-    #[clap(flatten)]
-    Custom(CustomSubcommand),
-}
-
 /// vite task CLI subcommands
 #[derive(Debug, Subcommand)]
-pub(crate) enum BuiltInCommand {
+pub enum BuiltInCommand {
     /// Run tasks
     Run {
         /// `packageName#taskName` or `taskName`.
@@ -118,7 +42,7 @@ pub enum CLITaskQueryError {
 }
 
 impl BuiltInCommand {
-    /// Convert to `TaskQuery`, or return an error if invalid.
+    /// Convert to `PlanRequest`, or return an error if invalid.
     pub fn into_plan_request(
         self,
         cwd: &Arc<AbsolutePath>,

crates/vite_task/src/cli/mod.rs

@@ -4,7 +4,7 @@ mod maybe_str;
 pub mod session;
 
 // Public exports for vite_task_bin
-pub use cli::CLIArgs;
+pub use cli::BuiltInCommand;
 pub use session::{LabeledReporter, Reporter, Session, SessionCallbacks, TaskSynthesizer};
 pub use vite_task_graph::{
     config::{

crates/vite_task/src/lib.rs

@@ -348,7 +348,7 @@ impl ExecutionContext<'_> {
     }
 }
 
-impl<'a, CustomSubcommand> Session<'a, CustomSubcommand> {
+impl<'a> Session<'a> {
     /// Execute an execution plan, reporting events to the provided reporter.
     ///
     /// Returns Err(ExitStatus) to suggest the caller to abort and exit the process with the given exit status.

crates/vite_task/src/session/execute/mod.rs

@@ -8,7 +8,7 @@ use std::{ffi::OsStr, fmt::Debug, sync::Arc};
 
 use cache::ExecutionCache;
 pub use cache::{CacheMiss, FingerprintMismatch};
-use clap::{Parser, Subcommand};
+use clap::Parser;
 pub use event::ExecutionEvent;
 use once_cell::sync::OnceCell;
 pub use reporter::{LabeledReporter, Reporter};
@@ -22,10 +22,7 @@ use vite_task_plan::{
 };
 use vite_workspace::{WorkspaceRoot, find_workspace_root};
 
-use crate::{
-    cli::{ParsedTaskCLIArgs, TaskCLIArgs},
-    collections::HashMap,
-};
+use crate::{cli::BuiltInCommand, collections::HashMap};
 
 #[derive(Debug)]
 enum LazyTaskGraph<'a> {
@@ -52,87 +49,76 @@ impl TaskGraphLoader for LazyTaskGraph<'_> {
     }
 }
 
-pub struct SessionCallbacks<'a, CustomSubcommand> {
-    pub task_synthesizer: &'a mut (dyn TaskSynthesizer<CustomSubcommand> + 'a),
+pub struct SessionCallbacks<'a> {
+    pub task_synthesizer: &'a mut (dyn TaskSynthesizer + 'a),
     pub user_config_loader: &'a mut (dyn UserConfigLoader + 'a),
 }
 
+/// Handles synthesizing task plan requests from commands found in task scripts.
+///
+/// When a task's command references a known program (e.g., `vite lint` in a script),
+/// the synthesizer converts it into a `SyntheticPlanRequest` for execution.
 #[async_trait::async_trait(?Send)]
-pub trait TaskSynthesizer<CustomSubcommand>: Debug {
-    fn should_synthesize_for_program(&self, program: &str) -> bool;
-
-    /// Synthesize a synthetic task plan request for the given parsed custom subcommand.
+pub trait TaskSynthesizer: Debug {
+    /// Called for every command in task scripts to determine if it should be synthesized.
     ///
+    /// - `program` is the program name (e.g., `"vite"`).
+    /// - `args` is all arguments after the program (e.g., `["lint", "--fix"]`).
     /// - `envs` is the current environment variables where the task is being planned.
     /// - `cwd` is the current working directory where the task is being planned.
     ///
-    /// The implementor can return a different `envs` in `SyntheticPlanRequest` to customize
-    /// environment variables for the synthetic task.
+    /// Returns `Ok(Some(request))` if the command is recognized and should be synthesized,
+    /// `Ok(None)` if the command should be executed as a normal process.
     async fn synthesize_task(
         &mut self,
-        subcommand: CustomSubcommand,
+        program: &str,
+        args: &[Str],
         envs: &Arc<HashMap<Arc<OsStr>, Arc<OsStr>>>,
         cwd: &Arc<AbsolutePath>,
-    ) -> anyhow::Result<SyntheticPlanRequest>;
+    ) -> anyhow::Result<Option<SyntheticPlanRequest>>;
 }
 
 #[derive(derive_more::Debug)]
-#[debug(bound())] // Avoid requiring CustomSubcommand: Debug
-struct PlanRequestParser<'a, CustomSubcommand> {
-    task_synthesizer: &'a mut (dyn TaskSynthesizer<CustomSubcommand> + 'a),
-}
-
-impl<CustomSubcommand: clap::Subcommand> PlanRequestParser<'_, CustomSubcommand> {
-    async fn get_plan_request_from_cli_args(
-        &mut self,
-        cli_args: ParsedTaskCLIArgs<CustomSubcommand>,
-        envs: &Arc<HashMap<Arc<OsStr>, Arc<OsStr>>>,
-        cwd: &Arc<AbsolutePath>,
-    ) -> anyhow::Result<PlanRequest> {
-        match cli_args {
-            ParsedTaskCLIArgs::BuiltIn(vite_task_subcommand) => {
-                Ok(vite_task_subcommand.into_plan_request(cwd)?)
-            }
-            ParsedTaskCLIArgs::Custom(custom_subcommand) => {
-                let synthetic_plan_request =
-                    self.task_synthesizer.synthesize_task(custom_subcommand, envs, cwd).await?;
-                Ok(PlanRequest::Synthetic(synthetic_plan_request))
-            }
-        }
-    }
+struct PlanRequestParser<'a> {
+    task_synthesizer: &'a mut (dyn TaskSynthesizer + 'a),
 }
 
 #[async_trait::async_trait(?Send)]
-impl<CustomSubcommand: clap::Subcommand> vite_task_plan::PlanRequestParser
-    for PlanRequestParser<'_, CustomSubcommand>
-{
+impl vite_task_plan::PlanRequestParser for PlanRequestParser<'_> {
     async fn get_plan_request(
         &mut self,
         program: &str,
         args: &[Str],
         envs: &Arc<HashMap<Arc<OsStr>, Arc<OsStr>>>,
         cwd: &Arc<AbsolutePath>,
     ) -> anyhow::Result<Option<PlanRequest>> {
-        Ok(
-            if self.task_synthesizer.should_synthesize_for_program(program)
-                && let Some(subcommand) = args.first()
-                && ParsedTaskCLIArgs::<CustomSubcommand>::has_subcommand(subcommand)
-            {
-                let cli_args = ParsedTaskCLIArgs::<CustomSubcommand>::try_parse_from(
-                    std::iter::once(program).chain(args.iter().map(Str::as_str)),
-                )?;
-                Some(self.get_plan_request_from_cli_args(cli_args, envs, cwd).await?)
-            } else {
-                None
-            },
-        )
+        // Try task synthesizer first (handles e.g. "vite lint" in scripts)
+        if let Some(synthetic) =
+            self.task_synthesizer.synthesize_task(program, args, envs, cwd).await?
+        {
+            return Ok(Some(PlanRequest::Synthetic(synthetic)));
+        }
+
+        // Try built-in "run" command (handles "vite run build" in scripts)
+        #[derive(Parser)]
+        enum BuiltInParser {
+            #[clap(flatten)]
+            Command(BuiltInCommand),
+        }
+        if let Ok(BuiltInParser::Command(built_in)) = BuiltInParser::try_parse_from(
+            std::iter::once(program).chain(args.iter().map(Str::as_str)),
+        ) {
+            return Ok(Some(built_in.into_plan_request(cwd)?));
+        }
+
+        Ok(None)
     }
 }
 
 /// Represents a vite task session for planning and executing tasks. A process typically has one session.
 ///
 /// A session manages task graph loading internally and provides non-consuming methods to plan and/or execute tasks (allows multiple plans/executions per session).
-pub struct Session<'a, CustomSubcommand> {
+pub struct Session<'a> {
     workspace_path: Arc<AbsolutePath>,
     /// A session doesn't necessarily load the task graph immediately.
     /// The task graph is loaded on-demand and cached for future use.
@@ -141,7 +127,7 @@ pub struct Session<'a, CustomSubcommand> {
     envs: Arc<HashMap<Arc<OsStr>, Arc<OsStr>>>,
     cwd: Arc<AbsolutePath>,
 
-    plan_request_parser: PlanRequestParser<'a, CustomSubcommand>,
+    plan_request_parser: PlanRequestParser<'a>,
 
     /// Cache is lazily initialized to avoid SQLite race conditions when multiple
     /// processes (e.g., parallel `vite lib` commands) start simultaneously.
@@ -157,9 +143,9 @@ fn get_cache_path_of_workspace(workspace_root: &AbsolutePath) -> AbsolutePathBuf
     }
 }
 
-impl<'a, CustomSubcommand> Session<'a, CustomSubcommand> {
+impl<'a> Session<'a> {
     /// Initialize a session with real environment variables and cwd
-    pub fn init(callbacks: SessionCallbacks<'a, CustomSubcommand>) -> anyhow::Result<Self> {
+    pub fn init(callbacks: SessionCallbacks<'a>) -> anyhow::Result<Self> {
         let envs = std::env::vars_os()
             .map(|(k, v)| (Arc::<OsStr>::from(k.as_os_str()), Arc::<OsStr>::from(v.as_os_str())))
             .collect();
@@ -176,7 +162,7 @@ impl<'a, CustomSubcommand> Session<'a, CustomSubcommand> {
     pub fn init_with(
         mut envs: HashMap<Arc<OsStr>, Arc<OsStr>>,
         cwd: Arc<AbsolutePath>,
-        callbacks: SessionCallbacks<'a, CustomSubcommand>,
+        callbacks: SessionCallbacks<'a>,
     ) -> anyhow::Result<Self> {
         let (workspace_root, _) = find_workspace_root(&cwd)?;
         let cache_path = get_cache_path_of_workspace(&workspace_root.path);
@@ -217,9 +203,7 @@ impl<'a, CustomSubcommand> Session<'a, CustomSubcommand> {
             _ => None,
         }
     }
-}
 
-impl<'a, CustomSubcommand: clap::Subcommand> Session<'a, CustomSubcommand> {
     pub async fn plan_synthetic_task(
         &mut self,
         synthetic_plan_request: SyntheticPlanRequest,
@@ -239,21 +223,17 @@ impl<'a, CustomSubcommand: clap::Subcommand> Session<'a, CustomSubcommand> {
     pub async fn plan_from_cli(
         &mut self,
         cwd: Arc<AbsolutePath>,
-        cli_args: TaskCLIArgs<CustomSubcommand>,
+        command: BuiltInCommand,
     ) -> Result<ExecutionPlan, vite_task_plan::Error> {
-        let plan_request = self
-            .plan_request_parser
-            .get_plan_request_from_cli_args(cli_args.parsed, &self.envs, &cwd)
-            .await
-            .map_err(|error| {
-                TaskPlanErrorKind::ParsePlanRequestError {
-                    error,
-                    program: cli_args.original[0].clone(),
-                    args: cli_args.original.iter().skip(1).cloned().collect(),
-                    cwd: Arc::clone(&cwd),
-                }
-                .with_empty_call_stack()
-            })?;
+        let plan_request = command.into_plan_request(&cwd).map_err(|error| {
+            TaskPlanErrorKind::ParsePlanRequestError {
+                error: error.into(),
+                program: Str::from("vite"),
+                args: Default::default(),
+                cwd: Arc::clone(&cwd),
+            }
+            .with_empty_call_stack()
+        })?;
         let plan = ExecutionPlan::plan(
             plan_request,
             &self.workspace_path,