@synergenius/flow-weaver-pack-weaver 0.8.3 → 0.9.3

package/src/cli-handlers.ts

@@ -13,7 +13,7 @@ import type { ExecutionEvent, WeaverConfig, RunRecord, RunOutcome, RunCostSummar
 import { AuditStore } from './bot/audit-store.js';
 
 export interface ParsedArgs {
-  command: 'run' | 'history' | 'costs' | 'providers' | 'watch' | 'cron' | 'pipeline' | 'dashboard' | 'eject' | 'bot' | 'session' | 'steer' | 'queue' | 'genesis' | 'audit';
+  command: 'run' | 'history' | 'costs' | 'providers' | 'watch' | 'cron' | 'pipeline' | 'dashboard' | 'eject' | 'bot' | 'session' | 'steer' | 'queue' | 'status' | 'genesis' | 'audit' | 'init' | 'assistant' | 'examples' | 'doctor';
   file?: string;
   verbose: boolean;
   dryRun: boolean;
@@ -57,6 +57,16 @@ export interface ParsedArgs {
   genesisWatch: boolean;
   // eject
   ejectWorkflow?: string;
+  // session scheduling
+  sessionContinuous: boolean;
+  sessionUntil?: string;
+  sessionMaxTasks?: number;
+  sessionParallel?: number;
+  // assistant
+  assistantNew?: boolean;
+  assistantResume?: string;
+  assistantList?: boolean;
+  assistantDelete?: string;
 }
 
 export function parseArgs(argv: string[]): ParsedArgs {
@@ -81,6 +91,7 @@ export function parseArgs(argv: string[]): ParsedArgs {
     autoApprove: false,
     genesisInit: false,
     genesisWatch: false,
+    sessionContinuous: false,
   };
 
   const args = argv.slice(2);
@@ -192,6 +203,14 @@ export function parseArgs(argv: string[]): ParsedArgs {
       }
     } else if (arg === 'session') {
       result.command = 'session';
+    } else if (arg === 'assistant') {
+      result.command = 'assistant';
+    } else if (arg === 'examples') {
+      result.command = 'examples';
+    } else if (arg === 'doctor') {
+      result.command = 'doctor';
+    } else if (arg === 'status') {
+      result.command = 'status';
     } else if (arg === 'steer') {
       result.command = 'steer';
       // Next arg is the subcommand
@@ -236,10 +255,33 @@ export function parseArgs(argv: string[]): ParsedArgs {
       }
     } else if (arg === 'genesis') {
       result.command = 'genesis';
+    } else if (arg === 'init') {
+      result.command = 'init';
     } else if (arg === '--init') {
       result.genesisInit = true;
     } else if (arg === '--watch') {
       result.genesisWatch = true;
+    } else if (arg === '--new') {
+      result.assistantNew = true;
+    } else if (arg === '--resume' && i + 1 < args.length) {
+      i++;
+      result.assistantResume = args[i];
+    } else if (arg === '--list') {
+      result.assistantList = true;
+    } else if (arg === '--delete' && i + 1 < args.length) {
+      i++;
+      result.assistantDelete = args[i];
+    } else if (arg === '--continuous') {
+      result.sessionContinuous = true;
+    } else if (arg === '--until' && i + 1 < args.length) {
+      i++;
+      result.sessionUntil = args[i];
+    } else if (arg === '--max-tasks' && i + 1 < args.length) {
+      i++;
+      result.sessionMaxTasks = parseInt(args[i]!, 10) || undefined;
+    } else if (arg === '--parallel' && i + 1 < args.length) {
+      i++;
+      result.sessionParallel = Math.min(Math.max(parseInt(args[i]!, 10) || 1, 1), 5);
     } else if (arg === '--project-dir' && i + 1 < args.length) {
       i++;
       result.file = args[i];
@@ -337,6 +379,14 @@ function printRunDetail(r: RunRecord): void {
   if (r.params) {
     console.log(`  Params:         ${JSON.stringify(r.params)}`);
   }
+  if (r.stepLog && r.stepLog.length > 0) {
+    console.log(`\n  Steps (${r.stepLog.length}):`);
+    for (const entry of r.stepLog) {
+      const icon = entry.status === 'ok' ? '\x1b[32m+\x1b[0m' : entry.status === 'blocked' ? '\x1b[33m⚠\x1b[0m' : '\x1b[31m✗\x1b[0m';
+      const detail = entry.detail ? ` — ${entry.detail}` : '';
+      console.log(`    ${icon} ${entry.step}${detail}`);
+    }
+  }
   console.log('');
 }
 
@@ -448,11 +498,19 @@ export async function handleCosts(opts: ParsedArgs): Promise<void> {
   const summary = store.summarize({ since: sinceTs, model: opts.costsModel });
 
   if (summary.totalRuns === 0) {
-    console.log('No cost data found.');
+    if (opts.historyJson) {
+      console.log(JSON.stringify(summary, null, 2));
+    } else {
+      console.log('No cost data found.');
+    }
     return;
   }
 
-  console.log(formatCostTable(summary));
+  if (opts.historyJson) {
+    console.log(JSON.stringify(summary, null, 2));
+  } else {
+    console.log(formatCostTable(summary));
+  }
 }
 
 export async function handleWatch(opts: ParsedArgs): Promise<void> {
@@ -704,6 +762,7 @@ export async function handleProviders(): Promise<void> {
 
 const MANAGED_WORKFLOWS: Record<string, string> = {
   bot: 'weaver-bot',
+  agent: 'weaver-agent',
   batch: 'weaver-bot-batch',
   genesis: 'genesis-task',
 };
@@ -1211,36 +1270,324 @@ export async function handleBot(opts: ParsedArgs): Promise<void> {
 }
 
 export async function handleSession(opts: ParsedArgs): Promise<void> {
-  const workflowPath = resolveWorkflowPath('bot', opts.file ?? process.cwd());
-
+  const projectDir = opts.file ?? process.cwd();
+  // Set project dir for per-project queue isolation
+  process.env.WEAVER_PROJECT_DIR = projectDir;
   const config = await loadConfig(opts.configPath);
+  const workflowPath = resolveWorkflowPath('agent', projectDir);
+
+  // Create terminal renderer for all session output
+  const { TerminalRenderer } = await import('./bot/terminal-renderer.js');
+  const renderer = new TerminalRenderer({ verbose: opts.verbose, quiet: opts.quiet });
+
+  // Parse --until HH:MM into a deadline timestamp
+  let deadline: number | undefined;
+  let deadlineStr: string | undefined;
+  if (opts.sessionUntil) {
+    const match = opts.sessionUntil.match(/^(\d{1,2}):(\d{2})$/);
+    if (match) {
+      const now = new Date();
+      const target = new Date(now);
+      target.setHours(parseInt(match[1]!, 10), parseInt(match[2]!, 10), 0, 0);
+      if (target.getTime() <= now.getTime()) target.setDate(target.getDate() + 1);
+      deadline = target.getTime();
+      deadlineStr = target.toLocaleTimeString([], { hour: '2-digit', minute: '2-digit' });
+    }
+  }
 
-  if (!opts.quiet) {
-    console.log('[weaver] Starting bot session (Ctrl+C to stop)');
-    console.log('[weaver] Add tasks with: flow-weaver weaver queue add "task"');
+  const maxTasks = opts.sessionMaxTasks ?? Infinity;
+  const continuous = opts.sessionContinuous || !!opts.sessionUntil || maxTasks < Infinity;
+  const parallelism = opts.sessionParallel ?? 1;
+
+  // Crash recovery
+  if (continuous) {
+    const { TaskQueue } = await import('./bot/task-queue.js');
+    const recoveryQueue = new TaskQueue();
+    const recovered = await recoveryQueue.recoverOrphans();
+    if (recovered > 0) renderer.info(`Recovered ${recovered} orphaned task(s)`);
   }
 
+  // Clean stale cache files
   try {
-    const result = await runWorkflow(workflowPath, {
-      params: { projectDir: opts.file ?? process.cwd() },
-      verbose: opts.verbose,
-      dryRun: opts.dryRun,
-      config,
-    });
+    const { execSync: execSyncClean } = await import('node:child_process');
+    const staleOutput = execSyncClean(`find "${projectDir}" -name "fw-exec-*" -type f`, { encoding: 'utf-8', timeout: 5000 }).trim();
+    if (staleOutput) {
+      const staleFiles = staleOutput.split('\n').filter(Boolean);
+      for (const f of staleFiles) { try { fs.unlinkSync(f); } catch {} }
+    }
+  } catch { /* non-fatal */ }
 
-    if (!opts.quiet) {
-      const color = result.success ? '\x1b[32m' : '\x1b[31m';
-      console.log(`${color}Session: ${result.outcome}\x1b[0m`);
+  // Detect provider label for session start
+  const providerType = config?.provider ?? 'auto';
+  const providerLabel = typeof providerType === 'object' ? providerType.name : String(providerType);
+  const sessionStartTime = Date.now();
+  renderer.sessionStart({ provider: providerLabel, parallel: parallelism, deadline: deadlineStr });
+
+  // Single-run mode (backwards compatible)
+  if (!continuous) {
+    try {
+      const result = await runWorkflow(workflowPath, {
+        params: { projectDir },
+        verbose: opts.verbose,
+        dryRun: opts.dryRun,
+        config,
+      });
+      if (!opts.quiet) {
+        const color = result.success ? '\x1b[32m' : '\x1b[31m';
+        console.log(`${color}Session: ${result.outcome}\x1b[0m`);
+      }
+      process.exit(result.success ? 0 : 1);
+    } catch (err: unknown) {
+      const msg = err instanceof Error ? err.message : String(err);
+      console.error(`\x1b[31m[weaver] Fatal: ${msg}\x1b[0m`);
+      process.exit(1);
     }
+    return;
+  }
 
-    process.exit(result.success ? 0 : 1);
-  } catch (err: unknown) {
-    const msg = err instanceof Error ? err.message : String(err);
-    console.error(`\x1b[31m[weaver] Fatal: ${msg}\x1b[0m`);
-    process.exit(1);
+  // Continuous mode: loop until deadline/maxTasks/interrupt
+  const { TaskQueue } = await import('./bot/task-queue.js');
+  const { isTransientError } = await import('./bot/retry-utils.js');
+  const { getErrorGuidance } = await import('./bot/error-guide.js');
+  const queue = new TaskQueue();
+  let taskCount = 0;
+  let interrupted = false;
+  let consecutiveErrors = 0;
+  let consecutiveNoOps = 0;
+  const MAX_CONSECUTIVE_ERRORS = 3;
+  const MAX_CONSECUTIVE_NO_OPS = 5;
+
+  // Session stats
+  let sessionCompleted = 0, sessionFailed = 0, sessionNoOp = 0;
+  let sessionInputTokens = 0, sessionOutputTokens = 0, sessionCost = 0;
+
+  process.on('SIGINT', () => { interrupted = true; });
+  process.on('SIGTERM', () => { interrupted = true; });
+
+  // Parallel task tracking
+  const running = new Map<string, Promise<void>>();
+  const filesInUse = new Set<string>();
+
+  const processTask = async (task: { id: string; instruction?: string; targets?: string[] }) => {
+    try {
+      const result = await runWorkflow(workflowPath, {
+        params: { projectDir, taskJson: JSON.stringify(task) },
+        verbose: opts.verbose,
+        dryRun: opts.dryRun,
+        config,
+      });
+
+      // Classify outcome: the summary contains "no changes" or "0 files" for no-ops
+      const isNoOp = result.success && (
+        result.summary.includes('no changes') ||
+        result.summary.includes('0 file') ||
+        result.summary.includes("doesn't exist") ||
+        result.summary.includes('does not exist') ||
+        result.summary.includes('nothing to') ||
+        result.outcome === 'no-op'
+      );
+
+      if (isNoOp) {
+        await queue.markNoOp(task.id);
+        sessionNoOp++;
+        consecutiveNoOps++;
+        consecutiveErrors = 0;
+      } else if (result.success) {
+        await queue.markComplete(task.id);
+        sessionCompleted++;
+        consecutiveErrors = 0;
+        consecutiveNoOps = 0;
+      } else {
+        await queue.markFailed(task.id, result.summary || result.outcome || 'unknown error');
+        sessionFailed++;
+        consecutiveErrors++;
+        consecutiveNoOps = 0;
+      }
+
+      // Track cost from workflow result
+      if (result.cost) {
+        sessionInputTokens += result.cost.totalInputTokens ?? 0;
+        sessionOutputTokens += result.cost.totalOutputTokens ?? 0;
+        sessionCost += result.cost.totalCost ?? 0;
+      }
+
+    } catch (err: unknown) {
+      const msg = err instanceof Error ? err.message : String(err);
+      const guidance = getErrorGuidance(msg);
+      renderer.error(`Task ${task.id.slice(0, 8)} error`, guidance ? `${msg}\n  Hint: ${guidance}` : msg);
+      await queue.markFailed(task.id, msg);
+      sessionFailed++;
+      if (!isTransientError(err)) {
+        consecutiveErrors++;
+      }
+    } finally {
+      for (const f of task.targets ?? []) filesInUse.delete(f);
+      running.delete(task.id);
+    }
+  };
+
+  while (taskCount < maxTasks && !interrupted) {
+    if (deadline && Date.now() >= deadline) {
+      renderer.info('Deadline reached, stopping session.');
+      break;
+    }
+
+    if (consecutiveErrors >= MAX_CONSECUTIVE_ERRORS) {
+      renderer.error('Session stopped', `${MAX_CONSECUTIVE_ERRORS} consecutive errors — check your API key or provider config.`);
+      break;
+    }
+
+    // Pause on consecutive no-ops (bot is spinning without doing anything)
+    if (consecutiveNoOps >= MAX_CONSECUTIVE_NO_OPS) {
+      renderer.warn(`${MAX_CONSECUTIVE_NO_OPS} consecutive no-op tasks — pausing 60s`);
+      await new Promise(r => setTimeout(r, 60_000));
+      consecutiveNoOps = 0;
+    }
+
+    // Wait if at capacity
+    if (running.size >= parallelism) {
+      await Promise.race(running.values());
+      continue;
+    }
+
+    const task = await queue.next();
+    if (!task) {
+      if (running.size > 0) {
+        // Tasks still running — wait for one to finish
+        await Promise.race(running.values());
+        continue;
+      }
+      // No pending or running tasks — wait and retry
+      await new Promise(r => setTimeout(r, 5_000));
+      continue;
+    }
+
+    // Auto-decompose broad tasks into per-file tasks
+    const { decomposeTask } = await import('./bot/task-decomposer.js');
+    const { decomposed, tasks: subtasks } = decomposeTask(task, projectDir);
+    if (decomposed && subtasks.length > 1) {
+      // Replace the broad task with per-file tasks
+      await queue.markComplete(task.id);
+      let decomposedCount = 0;
+      for (const st of subtasks) {
+        const { duplicate } = await queue.add({ instruction: st.instruction, mode: st.mode as 'modify', targets: st.targets, priority: st.priority ?? 0 });
+        if (!duplicate) decomposedCount++;
+      }
+      renderer.info(`Decomposed into ${subtasks.length} per-file tasks`);
+      continue;
+    }
+
+    // File conflict check: if task targets overlap with files in use, wait
+    const taskTargets = task.targets ?? [];
+    const hasConflict = taskTargets.some(f => filesInUse.has(f));
+    if (hasConflict && running.size > 0) {
+      await Promise.race(running.values());
+      continue;
+    }
+
+    taskCount++;
+    if (opts.verbose) process.env.WEAVER_VERBOSE = '1';
+    renderer.taskStart(taskCount, task.instruction ?? task.id);
+
+    await queue.markRunning(task.id);
+    // Reserve files
+    for (const f of taskTargets) filesInUse.add(f);
+
+    // Launch task (parallel or sequential based on parallelism setting)
+    const promise = processTask(task);
+    running.set(task.id, promise);
+
+    // In sequential mode (parallelism=1), await immediately
+    if (parallelism <= 1) {
+      await promise;
+    }
+  }
+
+  // Wait for all remaining parallel tasks
+  if (running.size > 0) {
+    await Promise.allSettled(running.values());
+  }
+
+  const elapsed = Date.now() - sessionStartTime;
+  renderer.sessionEnd({
+    tasks: taskCount,
+    completed: sessionCompleted,
+    failed: sessionFailed,
+    totalInputTokens: sessionInputTokens,
+    totalOutputTokens: sessionOutputTokens,
+    totalCost: sessionCost,
+    elapsed,
+  });
+
+  // Desktop notification on session end (cross-platform)
+  if (taskCount > 0) {
+    try {
+      const { sendDesktopNotification } = await import('./bot/bot-manager.js');
+      sendDesktopNotification('Weaver Session Complete', `${sessionCompleted} done, ${sessionFailed} failed, ${sessionNoOp} no-op`);
+    } catch { /* non-fatal */ }
   }
 }
 
+export async function handleAssistant(opts: ParsedArgs): Promise<void> {
+  const projectDir = opts.file ?? process.cwd();
+
+  // Handle --list and --delete before creating provider
+  if (opts.assistantList) {
+    const { ConversationStore } = await import('./bot/conversation-store.js');
+    const { formatTokens, formatElapsed } = await import('./bot/terminal-renderer.js');
+    const store = new ConversationStore();
+    const convos = store.list();
+    if (convos.length === 0) {
+      console.log('  No conversations yet.');
+      return;
+    }
+    console.log(`  Conversations (${convos.length}):\n`);
+    for (const c of convos) {
+      const ago = formatElapsed(Date.now() - c.lastMessageAt) + ' ago';
+      const title = c.title ? `"${c.title}"` : '(untitled)';
+      console.log(`    ${c.id}  ${title.padEnd(45)}  ${String(c.messageCount).padStart(3)} msgs  ${formatTokens(c.totalTokens).padStart(5)} tokens  ${ago}`);
+    }
+    return;
+  }
+
+  if (opts.assistantDelete) {
+    const { ConversationStore } = await import('./bot/conversation-store.js');
+    const store = new ConversationStore();
+    store.delete(opts.assistantDelete);
+    console.log(`  Deleted conversation ${opts.assistantDelete}`);
+    return;
+  }
+
+  const config = await loadConfig(opts.configPath);
+
+  // Create provider
+  const { createAnthropicProvider, createClaudeCliProvider } = await import('@synergenius/flow-weaver/agent');
+  const providerSetting = config?.provider ?? 'auto';
+  const providerType = typeof providerSetting === 'object' ? providerSetting.name : String(providerSetting);
+
+  let provider;
+  if (providerType === 'anthropic' || (providerType === 'auto' && process.env.ANTHROPIC_API_KEY)) {
+    const apiKey = process.env.ANTHROPIC_API_KEY ?? (typeof providerSetting === 'object' ? (providerSetting as { apiKey?: string }).apiKey : undefined);
+    if (!apiKey) { console.error('ANTHROPIC_API_KEY required for anthropic provider'); process.exit(1); }
+    provider = createAnthropicProvider({ apiKey, model: typeof providerSetting === 'object' ? providerSetting.model : undefined });
+  } else {
+    provider = createClaudeCliProvider({ model: typeof providerSetting === 'object' ? providerSetting.model : undefined });
+  }
+
+  const { ASSISTANT_TOOLS, createAssistantExecutor } = await import('./bot/assistant-tools.js');
+  const { runAssistant } = await import('./bot/assistant-core.js');
+  const executor = createAssistantExecutor(projectDir);
+
+  await runAssistant({
+    provider,
+    tools: ASSISTANT_TOOLS,
+    executor,
+    projectDir,
+    resumeId: opts.assistantResume,
+    newConversation: opts.assistantNew,
+  });
+}
+
 export async function handleSteer(opts: ParsedArgs): Promise<void> {
   const { SteeringController } = await import('./bot/steering.js');
   const controller = new SteeringController();
@@ -1266,8 +1613,8 @@ export async function handleQueue(opts: ParsedArgs): Promise<void> {
   const queue = new TaskQueue();
 
   const action = opts.botTask;
-  if (!action || !['add', 'list', 'clear', 'remove'].includes(action)) {
-    console.error('[weaver] Usage: flow-weaver weaver queue <add|list|clear|remove> [task|id]');
+  if (!action || !['add', 'list', 'clear', 'remove', 'retry'].includes(action)) {
+    console.error('[weaver] Usage: flow-weaver weaver queue <add|list|clear|remove|retry> [task|id]');
     process.exit(1);
   }
 
@@ -1278,18 +1625,24 @@ export async function handleQueue(opts: ParsedArgs): Promise<void> {
         console.error('[weaver] Usage: flow-weaver weaver queue add "task instruction"');
         process.exit(1);
       }
-      const id = await queue.add({ instruction, priority: 0 });
-      console.log(`[weaver] Task added: ${id}`);
+      const { id, duplicate } = await queue.add({ instruction, priority: 0 });
+      if (duplicate) {
+        console.log(`[weaver] Task already queued (${id}).`);
+      } else {
+        console.log(`[weaver] Task added: ${id}`);
+      }
       break;
     }
     case 'list': {
       const tasks = await queue.list();
-      if (tasks.length === 0) {
+      if (opts.historyJson) {
+        console.log(JSON.stringify(tasks, null, 2));
+      } else if (tasks.length === 0) {
         console.log('No tasks in queue.');
       } else {
-        console.log('ID'.padEnd(10) + 'STATUS'.padEnd(12) + 'INSTRUCTION');
+        console.log('ID'.padEnd(10) + 'STATUS'.padEnd(12) + 'PRIORITY'.padEnd(10) + 'INSTRUCTION');
         for (const t of tasks) {
-          console.log(t.id.padEnd(10) + t.status.padEnd(12) + t.instruction.slice(0, 60));
+          console.log(t.id.padEnd(10) + t.status.padEnd(12) + String(t.priority).padEnd(10) + t.instruction.slice(0, 60));
         }
       }
       break;
@@ -1309,7 +1662,63 @@ export async function handleQueue(opts: ParsedArgs): Promise<void> {
       console.log(removed ? `Removed task ${id}.` : `No task found with id "${id}".`);
       break;
     }
+    case 'retry': {
+      const id = opts.botFile;
+      if (id) {
+        // Retry a specific task
+        const retried = await queue.retry(id);
+        console.log(retried ? `Task ${id} reset to pending.` : `No failed/running task found with id "${id}".`);
+      } else {
+        // Retry all failed tasks
+        const count = await queue.retryAll();
+        console.log(`Reset ${count} failed task(s) to pending.`);
+      }
+      break;
+    }
+  }
+}
+
+export async function handleStatus(opts: ParsedArgs): Promise<void> {
+  const store = new RunStore();
+  const { TaskQueue } = await import('./bot/task-queue.js');
+  const queue = new TaskQueue();
+
+  const orphans = store.checkOrphans();
+  const recentRuns = store.list({ limit: 5 });
+  const tasks = await queue.list();
+  const pending = tasks.filter(t => t.status === 'pending').length;
+  const running = tasks.filter(t => t.status === 'running').length;
+  const completed = tasks.filter(t => t.status === 'completed').length;
+  const failed = tasks.filter(t => t.status === 'failed').length;
+
+  if (opts.historyJson) {
+    console.log(JSON.stringify({
+      queue: { pending, running, completed, failed, total: tasks.length },
+      orphanedRuns: orphans.length,
+      recentRuns: recentRuns.map(r => ({
+        id: r.id, outcome: r.outcome, summary: r.summary,
+        startedAt: r.startedAt, durationMs: r.durationMs,
+      })),
+    }, null, 2));
+    return;
+  }
+
+  console.log('\n\x1b[1mWeaver Status\x1b[0m\n');
+  console.log(`  Queue:  ${pending} pending, ${running} running, ${completed} completed, ${failed} failed`);
+  if (orphans.length > 0) {
+    console.log(`  \x1b[33mOrphaned runs: ${orphans.length} (recovered)\x1b[0m`);
+  }
+
+  if (recentRuns.length > 0) {
+    console.log(`\n  Recent runs:`);
+    for (const r of recentRuns) {
+      const icon = r.success ? '\x1b[32m✓\x1b[0m' : '\x1b[31m✗\x1b[0m';
+      console.log(`    ${icon} ${r.id.slice(0, 8)} ${r.outcome.padEnd(9)} ${formatDuration(r.durationMs).padEnd(8)} ${r.summary.slice(0, 60)}`);
+    }
+  } else {
+    console.log('\n  No recent runs.');
   }
+  console.log('');
 }
 
 export async function handleGenesis(opts: ParsedArgs): Promise<void> {
@@ -1443,3 +1852,325 @@ function printAuditEvents(events: AuditEvent[], json: boolean): void {
     console.log(`${time} [${e.type}]${dataStr}`);
   }
 }
+
+// --- Help ---
+
+const COMMAND_HELP: Record<string, string> = {
+  run:       'run <workflow.ts>              Execute a workflow with AI agent channel',
+  bot:       'bot "task description"         Create or modify a workflow from a task',
+  init:      'init                           Create a .weaver.json config file',
+  history:   'history [id] [--limit N]       Show execution history',
+  costs:     'costs [--since 7d]             Show AI token usage and costs',
+  providers: 'providers                      List available AI providers',
+  watch:     'watch <workflow.ts>            Re-run on file changes',
+  cron:      'cron "*/5 * * * *" <file>      Schedule workflow execution',
+  pipeline:  'pipeline <config.json>         Run multi-stage pipeline',
+  dashboard: 'dashboard <file> [--port N]    Start live execution dashboard',
+  session:   'session                        Start continuous task queue processing',
+  queue:     'queue <add|list|clear> [task]  Manage task queue',
+  steer:     'steer <pause|resume|cancel>    Control a running session',
+  genesis:   'genesis [--init] [--watch]     Run self-evolution cycle',
+  eject:     'eject [--workflow bot|genesis]  Export managed workflows',
+  audit:     'audit [runId] [--limit N]      View audit log',
+  assistant: 'assistant                       AI-powered assistant for managing bots and workflows',
+};
+
+export function printHelp(command?: string): void {
+  if (command && command !== 'help' && COMMAND_HELP[command]) {
+    console.log(`\nUsage: flow-weaver weaver ${COMMAND_HELP[command]}\n`);
+    printCommandHelp(command);
+    return;
+  }
+
+  console.log(`
+Weaver — AI-powered workflow automation for Flow Weaver
+
+Usage: flow-weaver weaver <command> [options]
+
+Commands:
+  ${Object.values(COMMAND_HELP).join('\n  ')}
+
+Global options:
+  -h, --help          Show help
+  -v, --verbose       Show detailed output
+  -n, --dry-run       Preview without executing
+  --quiet             Suppress output
+  -p, --params <json> Input parameters as JSON
+  -c, --config <path> Path to .weaver.json config
+  --approval <mode>   Override approval mode (auto|prompt|web|timeout-auto)
+
+Quick start:
+  flow-weaver weaver init                              # create .weaver.json
+  flow-weaver weaver providers                         # check available AI providers
+  flow-weaver weaver bot "Create a hello world workflow"  # create your first workflow
+`);
+}
+
+function printCommandHelp(command: string): void {
+  const help: Record<string, string> = {
+    run: `Options:
+  --dashboard         Enable live dashboard
+  --port <n>          Dashboard port (default: 4242)`,
+    bot: `Options:
+  --file <path>       Target file for modification (switches to modify mode)
+  --template <name>   Use a template for scaffolding
+  --batch <n>         Process multiple tasks
+  --auto-approve      Skip approval gate
+  --dashboard         Enable live dashboard`,
+    history: `Options:
+  --limit <n>         Number of records (default: 20)
+  --outcome <type>    Filter: completed, failed, error, skipped
+  --workflow <path>   Filter by workflow file
+  --since <range>     Time range: 7d, 2h, or ISO date
+  --json              Output as JSON
+  --prune             Remove old records
+  --clear             Delete all history`,
+    costs: `Options:
+  --since <range>     Time range: 7d, 30d, or ISO date
+  --model <name>      Filter by model`,
+    genesis: `Options:
+  --init              Initialize .genesis/config.json
+  --watch             Run multiple evolution cycles
+  --project-dir <p>   Project directory`,
+    watch: `Options:
+  --debounce <ms>     Debounce interval (default: 500)
+  --log <path>        Log file for daemon output`,
+    pipeline: `Options:
+  --stage <id>        Run a specific stage only`,
+    queue: `Actions:
+  add "task"          Add task to queue
+  list                Show queue contents
+  clear               Remove all tasks
+  remove <id>         Remove a specific task`,
+    steer: `Commands:
+  pause               Pause current execution
+  resume              Resume paused execution
+  cancel              Cancel current execution
+  redirect "task"     Switch to a different task
+  queue "task"        Add task to queue from steer`,
+  };
+
+  if (help[command]) {
+    console.log(help[command]);
+    console.log('');
+  }
+}
+
+// --- Init ---
+
+export async function handleInit(opts: ParsedArgs): Promise<void> {
+  const dir = opts.file ? path.resolve(opts.file) : process.cwd();
+  const configPath = path.join(dir, '.weaver.json');
+
+  if (fs.existsSync(configPath)) {
+    console.log(`[weaver] Config already exists: ${configPath}`);
+    console.log('  Edit it directly or delete it to regenerate.');
+    return;
+  }
+
+  // Detect best available provider (priority: Anthropic API > OpenAI API > Claude CLI > Copilot CLI)
+  let provider: string = 'auto';
+  const detected: string[] = [];
+  try {
+    if (process.env.ANTHROPIC_API_KEY) {
+      provider = 'anthropic';
+      detected.push('Anthropic API (ANTHROPIC_API_KEY)');
+    }
+    if (process.env.OPENAI_API_KEY) {
+      if (provider === 'auto') provider = 'openai';
+      detected.push('OpenAI API (OPENAI_API_KEY)');
+    }
+    const { execFileSync } = await import('node:child_process');
+    try {
+      execFileSync('claude', ['--version'], { stdio: 'pipe' });
+      if (provider === 'auto') provider = 'claude-cli';
+      detected.push('Claude CLI');
+    } catch { /* not found */ }
+    try {
+      execFileSync('copilot', ['--version'], { stdio: 'pipe' });
+      if (provider === 'auto') provider = 'copilot-cli';
+      detected.push('Copilot CLI');
+    } catch { /* not found */ }
+  } catch {
+    // Stay with auto
+  }
+
+  const config = {
+    provider: provider === 'auto' ? 'auto' : { name: provider },
+    approval: 'auto',
+  };
+
+  fs.writeFileSync(configPath, JSON.stringify(config, null, 2) + '\n', 'utf-8');
+
+  console.log('');
+  console.log('  \x1b[1mWelcome to Weaver\x1b[0m — your AI workflow companion.');
+  console.log('');
+  console.log('  \x1b[2mDetecting providers...\x1b[0m');
+  if (detected.length > 0) {
+    for (const d of detected) console.log(`    \x1b[32m✓\x1b[0m ${d}`);
+  } else {
+    console.log('    \x1b[33m⚠\x1b[0m No provider detected');
+    console.log('      Set ANTHROPIC_API_KEY, OPENAI_API_KEY, or install Claude CLI');
+  }
+  console.log('');
+
+  // Test connection if possible
+  if (provider === 'claude-cli') {
+    try {
+      const { execFileSync: testExec } = await import('node:child_process');
+      testExec('claude', ['--version'], { stdio: 'pipe', timeout: 5000 });
+      console.log('  \x1b[2mTesting connection...\x1b[0m');
+      console.log('    \x1b[32m✓\x1b[0m Claude CLI: connected');
+    } catch {
+      console.log('  \x1b[33m⚠\x1b[0m Could not verify Claude CLI connection');
+    }
+  }
+
+  console.log('');
+  console.log(`  \x1b[32m✓\x1b[0m Config written to .weaver.json`);
+  console.log(`    provider: ${provider}`);
+  console.log('    approval: auto');
+  console.log('');
+  console.log('  Try it now:');
+  console.log('    \x1b[36mweaver bot "Create a hello world workflow"\x1b[0m');
+  console.log('    \x1b[36mweaver assistant\x1b[0m');
+  console.log('');
+  console.log('  Learn more:');
+  console.log('    weaver examples         \x1b[2m# see what weaver can do\x1b[0m');
+  console.log('    weaver doctor           \x1b[2m# validate your setup\x1b[0m');
+  console.log('');
+}
+
+export async function handleExamples(_opts: ParsedArgs): Promise<void> {
+  console.log('');
+  console.log('  \x1b[1mWeaver Examples\x1b[0m');
+  console.log('');
+  console.log('  \x1b[36mCreate workflows:\x1b[0m');
+  console.log('    weaver bot "Create a workflow that validates user input and sends email"');
+  console.log('    weaver bot "Create a data pipeline that reads CSV, transforms, and writes JSON"');
+  console.log('    weaver bot "Create an AI agent with retry and fallback providers"');
+  console.log('    weaver bot "Create a webhook handler that processes Stripe events"');
+  console.log('    weaver bot "Create a RAG pipeline with document chunking and embedding"');
+  console.log('');
+  console.log('  \x1b[36mModify existing workflows:\x1b[0m');
+  console.log('    weaver bot "Add error handling to my-workflow.ts" --file src/my-workflow.ts');
+  console.log('    weaver bot "Add a validation step before the API call" --file src/pipeline.ts');
+  console.log('    weaver bot "Make the retry node use exponential backoff" --file src/agent.ts');
+  console.log('');
+  console.log('  \x1b[36mInteractive assistant:\x1b[0m');
+  console.log('    weaver assistant                        \x1b[2m# AI assistant with tools\x1b[0m');
+  console.log('    weaver assistant --new                  \x1b[2m# fresh conversation\x1b[0m');
+  console.log('    weaver assistant --list                 \x1b[2m# saved conversations\x1b[0m');
+  console.log('');
+  console.log('  \x1b[36mAutonomous mode:\x1b[0m');
+  console.log('    weaver session --continuous             \x1b[2m# process task queue\x1b[0m');
+  console.log('    weaver queue add "Fix all validation errors"');
+  console.log('    weaver session --continuous --until 10:00 --parallel 3');
+  console.log('');
+  console.log('  \x1b[36mInspect and debug:\x1b[0m');
+  console.log('    flow-weaver validate src/*.ts           \x1b[2m# check all workflows\x1b[0m');
+  console.log('    flow-weaver diagram src/my-workflow.ts  \x1b[2m# visual diagram\x1b[0m');
+  console.log('    flow-weaver describe src/my-workflow.ts \x1b[2m# natural language description\x1b[0m');
+  console.log('');
+  console.log('  \x1b[36mCustomize the bot:\x1b[0m');
+  console.log('    weaver eject                            \x1b[2m# get editable bot workflow\x1b[0m');
+  console.log('    weaver eject --workflow bot              \x1b[2m# eject specific workflow\x1b[0m');
+  console.log('');
+}
+
+export async function handleDoctor(opts: ParsedArgs): Promise<void> {
+  const dir = opts.file ?? process.cwd();
+  const checks: Array<{ label: string; status: 'ok' | 'warn' | 'fail'; detail: string }> = [];
+
+  // Config check
+  const configPath = path.join(dir, '.weaver.json');
+  if (fs.existsSync(configPath)) {
+    checks.push({ label: 'Config', status: 'ok', detail: '.weaver.json found' });
+  } else {
+    checks.push({ label: 'Config', status: 'warn', detail: 'No .weaver.json — run "weaver init"' });
+  }
+
+  // Provider check
+  const config = await loadConfig(opts.configPath);
+  const providerSetting = config?.provider ?? 'auto';
+  const providerName = typeof providerSetting === 'object' ? providerSetting.name : String(providerSetting);
+  let providerDetail = providerName;
+
+  if (providerName === 'anthropic' || process.env.ANTHROPIC_API_KEY) {
+    providerDetail = 'anthropic (API key set)';
+    checks.push({ label: 'Provider', status: 'ok', detail: providerDetail });
+  } else {
+    try {
+      const { execFileSync: provCheck } = await import('node:child_process');
+      provCheck('claude', ['--version'], { stdio: 'pipe', timeout: 5000 });
+      providerDetail = 'claude-cli';
+      checks.push({ label: 'Provider', status: 'ok', detail: providerDetail });
+    } catch {
+      checks.push({ label: 'Provider', status: 'fail', detail: 'No provider found — set ANTHROPIC_API_KEY or install Claude CLI' });
+    }
+  }
+
+  // Connection test
+  if (providerName === 'claude-cli' || (!process.env.ANTHROPIC_API_KEY && providerName === 'auto')) {
+    try {
+      const { execFileSync: connCheck } = await import('node:child_process');
+      const start = Date.now();
+      connCheck('claude', ['-p', '--max-turns', '1', 'say ok'], { stdio: 'pipe', timeout: 15000 });
+      checks.push({ label: 'Connection', status: 'ok', detail: `OK (${((Date.now() - start) / 1000).toFixed(1)}s)` });
+    } catch {
+      checks.push({ label: 'Connection', status: 'warn', detail: 'Could not verify (Claude CLI may need auth)' });
+    }
+  } else if (process.env.ANTHROPIC_API_KEY) {
+    checks.push({ label: 'Connection', status: 'ok', detail: 'API key configured' });
+  } else {
+    checks.push({ label: 'Connection', status: 'warn', detail: 'Not tested' });
+  }
+
+  // Flow Weaver version
+  try {
+    const { execFileSync: fwCheck } = await import('node:child_process');
+    const version = fwCheck('npx', ['flow-weaver', '--version'], { encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'], timeout: 10000, cwd: dir }).trim();
+    checks.push({ label: 'Flow Weaver', status: 'ok', detail: version });
+  } catch {
+    checks.push({ label: 'Flow Weaver', status: 'fail', detail: 'Not installed — run "npm install @synergenius/flow-weaver"' });
+  }
+
+  // Queue status
+  try {
+    const { TaskQueue } = await import('./bot/task-queue.js');
+    process.env.WEAVER_PROJECT_DIR = dir;
+    const queue = new TaskQueue();
+    const tasks = await queue.list();
+    const pending = tasks.filter(t => t.status === 'pending').length;
+    const running = tasks.filter(t => t.status === 'running').length;
+    checks.push({ label: 'Queue', status: 'ok', detail: `${pending} pending, ${running} running` });
+  } catch {
+    checks.push({ label: 'Queue', status: 'ok', detail: 'Empty (no queue file)' });
+  }
+
+  // Plan file
+  const planPath = path.join(dir, '.weaver-plan.md');
+  if (fs.existsSync(planPath)) {
+    checks.push({ label: 'Plan', status: 'ok', detail: '.weaver-plan.md found' });
+  } else {
+    checks.push({ label: 'Plan', status: 'warn', detail: 'No .weaver-plan.md — optional, guides bot behavior' });
+  }
+
+  // Output
+  console.log('');
+  console.log('  \x1b[1mWeaver Doctor\x1b[0m');
+  console.log('');
+  const icons = { ok: '\x1b[32m✓\x1b[0m', warn: '\x1b[33m⚠\x1b[0m', fail: '\x1b[31m✗\x1b[0m' };
+  for (const check of checks) {
+    console.log(`  ${icons[check.status]} ${check.label.padEnd(14)} ${check.detail}`);
+  }
+  console.log('');
+
+  const failures = checks.filter(c => c.status === 'fail');
+  if (failures.length > 0) {
+    console.log(`  \x1b[31m${failures.length} issue(s) found.\x1b[0m`);
+  } else {
+    console.log('  \x1b[32mAll checks passed.\x1b[0m');
+  }
+  console.log('');
+}