@williambeto/ai-workflow 2.6.4 → 2.6.7

package/CHANGELOG.md

@@ -1,3 +1,8 @@
+## [unreleased]
+
+### 🧪 Testing
+
+- Align E2E assertions with updated requestedActor routing mechanics
 ## [2.6.4] - 2026-07-04
 
 ### 🐛 Bug Fixes

package/bin/ai-workflow.js

@@ -21,13 +21,13 @@ import {
   isTerminalFailure,
   readPackageFile,
   resolveWorkflowProfile
-} from "../chunk-UHLZX2EG.js";
+} from "../chunk-W4RTQWVQ.js";
 import {
   EvidenceCollector,
   QualityGuard,
   ValidationPlanner
-} from "../chunk-6EMG6FAO.js";
-import "../chunk-2AOV2ATY.js";
+} from "../chunk-BDZPUAEX.js";
+import "../chunk-XW747GIG.js";
 import "../chunk-5WRI5ZAA.js";
 
 // src/cli/commands/init.ts
@@ -1486,11 +1486,7 @@ async function isSymlink(filePath) {
     return false;
   }
 }
-async function runDoctor({ cwd }) {
-  let hasFailure = false;
-  let hasWarning = false;
-  let managedBlocks = [];
-  console.log("Doctor report:");
+async function checkOpenCodeRuntime(cwd, state) {
   const adapter = new OpenCodeAdapter({ cwd });
   const inspection = await adapter.inspect();
   if (inspection.available) {
@@ -1500,22 +1496,26 @@ async function runDoctor({ cwd }) {
     if (inspection.supports.agent) {
       console.log("PASS opencode --agent selection is supported");
     } else {
-      hasWarning = true;
+      state.hasWarning = true;
       console.log("WARN opencode --agent selection is not supported; prompt fallback is available");
     }
   } else {
-    hasFailure = true;
+    state.hasFailure = true;
     console.log("FAIL opencode CLI is not installed or not available in PATH");
   }
+}
+async function checkRequiredFiles(cwd, state) {
   for (const relativePath of REQUIRED_FILES) {
     const ok = await exists(path10.join(cwd, relativePath));
     if (ok) {
       console.log(`PASS ${relativePath}`);
     } else {
-      hasFailure = true;
+      state.hasFailure = true;
       console.log(`FAIL ${relativePath} missing`);
     }
   }
+}
+async function checkAiWorkflowConfig(cwd, state) {
   const configPathV2 = path10.join(cwd, ".ai-workflow/config.json");
   const configPathLegacy = path10.join(cwd, ".ai-workflow.json");
   let configPath = null;
@@ -1524,122 +1524,137 @@ async function runDoctor({ cwd }) {
   } else if (await exists(configPathLegacy)) {
     configPath = configPathLegacy;
   }
-  if (configPath) {
-    try {
-      const config = await readJson(configPath);
-      if (config.installMode === "project-local" || config.mode === "standalone") {
-        console.log("PASS install mode is project-local/standalone");
-      } else {
-        hasWarning = true;
-        console.log(`WARN install mode is not project-local/standalone in ${path10.basename(configPath)}`);
-      }
-      if (config.profile) {
-        console.log(`PASS profile detected: ${config.profile}`);
-      } else {
-        hasWarning = true;
-        console.log(`WARN profile is missing in ${path10.basename(configPath)}`);
-      }
-      if (config.runtime) {
-        console.log(`PASS runtime: ${config.runtime}`);
-      } else {
-        console.log(`NOTE runtime field not present in ${path10.basename(configPath)}`);
-      }
-      if (Array.isArray(config.managedBlocks)) {
-        managedBlocks = config.managedBlocks;
-      } else {
-        console.log(`NOTE managedBlocks not present in ${path10.basename(configPath)} (legacy field)`);
-      }
-      if (Array.isArray(config.managedFiles)) {
-        for (const relativePath of config.managedFiles) {
-          const fileExists = await exists(path10.join(cwd, relativePath));
-          if (!fileExists) {
-            hasWarning = true;
-            console.log(`WARN managed file missing: ${relativePath}`);
-          }
+  if (!configPath) return;
+  try {
+    const config = await readJson(configPath);
+    const basename = path10.basename(configPath);
+    if (config.installMode === "project-local" || config.mode === "standalone") {
+      console.log("PASS install mode is project-local/standalone");
+    } else {
+      state.hasWarning = true;
+      console.log(`WARN install mode is not project-local/standalone in ${basename}`);
+    }
+    if (config.profile) {
+      console.log(`PASS profile detected: ${config.profile}`);
+    } else {
+      state.hasWarning = true;
+      console.log(`WARN profile is missing in ${basename}`);
+    }
+    if (config.runtime) {
+      console.log(`PASS runtime: ${config.runtime}`);
+    } else {
+      console.log(`NOTE runtime field not present in ${basename}`);
+    }
+    if (Array.isArray(config.managedBlocks)) {
+      state.managedBlocks = config.managedBlocks;
+    } else {
+      console.log(`NOTE managedBlocks not present in ${basename} (legacy field)`);
+    }
+    if (Array.isArray(config.managedFiles)) {
+      for (const relativePath of config.managedFiles) {
+        const fileExists = await exists(path10.join(cwd, relativePath));
+        if (!fileExists) {
+          state.hasWarning = true;
+          console.log(`WARN managed file missing: ${relativePath}`);
         }
       }
-      if (Array.isArray(config.managedLinks)) {
-        for (const relativePath of config.managedLinks) {
-          const absolutePath = path10.join(cwd, relativePath);
-          const linkExists = await exists(absolutePath);
-          if (!linkExists) {
-            hasWarning = true;
-            console.log(`WARN managed link missing: ${relativePath}`);
-            continue;
-          }
-          const isLink = await isSymlink(absolutePath);
-          if (!isLink) {
-            hasWarning = true;
-            console.log(`WARN managed link is not a symlink: ${relativePath}`);
-          }
+    }
+    if (Array.isArray(config.managedLinks)) {
+      for (const relativePath of config.managedLinks) {
+        const absolutePath = path10.join(cwd, relativePath);
+        if (!await exists(absolutePath)) {
+          state.hasWarning = true;
+          console.log(`WARN managed link missing: ${relativePath}`);
+          continue;
+        }
+        if (!await isSymlink(absolutePath)) {
+          state.hasWarning = true;
+          console.log(`WARN managed link is not a symlink: ${relativePath}`);
         }
       }
-    } catch {
-      hasFailure = true;
-      console.log(`FAIL ${path10.basename(configPath)} is not valid JSON`);
     }
+  } catch {
+    state.hasFailure = true;
+    console.log(`FAIL ${path10.basename(configPath)} is not valid JSON`);
   }
+}
+async function checkOpencodeJson(cwd, state) {
   const opencodePath = path10.join(cwd, "opencode.jsonc");
   if (!await exists(opencodePath)) {
-    hasFailure = true;
+    state.hasFailure = true;
     console.log("FAIL opencode.jsonc missing");
-  } else {
-    try {
-      const opencodeConfig = await readJsonc(opencodePath);
-      console.log("PASS opencode.jsonc is valid JSONC");
-      const needsAgentDefault = managedBlocks.includes("opencode.jsonc:agent.default");
-      if (!needsAgentDefault || opencodeConfig.agent?.default) {
-        console.log("PASS opencode agent.default available");
-      } else {
-        hasFailure = true;
-        console.log("FAIL opencode agent.default missing");
-      }
-      const requiredCommands = managedBlocks.filter((block) => block.startsWith("opencode.jsonc:command.")).map((block) => block.replace("opencode.jsonc:command.", ""));
-      if (requiredCommands.length === 0) {
-        console.log("PASS no managed opencode commands required");
+    return;
+  }
+  try {
+    const opencodeConfig = await readJsonc(opencodePath);
+    console.log("PASS opencode.jsonc is valid JSONC");
+    const needsAgentDefault = state.managedBlocks.includes("opencode.jsonc:agent.default");
+    if (!needsAgentDefault || opencodeConfig.agent?.default) {
+      console.log("PASS opencode agent.default available");
+    } else {
+      state.hasFailure = true;
+      console.log("FAIL opencode agent.default missing");
+    }
+    const requiredCommands = state.managedBlocks.filter((block) => block.startsWith("opencode.jsonc:command.")).map((block) => block.replace("opencode.jsonc:command.", ""));
+    if (requiredCommands.length === 0) {
+      console.log("PASS no managed opencode commands required");
+    } else {
+      const missingCommands = requiredCommands.filter((command) => !opencodeConfig.command?.[command]);
+      if (missingCommands.length === 0) {
+        console.log(`PASS opencode managed commands available (${requiredCommands.length})`);
       } else {
-        const missingCommands = requiredCommands.filter((command) => !opencodeConfig.command?.[command]);
-        if (missingCommands.length === 0) {
-          console.log(`PASS opencode managed commands available (${requiredCommands.length})`);
-        } else {
-          hasFailure = true;
-          console.log(`FAIL opencode command entries missing: ${missingCommands.join(", ")}`);
-        }
+        state.hasFailure = true;
+        console.log(`FAIL opencode command entries missing: ${missingCommands.join(", ")}`);
       }
-      const requiredAgents = managedBlocks.filter((block) => block.startsWith("opencode.jsonc:agent.") && !block.endsWith(".default")).map((block) => block.replace("opencode.jsonc:agent.", ""));
-      if (requiredAgents.length === 0) {
-        console.log("PASS no managed opencode agents required");
+    }
+    const requiredAgents = state.managedBlocks.filter((block) => block.startsWith("opencode.jsonc:agent.") && !block.endsWith(".default")).map((block) => block.replace("opencode.jsonc:agent.", ""));
+    if (requiredAgents.length === 0) {
+      console.log("PASS no managed opencode agents required");
+    } else {
+      const missingAgents = requiredAgents.filter((agent) => !opencodeConfig.agent?.[agent]);
+      if (missingAgents.length === 0) {
+        console.log(`PASS opencode managed agents available (${requiredAgents.length})`);
       } else {
-        const missingAgents = requiredAgents.filter((agent) => !opencodeConfig.agent?.[agent]);
-        if (missingAgents.length === 0) {
-          console.log(`PASS opencode managed agents available (${requiredAgents.length})`);
-        } else {
-          hasFailure = true;
-          console.log(`FAIL opencode agent entries missing: ${missingAgents.join(", ")}`);
-        }
+        state.hasFailure = true;
+        console.log(`FAIL opencode agent entries missing: ${missingAgents.join(", ")}`);
       }
-    } catch {
-      hasFailure = true;
-      console.log("FAIL opencode.jsonc is not valid JSONC");
     }
+  } catch {
+    state.hasFailure = true;
+    console.log("FAIL opencode.jsonc is not valid JSONC");
   }
+}
+async function checkPackageJson(cwd, state) {
   const packageJsonPath = path10.join(cwd, "package.json");
   if (await exists(packageJsonPath)) {
     try {
       const packageJson = await readJson(packageJsonPath);
       const scripts = packageJson.scripts ?? {};
       if (!scripts.validate) {
-        hasWarning = true;
+        state.hasWarning = true;
         console.log("WARN package.json has no validate script");
       }
     } catch {
-      hasFailure = true;
+      state.hasFailure = true;
       console.log("FAIL package.json is not valid JSON");
     }
   }
-  const finalStatus = hasFailure ? "FAIL" : hasWarning ? "PASS_WITH_NOTES" : "PASS";
+}
+async function runDoctor({ cwd }) {
+  const state = {
+    hasFailure: false,
+    hasWarning: false,
+    managedBlocks: []
+  };
+  console.log("Doctor report:");
+  await checkOpenCodeRuntime(cwd, state);
+  await checkRequiredFiles(cwd, state);
+  await checkAiWorkflowConfig(cwd, state);
+  await checkOpencodeJson(cwd, state);
+  await checkPackageJson(cwd, state);
+  const finalStatus = state.hasFailure ? "FAIL" : state.hasWarning ? "PASS_WITH_NOTES" : "PASS";
   console.log(`Final status: ${finalStatus}`);
-  if (hasFailure) {
+  if (state.hasFailure) {
     process.exitCode = 1;
   }
 }
@@ -2288,6 +2303,71 @@ async function generateFinalHandoff(plan, taskSlug, cwd, finalState, evidence) {
 `);
   return handoffPath;
 }
+async function runFastTrackValidation(cwd, result, checkBranchSafety) {
+  console.log(`
+--- [FAST-TRACK] Running Lightweight Validation Gates ---`);
+  checkBranchSafety();
+  const changedFiles = result.evidence?.changedFiles || [];
+  console.log(`[FAST-TRACK] Changed files detected:`, changedFiles);
+  const evidencePath = path14.join(cwd, "EVIDENCE.json");
+  const hasEvidence = await fs12.access(evidencePath).then(() => true).catch(() => false);
+  if (hasEvidence) {
+    const { EvidenceValidator } = await import("../evidence-validator-76ZQQYDU.js");
+    const isTest = process.env.NODE_ENV === "test" || process.env.VITEST === "true";
+    const evidenceValidator = new EvidenceValidator({ cwd, skipFileCheck: isTest, skipGitCheck: isTest });
+    const valResult = await evidenceValidator.validate();
+    if (!valResult.valid) {
+      console.error(`
+[FAST-TRACK BLOCKED] EVIDENCE.json validation failed: ${valResult.reason}`);
+      return "FAIL_QUALITY_GATE";
+    }
+  }
+  return result.overallStatus;
+}
+async function runFidelityValidation(naturalRequest, result, finalizer) {
+  const fidelityResult = await finalizer.verifyFidelity({
+    userRequest: naturalRequest,
+    projectContext: result.evidence?.deliveryDecision?.projectContext || null,
+    deliveryDecision: result.evidence?.deliveryDecision || null,
+    changedFiles: result.evidence?.changedFiles || [],
+    evidence: result.evidence || null,
+    explicitApprovals: process.env.AI_WORKFLOW_APPROVALS ? process.env.AI_WORKFLOW_APPROVALS.split(",").map((a) => a.trim()) : []
+  });
+  if (!fidelityResult.passed) {
+    console.log(`
+[FINALIZER BLOCKED] BLOCKED: Artifact fidelity check failed!`);
+    console.log(`Reason: ${fidelityResult.reason}`);
+    return "FAIL_QUALITY_GATE";
+  }
+  return result.overallStatus;
+}
+function computeFinalState(finalStatus) {
+  if (finalStatus === "PASS") return "COMPLETED";
+  if (finalStatus === "PASS_WITH_NOTES") return "COMPLETED_WITH_NOTES";
+  return "BLOCKED";
+}
+async function executeReadOnlyWorkflow(cwd, stateMachine, readOnlyStateBefore, fastTrack) {
+  await runReadOnlyConfinementCheck(readOnlyStateBefore, cwd, stateMachine, fastTrack);
+  stateMachine.transitionTo("IMPLEMENTED");
+  stateMachine.transitionTo("VALIDATING");
+  stateMachine.transitionTo("COMPLETED");
+  console.log("\n--- Final Handoff ---");
+  console.log(`
+[AI WORKFLOW COMPLETE] COMPLETED`);
+  console.log(`Handoff Packet: [IN-MEMORY] (No handoff file written in read-only mode)
+`);
+  return {
+    overallStatus: "PASS",
+    evidence: {
+      internalStatus: "PASS",
+      commandsRun: []
+    },
+    quality: {
+      overallStatus: "PASS"
+    },
+    stateHistory: stateMachine.getHistory()
+  };
+}
 async function runExecute({ cwd, naturalRequest, taskSlug: taskSlugOverride }) {
   if (!naturalRequest || !naturalRequest.trim()) {
     throw new Error("Missing request. Please provide a natural request string via positional arguments or --request flag.");
@@ -2303,16 +2383,15 @@ async function runExecute({ cwd, naturalRequest, taskSlug: taskSlugOverride }) {
     const stateMachine = new WorkflowStateMachine();
     const { plan: planObj, classification } = await classifyAndPlanExecution(naturalRequest, cwd, taskSlug, delegationController, stateMachine);
     plan = planObj;
-    const fastTrack = plan.riskLevel === "low" && (plan.branchNeeded ? plan.evidencePolicy === "optional" : true);
+    const fastTrack = plan.riskLevel === "low" && (!plan.branchNeeded || plan.evidencePolicy === "optional");
     const branchGate = new BranchGate({ memoryDir: path14.join(cwd, ".ai-workflow"), cwd });
     const gateResult = runBranchGate(plan, taskSlug, cwd, stateMachine, branchGate);
     const checkBranchSafety = () => {
-      if (plan.branchNeeded) {
-        const currentBranch = branchGate.getCurrentBranch();
-        if (branchGate.protectedBranches.includes(currentBranch)) {
-          stateMachine.transitionTo("BLOCKED");
-          throw new Error(`[WORKFLOW BLOCKED] Security violation: current branch is protected '${currentBranch}'!`);
-        }
+      if (!planObj.branchNeeded) return;
+      const currentBranch = branchGate.getCurrentBranch();
+      if (branchGate.protectedBranches.includes(currentBranch)) {
+        stateMachine.transitionTo("BLOCKED");
+        throw new Error(`[WORKFLOW BLOCKED] Security violation: current branch is protected '${currentBranch}'!`);
       }
     };
     await createSpecIfRequired(plan, classification, taskSlug, cwd);
@@ -2321,27 +2400,8 @@ async function runExecute({ cwd, naturalRequest, taskSlug: taskSlugOverride }) {
       readOnlyStateBefore = await captureReadOnlyState(cwd, fastTrack);
     }
     await runImplementation(plan, classification, delegationController, stateMachine, fastTrack);
-    if (!plan.branchNeeded) {
-      await runReadOnlyConfinementCheck(readOnlyStateBefore, cwd, stateMachine, fastTrack);
-      stateMachine.transitionTo("IMPLEMENTED");
-      stateMachine.transitionTo("VALIDATING");
-      stateMachine.transitionTo("COMPLETED");
-      console.log("\n--- Final Handoff ---");
-      console.log(`
-[AI WORKFLOW COMPLETE] COMPLETED`);
-      console.log(`Handoff Packet: [IN-MEMORY] (No handoff file written in read-only mode)
-`);
-      return {
-        overallStatus: "PASS",
-        evidence: {
-          internalStatus: "PASS",
-          commandsRun: []
-        },
-        quality: {
-          overallStatus: "PASS"
-        },
-        stateHistory: stateMachine.getHistory()
-      };
+    if (!plan.branchNeeded && readOnlyStateBefore) {
+      return await executeReadOnlyWorkflow(cwd, stateMachine, readOnlyStateBefore, fastTrack);
     }
     stateMachine.transitionTo("IMPLEMENTED");
     checkBranchSafety();
@@ -2369,7 +2429,6 @@ async function runExecute({ cwd, naturalRequest, taskSlug: taskSlugOverride }) {
     }
     checkBranchSafety();
     let integrity = { valid: true, changes: { added: [], modified: [], deleted: [] } };
-    let stabResult = result;
     if (!fastTrack) {
       const stab = await runFinalizerStabilization(
         plan,
@@ -2382,54 +2441,23 @@ async function runExecute({ cwd, naturalRequest, taskSlug: taskSlugOverride }) {
         snapshotRef,
         checkBranchSafety
       );
-      stabResult = stab.result;
+      result = stab.result;
       integrity = stab.integrity;
     }
-    result = stabResult;
     let finalStatus = result.overallStatus;
     if (fastTrack) {
-      console.log(`
---- [FAST-TRACK] Running Lightweight Validation Gates ---`);
-      checkBranchSafety();
-      const changedFiles = result.evidence?.changedFiles || [];
-      console.log(`[FAST-TRACK] Changed files detected:`, changedFiles);
-      const evidencePath = path14.join(cwd, "EVIDENCE.json");
-      const hasEvidence = await fs12.access(evidencePath).then(() => true).catch(() => false);
-      if (hasEvidence) {
-        const { EvidenceValidator } = await import("../evidence-validator-76ZQQYDU.js");
-        const isTest = process.env.NODE_ENV === "test" || process.env.VITEST === "true";
-        const evidenceValidator = new EvidenceValidator({ cwd, skipFileCheck: isTest, skipGitCheck: isTest });
-        const valResult2 = await evidenceValidator.validate();
-        if (!valResult2.valid) {
-          console.error(`
-[FAST-TRACK BLOCKED] EVIDENCE.json validation failed: ${valResult2.reason}`);
-          finalStatus = "FAIL_QUALITY_GATE";
-        }
-      }
+      finalStatus = await runFastTrackValidation(cwd, result, checkBranchSafety);
     } else if (!integrity.valid) {
       console.log(`
 [FINALIZER BLOCKED] BLOCKED: workspace did not stabilize`);
       console.log(`Final changes detected:`, integrity.changes);
       finalStatus = "FAIL_QUALITY_GATE";
     } else {
-      const fidelityResult = await finalizer.verifyFidelity({
-        userRequest: naturalRequest,
-        projectContext: result.evidence?.deliveryDecision?.projectContext || null,
-        deliveryDecision: result.evidence?.deliveryDecision || null,
-        changedFiles: result.evidence?.changedFiles || [],
-        evidence: result.evidence || null,
-        explicitApprovals: process.env.AI_WORKFLOW_APPROVALS ? process.env.AI_WORKFLOW_APPROVALS.split(",").map((a) => a.trim()) : []
-      });
-      if (!fidelityResult.passed) {
-        console.log(`
-[FINALIZER BLOCKED] BLOCKED: Artifact fidelity check failed!`);
-        console.log(`Reason: ${fidelityResult.reason}`);
-        finalStatus = "FAIL_QUALITY_GATE";
-      }
+      finalStatus = await runFidelityValidation(naturalRequest, result, finalizer);
     }
-    const finalState = finalStatus === "PASS" ? "COMPLETED" : finalStatus === "PASS_WITH_NOTES" ? "COMPLETED_WITH_NOTES" : "BLOCKED";
+    const finalState = computeFinalState(finalStatus);
     stateMachine.transitionTo(finalState);
-    const handoffPath = await generateFinalHandoff(plan, taskSlug, cwd, finalState, result.evidence);
+    await generateFinalHandoff(plan, taskSlug, cwd, finalState, result.evidence);
     return { ...result, overallStatus: finalStatus, stateHistory: stateMachine.getHistory() };
   } finally {
     if (plan && !plan.branchNeeded) {
@@ -2589,19 +2617,9 @@ function parseFlags(args) {
     purgeAgents: args.includes("--purge-agents") || args.includes("--purge")
   };
 }
-async function runCli(args) {
-  const [command] = args;
-  if (command === "--version" || command === "-v") {
-    console.log(getPackageVersion() || "unknown");
-    return;
-  }
-  if (!command || command === "--help" || command === "-h") {
-    printHelp();
-    return;
-  }
-  if (command === "execute") {
-    const flags = parseFlags(args.slice(1));
-    const positionals = args.slice(1).filter((arg) => !arg.startsWith("-"));
+var commandMap = {
+  execute: async (args, flags) => {
+    const positionals = args.filter((arg) => !arg.startsWith("-"));
     const request = flags.request || positionals.join(" ");
     const result = await runExecute({
       cwd: process.cwd(),
@@ -2611,25 +2629,23 @@ async function runCli(args) {
     if (result && (result.overallStatus === "FAIL_QUALITY_GATE" || result.overallStatus === "BLOCKED" || result.overallStatus === "FAIL")) {
       process.exit(1);
     }
-    return;
-  }
-  if (command === "run") {
+  },
+  run: async (_, flags) => {
     await runMasterOrchestrator({
       cwd: process.cwd(),
-      ...parseFlags(args.slice(1))
+      ...flags
     });
-    return;
-  }
-  if (command === "init") {
+  },
+  init: async (_, flags) => {
     await runInit({
       cwd: process.cwd(),
-      ...parseFlags(args.slice(1))
+      ...flags
     });
-    return;
-  }
-  if (command === "collect-evidence") {
-    const flags = parseFlags(args.slice(1));
-    if (flags.mode && !["quick", "standard", "full"].includes(flags.mode)) throw new Error("--mode must be quick, standard, or full");
+  },
+  "collect-evidence": async (_, flags) => {
+    if (flags.mode && !["quick", "standard", "full"].includes(flags.mode)) {
+      throw new Error("--mode must be quick, standard, or full");
+    }
     await runCollectEvidence({
       cwd: process.cwd(),
       taskSlug: flags.taskSlug,
@@ -2639,11 +2655,9 @@ async function runCli(args) {
       visualDist: flags.visualDist,
       port: flags.port
     });
-    return;
-  }
-  if (command === "validate") {
-    const flags = parseFlags(args.slice(1));
-    const { runValidate } = await import("../validate-Q2NLLQ5G.js");
+  },
+  validate: async (_, flags) => {
+    const { runValidate } = await import("../validate-A46WUBVZ.js");
     await runValidate({
       cwd: process.cwd(),
       taskSlug: flags.taskSlug,
@@ -2651,17 +2665,32 @@ async function runCli(args) {
       visualDist: flags.visualDist,
       port: flags.port
     });
-    return;
-  }
-  if (command === "doctor") {
+  },
+  doctor: async () => {
     await runDoctor({ cwd: process.cwd() });
-    return;
-  }
-  if (command === "clean") {
+  },
+  clean: async (_, flags) => {
     await runClean({
       cwd: process.cwd(),
-      ...parseFlags(args.slice(1))
+      ...flags
     });
+  }
+};
+async function runCli(args) {
+  const [command] = args;
+  if (command === "--version" || command === "-v") {
+    console.log(getPackageVersion() || "unknown");
+    return;
+  }
+  if (!command || command === "--help" || command === "-h") {
+    printHelp();
+    return;
+  }
+  const handler = commandMap[command];
+  if (handler) {
+    const argsSlice = args.slice(1);
+    const flags = parseFlags(argsSlice);
+    await handler(argsSlice, flags);
     return;
   }
   throw new Error(`unknown command: ${command}`);