@litmers/cursorflow-orchestrator 0.1.18 → 0.1.26

package/src/cli/run.ts

@@ -9,6 +9,7 @@ import { orchestrate } from '../core/orchestrator';
 import { getLogsDir, loadConfig } from '../utils/config';
 import { runDoctor, getDoctorStatus } from '../utils/doctor';
 import { areCommandsInstalled, setupCommands } from './setup-commands';
+import { safeJoin } from '../utils/path';
 
 interface RunOptions {
   tasksDir?: string;
@@ -17,6 +18,7 @@ interface RunOptions {
   maxConcurrent: number | null;
   skipDoctor: boolean;
   noGit: boolean;
+  raw: boolean;
   help: boolean;
 }
 
@@ -32,6 +34,7 @@ Options:
   --executor <type>      cursor-agent | cloud
   --skip-doctor          Skip environment checks (not recommended)
   --no-git               Disable Git operations (worktree, push, commit)
+  --raw                  Save raw logs (absolute raw, no processing)
   --dry-run              Show execution plan without starting agents
   --help, -h             Show help
 
@@ -53,6 +56,7 @@ function parseArgs(args: string[]): RunOptions {
     maxConcurrent: maxConcurrentIdx >= 0 ? parseInt(args[maxConcurrentIdx + 1] || '0') || null : null,
     skipDoctor: args.includes('--skip-doctor') || args.includes('--no-doctor'),
     noGit: args.includes('--no-git'),
+    raw: args.includes('--raw'),
     help: args.includes('--help') || args.includes('-h'),
   };
 }
@@ -90,8 +94,8 @@ async function run(args: string[]): Promise<void> {
     path.isAbsolute(options.tasksDir)
       ? options.tasksDir
       : (fs.existsSync(options.tasksDir)
-        ? path.resolve(process.cwd(), options.tasksDir)
-        : path.join(config.projectRoot, options.tasksDir));
+        ? path.resolve(process.cwd(), options.tasksDir) // nosemgrep
+        : safeJoin(config.projectRoot, options.tasksDir));
 
   if (!fs.existsSync(tasksDir)) {
     throw new Error(`Tasks directory not found: ${tasksDir}`);
@@ -119,9 +123,9 @@ async function run(args: string[]): Promise<void> {
       for (const issue of report.issues) {
         const header = `${issue.title} (${issue.id})`;
         if (issue.severity === 'error') {
-          logger.error(header, '❌');
+          logger.error(header, { emoji: '❌' });
         } else {
-          logger.warn(header, '⚠️');
+          logger.warn(header, { emoji: '⚠️' });
         }
         console.log(`   ${issue.message}`);
         if (issue.details) console.log(`   Details: ${issue.details}`);
@@ -142,7 +146,10 @@ async function run(args: string[]): Promise<void> {
       runDir: path.join(logsDir, 'runs', `run-${Date.now()}`),
       maxConcurrentLanes: options.maxConcurrent || config.maxConcurrentLanes,
       webhooks: config.webhooks || [],
-      enhancedLogging: config.enhancedLogging,
+      enhancedLogging: {
+        ...config.enhancedLogging,
+        ...(options.raw ? { raw: true } : {}),
+      },
       noGit: options.noGit,
     });
   } catch (error: any) {

package/src/cli/runs.ts

@@ -0,0 +1,212 @@
+/**
+ * CursorFlow runs command - List and view run details
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import * as logger from '../utils/logger';
+import { loadConfig, getLogsDir } from '../utils/config';
+import { RunService } from '../utils/run-service';
+import { RunStatus, RunInfo } from '../utils/types';
+import { safeJoin } from '../utils/path';
+
+interface RunsOptions {
+  status?: RunStatus;
+  json: boolean;
+  help: boolean;
+  runId?: string;
+}
+
+function printHelp(): void {
+  console.log(`
+Usage: cursorflow runs [run-id] [options]
+
+List all runs or view details of a specific run.
+
+Options:
+  [run-id]               View details of a specific run
+  --running              Filter to show only running runs
+  --status <status>      Filter by status: running, completed, failed, partial, pending
+  --json                 Output in JSON format
+  --help, -h             Show help
+
+Examples:
+  cursorflow runs              # List all runs
+  cursorflow runs --running    # List only running runs
+  cursorflow runs run-123      # View details of run-123
+  `);
+}
+
+function parseArgs(args: string[]): RunsOptions {
+  const statusIdx = args.indexOf('--status');
+  const running = args.includes('--running');
+  
+  // Find run ID (first non-option argument)
+  const runId = args.find((arg, i) => {
+    if (arg.startsWith('--') || arg.startsWith('-')) return false;
+    // Skip values for options
+    const prevArg = args[i - 1];
+    if (prevArg && ['--status'].includes(prevArg)) {
+      return false;
+    }
+    return true;
+  });
+
+  return {
+    runId,
+    status: running ? 'running' : (statusIdx >= 0 ? args[statusIdx + 1] as RunStatus : undefined),
+    json: args.includes('--json'),
+    help: args.includes('--help') || args.includes('-h'),
+  };
+}
+
+/**
+ * Format duration in a human-readable way
+ */
+function formatDuration(ms: number): string {
+  if (ms < 1000) return `${ms}ms`;
+  const seconds = Math.floor(ms / 1000);
+  if (seconds < 60) return `${seconds}s`;
+  const minutes = Math.floor(seconds / 60);
+  const remainingSeconds = seconds % 60;
+  if (minutes < 60) return `${minutes}m ${remainingSeconds}s`;
+  const hours = Math.floor(minutes / 60);
+  const remainingMinutes = minutes % 60;
+  return `${hours}h ${remainingMinutes}m`;
+}
+
+/**
+ * Get status color and emoji
+ */
+function getStatusDisplay(status: RunStatus): string {
+  switch (status) {
+    case 'running':
+      return `${logger.COLORS.blue}🔄 running${logger.COLORS.reset}`;
+    case 'completed':
+      return `${logger.COLORS.green}✅ done   ${logger.COLORS.reset}`;
+    case 'failed':
+      return `${logger.COLORS.red}❌ failed ${logger.COLORS.reset}`;
+    case 'partial':
+      return `${logger.COLORS.yellow}⚠️ partial${logger.COLORS.reset}`;
+    case 'pending':
+      return `${logger.COLORS.gray}⏳ pending${logger.COLORS.reset}`;
+    default:
+      return status;
+  }
+}
+
+/**
+ * Display list of runs
+ */
+function displayRunList(runs: RunInfo[]): void {
+  if (runs.length === 0) {
+    console.log('No runs found.');
+    return;
+  }
+
+  console.log(`    Run ID              Task            Status     Lanes     Duration`);
+  console.log(`${logger.COLORS.cyan}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${logger.COLORS.reset}`);
+
+  for (const run of runs) {
+    const isRunning = run.status === 'running';
+    const prefix = isRunning ? `${logger.COLORS.blue}  ▶${logger.COLORS.reset}` : '   ';
+    
+    const id = run.id.padEnd(20);
+    const task = (run.taskName || 'unnamed').substring(0, 15).padEnd(15);
+    const status = getStatusDisplay(run.status);
+    
+    const completedLanes = run.lanes.filter(l => l.status === 'completed').length;
+    const totalLanes = run.lanes.length;
+    const lanes = `${completedLanes}/${totalLanes}`.padEnd(10);
+    
+    const duration = formatDuration(run.duration);
+    
+    console.log(`${prefix} ${id} ${task} ${status} ${lanes} ${duration}`);
+  }
+}
+
+/**
+ * Display detailed information for a single run
+ */
+function displayRunDetail(run: RunInfo): void {
+  logger.section(`Run Details: ${run.id}`);
+  
+  console.log(`${logger.COLORS.bold}Task:${logger.COLORS.reset}      ${run.taskName}`);
+  console.log(`${logger.COLORS.bold}Status:${logger.COLORS.reset}    ${getStatusDisplay(run.status)}`);
+  console.log(`${logger.COLORS.bold}Start Time:${logger.COLORS.reset} ${new Date(run.startTime).toLocaleString()}`);
+  console.log(`${logger.COLORS.bold}Duration:${logger.COLORS.reset}   ${formatDuration(run.duration)}`);
+  console.log(`${logger.COLORS.bold}Path:${logger.COLORS.reset}       ${run.path}`);
+  
+  console.log(`\n${logger.COLORS.bold}Lanes:${logger.COLORS.reset}`);
+  for (const lane of run.lanes) {
+    const statusColor = lane.status === 'completed' ? logger.COLORS.green : 
+                       lane.status === 'failed' ? logger.COLORS.red : 
+                       lane.status === 'running' ? logger.COLORS.blue : logger.COLORS.reset;
+    
+    console.log(`  - ${lane.name.padEnd(20)} [${statusColor}${lane.status.toUpperCase()}${logger.COLORS.reset}] Task ${lane.currentTask}/${lane.totalTasks} (PID: ${lane.pid || 'N/A'})`);
+  }
+  
+  if (run.branches.length > 0) {
+    console.log(`\n${logger.COLORS.bold}Branches:${logger.COLORS.reset}`);
+    for (const branch of run.branches) {
+      console.log(`  - ${branch}`);
+    }
+  }
+  
+  if (run.worktrees.length > 0) {
+    console.log(`\n${logger.COLORS.bold}Worktrees:${logger.COLORS.reset}`);
+    for (const wt of run.worktrees) {
+      console.log(`  - ${wt}`);
+    }
+  }
+  
+  console.log(`\nView logs: ${logger.COLORS.cyan}cursorflow logs ${run.id} --all${logger.COLORS.reset}`);
+}
+
+async function runs(args: string[]): Promise<void> {
+  const options = parseArgs(args);
+  
+  if (options.help) {
+    printHelp();
+    return;
+  }
+  
+  const config = loadConfig();
+  const logsDir = getLogsDir(config);
+  const runsDir = safeJoin(logsDir, 'runs');
+  
+  if (!fs.existsSync(runsDir)) {
+    if (options.json) {
+      console.log('[]');
+    } else {
+      console.log('No runs found. (Runs directory does not exist)');
+    }
+    return;
+  }
+  
+  const runService = new RunService(runsDir);
+  
+  if (options.runId) {
+    const run = runService.getRunInfo(options.runId);
+    if (!run) {
+      throw new Error(`Run not found: ${options.runId}`);
+    }
+    
+    if (options.json) {
+      console.log(JSON.stringify(run, null, 2));
+    } else {
+      displayRunDetail(run);
+    }
+    return;
+  }
+  
+  const runsList = runService.listRuns({ status: options.status });
+  
+  if (options.json) {
+    console.log(JSON.stringify(runsList, null, 2));
+  } else {
+    displayRunList(runsList);
+  }
+}
+
+export = runs;

package/src/cli/signal.ts

@@ -9,6 +9,7 @@ import * as fs from 'fs';
 import * as logger from '../utils/logger';
 import { loadConfig, getLogsDir } from '../utils/config';
 import { appendLog, createConversationEntry } from '../utils/state';
+import { safeJoin } from '../utils/path';
 
 interface SignalOptions {
   lane: string | null;
@@ -51,7 +52,7 @@ function parseArgs(args: string[]): SignalOptions {
 }
 
 function findLatestRunDir(logsDir: string): string | null {
-  const runsDir = path.join(logsDir, 'runs');
+  const runsDir = safeJoin(logsDir, 'runs');
   if (!fs.existsSync(runsDir)) return null;
   
   const runs = fs.readdirSync(runsDir)
@@ -59,7 +60,7 @@ function findLatestRunDir(logsDir: string): string | null {
     .sort()
     .reverse();
     
-  return runs.length > 0 ? path.join(runsDir, runs[0]!) : null;
+  return runs.length > 0 ? safeJoin(runsDir, runs[0]!) : null;
 }
 
 async function signal(args: string[]): Promise<void> {
@@ -86,14 +87,14 @@ async function signal(args: string[]): Promise<void> {
     throw new Error(`Run directory not found: ${runDir || 'latest'}`);
   }
 
-  const laneDir = path.join(runDir, 'lanes', options.lane);
+  const laneDir = safeJoin(runDir, 'lanes', options.lane);
   if (!fs.existsSync(laneDir)) {
     throw new Error(`Lane directory not found: ${laneDir}`);
   }
 
   // Case 1: Timeout update
   if (options.timeout !== null) {
-    const timeoutPath = path.join(laneDir, 'timeout.txt');
+    const timeoutPath = safeJoin(laneDir, 'timeout.txt');
     fs.writeFileSync(timeoutPath, String(options.timeout));
     logger.success(`Timeout update signal sent to ${options.lane}: ${options.timeout}ms`);
     return;
@@ -101,8 +102,8 @@ async function signal(args: string[]): Promise<void> {
 
   // Case 2: Intervention message
   if (options.message) {
-    const interventionPath = path.join(laneDir, 'intervention.txt');
-    const convoPath = path.join(laneDir, 'conversation.jsonl');
+    const interventionPath = safeJoin(laneDir, 'intervention.txt');
+    const convoPath = safeJoin(laneDir, 'conversation.jsonl');
     
     logger.info(`Sending signal to lane: ${options.lane}`);
     logger.info(`Message: "${options.message}"`);
@@ -111,7 +112,7 @@ async function signal(args: string[]): Promise<void> {
     fs.writeFileSync(interventionPath, options.message);
     
     // 2. Also append to conversation log for visibility and history
-    const entry = createConversationEntry('system', `[COMMANDER INTERVENTION]\n${options.message}`, {
+    const entry = createConversationEntry('intervention', `[HUMAN INTERVENTION]: ${options.message}`, {
       task: 'DIRECT_SIGNAL'
     });
     appendLog(convoPath, entry);

package/src/cli/stop.ts

@@ -0,0 +1,209 @@
+/**
+ * CursorFlow stop command - Stop running workflows or specific lanes
+ */
+
+import * as readline from 'readline';
+import * as logger from '../utils/logger';
+import { loadConfig, getLogsDir } from '../utils/config';
+import { RunService } from '../utils/run-service';
+import { ProcessManager } from '../utils/process-manager';
+import { safeJoin } from '../utils/path';
+
+interface StopOptions {
+  runId?: string;
+  lane?: string;
+  force: boolean;
+  yes: boolean;
+  help: boolean;
+}
+
+function printHelp(): void {
+  console.log(`
+Usage: cursorflow stop [run-id] [options]
+
+Stop running workflows or specific lanes.
+
+Options:
+  [run-id]               Stop a specific run
+  --lane <name>          Stop only a specific lane
+  --force                Use SIGKILL instead of SIGTERM
+  --yes, -y              Skip confirmation prompt
+  --help, -h             Show help
+
+Examples:
+  cursorflow stop              # Stop all running workflows
+  cursorflow stop run-123      # Stop run-123
+  cursorflow stop --lane api   # Stop only the 'api' lane in the latest run
+  cursorflow stop --force      # Force stop all workflows
+  `);
+}
+
+function parseArgs(args: string[]): StopOptions {
+  const laneIdx = args.indexOf('--lane');
+  
+  // Find run ID (first non-option argument)
+  const runId = args.find((arg, i) => {
+    if (arg.startsWith('--') || arg.startsWith('-')) return false;
+    // Skip values for options
+    const prevArg = args[i - 1];
+    if (prevArg && ['--lane'].includes(prevArg)) {
+      return false;
+    }
+    return true;
+  });
+
+  return {
+    runId,
+    lane: laneIdx >= 0 ? args[laneIdx + 1] : undefined,
+    force: args.includes('--force'),
+    yes: args.includes('--yes') || args.includes('-y'),
+    help: args.includes('--help') || args.includes('-h'),
+  };
+}
+
+/**
+ * Prompt user for confirmation
+ */
+async function confirm(message: string): Promise<boolean> {
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout,
+  });
+
+  return new Promise((resolve) => {
+    rl.question(`${message} [y/N]: `, (answer) => {
+      rl.close();
+      resolve(answer.toLowerCase() === 'y' || answer.toLowerCase() === 'yes');
+    });
+  });
+}
+
+async function stop(args: string[]): Promise<void> {
+  const options = parseArgs(args);
+  
+  if (options.help) {
+    printHelp();
+    return;
+  }
+  
+  const config = loadConfig();
+  const logsDir = getLogsDir(config);
+  const runsDir = safeJoin(logsDir, 'runs');
+  const runService = new RunService(runsDir);
+  
+  const signal = options.force ? 'SIGKILL' : 'SIGTERM';
+  
+  // Case 1: Stop specific lane in specific run (or latest if runId not provided)
+  if (options.lane) {
+    let runId = options.runId;
+    if (!runId) {
+      const activeRuns = runService.getActiveRuns();
+      if (activeRuns.length === 0) {
+        logger.info('No active runs found.');
+        return;
+      }
+      runId = activeRuns[0]!.id;
+    }
+    
+    const run = runService.getRunInfo(runId);
+    if (!run) {
+      throw new Error(`Run not found: ${runId}`);
+    }
+    
+    const lane = run.lanes.find(l => l.name === options.lane);
+    if (!lane) {
+      throw new Error(`Lane '${options.lane}' not found in run '${runId}'`);
+    }
+    
+    if (!lane.pid) {
+      logger.info(`Lane '${options.lane}' is not currently running (no PID).`);
+      return;
+    }
+    
+    if (!options.yes) {
+      const ok = await confirm(`⚠️  Stop lane '${options.lane}' in run '${runId}'?`);
+      if (!ok) return;
+    }
+    
+    logger.info(`🛑 Stopping lane '${options.lane}' (PID ${lane.pid})...`);
+    if (ProcessManager.killProcess(lane.pid, signal)) {
+      logger.success(`✓ lane '${options.lane}' stopped.`);
+    } else {
+      logger.error(`Failed to stop lane '${options.lane}'.`);
+    }
+    return;
+  }
+  
+  // Case 2: Stop specific run
+  if (options.runId) {
+    const run = runService.getRunInfo(options.runId);
+    if (!run) {
+      throw new Error(`Run not found: ${options.runId}`);
+    }
+    
+    if (run.status !== 'running') {
+      logger.info(`Run '${options.runId}' is not currently running (Status: ${run.status}).`);
+      return;
+    }
+    
+    if (!options.yes) {
+      const ok = await confirm(`⚠️  Stop run '${options.runId}' (${run.taskName})?`);
+      if (!ok) return;
+    }
+    
+    logger.info(`🛑 Stopping run '${options.runId}'...`);
+    let stoppedCount = 0;
+    for (const lane of run.lanes) {
+      if (lane.pid && ProcessManager.killProcess(lane.pid, signal)) {
+        logger.info(`  ✓ lane '${lane.name}' (PID ${lane.pid}) stopped`);
+        stoppedCount++;
+      }
+    }
+    
+    if (stoppedCount > 0) {
+      logger.success(`✅ Run '${options.runId}' stopped.`);
+    } else {
+      logger.info('No active lanes were stopped.');
+    }
+    return;
+  }
+  
+  // Case 3: Stop all running workflows
+  const activeRuns = runService.getActiveRuns();
+  if (activeRuns.length === 0) {
+    logger.info('No active runs found.');
+    return;
+  }
+  
+  if (!options.yes) {
+    console.log('\n⚠️  Stop all running workflows?\n');
+    console.log('Currently running:');
+    for (const run of activeRuns) {
+      const activeLanes = run.lanes.filter(l => l.pid).length;
+      console.log(`  - ${run.id} (${run.taskName}): ${activeLanes} lanes active`);
+    }
+    console.log('');
+    
+    const ok = await confirm('Continue?');
+    if (!ok) return;
+  }
+  
+  logger.info('🛑 Stopping all workflows...');
+  let totalStopped = 0;
+  for (const run of activeRuns) {
+    for (const lane of run.lanes) {
+      if (lane.pid && ProcessManager.killProcess(lane.pid, signal)) {
+        logger.info(`  ✓ lane '${lane.name}' (PID ${lane.pid}) stopped`);
+        totalStopped++;
+      }
+    }
+  }
+  
+  if (totalStopped > 0) {
+    logger.success(`\n✅ All workflows stopped (${totalStopped} lanes).`);
+  } else {
+    logger.info('\nNo active lanes were stopped.');
+  }
+}
+
+export = stop;

package/src/cli/tasks.ts

@@ -0,0 +1,154 @@
+/**
+ * CursorFlow tasks command
+ *
+ * Usage:
+ *   cursorflow tasks              # List all tasks
+ *   cursorflow tasks --validate   # List all tasks with validation
+ *   cursorflow tasks <name>       # Show detailed task info
+ */
+
+import * as logger from '../utils/logger';
+import { TaskService, TaskDirInfo, ValidationStatus } from '../utils/task-service';
+import { findProjectRoot, loadConfig, getTasksDir } from '../utils/config';
+
+const COLORS = logger.COLORS;
+
+interface TasksCliOptions {
+  validate: boolean;
+  taskName: string | null;
+}
+
+function printHelp(): void {
+  console.log(`
+Usage: cursorflow tasks [options] [task-name]
+
+Manage and view prepared tasks in _cursorflow/tasks/.
+
+Options:
+  --validate             Run validation on all tasks before listing
+  --help, -h             Show help
+
+Examples:
+  cursorflow tasks
+  cursorflow tasks --validate
+  cursorflow tasks 2412221530_AuthSystem
+  `);
+}
+
+function parseArgs(args: string[]): TasksCliOptions {
+  const options: TasksCliOptions = {
+    validate: args.includes('--validate'),
+    taskName: null,
+  };
+
+  const nameArg = args.find(arg => !arg.startsWith('-'));
+  if (nameArg) {
+    options.taskName = nameArg;
+  }
+
+  if (args.includes('--help') || args.includes('-h')) {
+    printHelp();
+    process.exit(0);
+  }
+
+  return options;
+}
+
+function formatDate(date: Date): string {
+  const months = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'];
+  return `${months[date.getMonth()]} ${date.getDate()}`;
+}
+
+function getStatusLabel(info: TaskDirInfo): string {
+  const status = info.validationStatus;
+  const icon = status === 'valid' ? '✅' : status === 'warnings' ? '⚠️' : status === 'errors' ? '❌' : '❓';
+  
+  if (status === 'valid') return `${icon} Valid`;
+  if (status === 'warnings') return `${icon} Warnings`;
+  if (status === 'errors') return `${icon} Errors`;
+  
+  return `${icon} Unknown`;
+}
+
+function printTasksList(tasks: TaskDirInfo[]): void {
+  if (tasks.length === 0) {
+    logger.info('No tasks found in _cursorflow/tasks/');
+    return;
+  }
+
+  console.log(`${COLORS.bold}Prepared Tasks:${COLORS.reset}`);
+  
+  for (let i = 0; i < tasks.length; i++) {
+    const task = tasks[i];
+    const prefix = i === 0 ? '  ▶' : '   ';
+    const name = task.name.padEnd(30);
+    const lanes = `${task.lanes.length} lane${task.lanes.length > 1 ? 's' : ''}`.padEnd(10);
+    const status = getStatusLabel(task).padEnd(14);
+    const date = formatDate(task.timestamp);
+    
+    let color = COLORS.reset;
+    if (task.validationStatus === 'errors') color = COLORS.red;
+    else if (task.validationStatus === 'warnings') color = COLORS.yellow;
+    else if (task.validationStatus === 'valid') color = COLORS.green;
+
+    console.log(`${color}${prefix} ${name} ${lanes} ${status} ${date}${COLORS.reset}`);
+  }
+}
+
+function printTaskDetail(info: TaskDirInfo): void {
+  console.log(`${COLORS.bold}Task: ${info.name}${COLORS.reset}`);
+  console.log(`${COLORS.cyan}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${COLORS.reset}`);
+  
+  if (info.lanes.length === 0) {
+    console.log('No lanes defined.');
+  } else {
+    console.log(`${COLORS.bold}Lanes:${COLORS.reset}`);
+    for (const lane of info.lanes) {
+      const fileName = lane.fileName.padEnd(18);
+      const preset = `[${lane.preset}]`.padEnd(10);
+      const flow = lane.taskFlow;
+      const depends = lane.dependsOn.length > 0 ? ` ${COLORS.gray}(depends: ${lane.dependsOn.join(', ')})${COLORS.reset}` : '';
+      
+      console.log(`  ${fileName} ${COLORS.blue}${preset}${COLORS.reset} ${flow}${depends}`);
+    }
+  }
+
+}
+
+async function tasks(args: string[]): Promise<void> {
+  const options = parseArgs(args);
+  const projectRoot = findProjectRoot();
+  const config = loadConfig(projectRoot);
+  const tasksDir = getTasksDir(config);
+  const taskService = new TaskService(tasksDir);
+
+  if (options.taskName) {
+    const info = taskService.getTaskDirInfo(options.taskName);
+    if (!info) {
+      logger.error(`Task not found: ${options.taskName}`);
+      process.exit(1);
+    }
+    
+    // Always validate for detail view to have report
+    taskService.validateTaskDir(options.taskName);
+    const updatedInfo = taskService.getTaskDirInfo(options.taskName)!;
+    
+    printTaskDetail(updatedInfo);
+  } else {
+    let taskList = taskService.listTaskDirs();
+    
+    if (options.validate) {
+      const spinner = logger.createSpinner('Validating tasks...');
+      spinner.start();
+      for (const task of taskList) {
+        taskService.validateTaskDir(task.name);
+      }
+      spinner.succeed('Validation complete');
+      taskList = taskService.listTaskDirs();
+    }
+    
+    printTasksList(taskList);
+  }
+}
+
+export = tasks;