Function dispatch

packages/evals/tui/commandTree.ts:220–296

(
  root: CommandNode,
  tokens: string[],
  ctx: CommandContext,
)

 * whether the invocation counts as a "first use" for the welcome marker.
 */
export async function dispatch(
  root: CommandNode,
  tokens: string[],
  ctx: CommandContext,
): Promise<DispatchOutcome> {
  const result = resolveCommand(root, ctx.contextPath ?? [], tokens);

  switch (result.kind) {
    case "noop":
      return { kind: "noop" };

    case "meta":
      await runMeta(result.name, result.args, root, ctx);
      return { kind: "meta" };

    case "run": {
      // Help is only triggered when `help` / `--help` / `-h` sits IMMEDIATELY
      // after the matched path. Later positions are arguments or flag values
      // and must reach the handler unchanged (e.g. `config set trials --help`
      // must surface a parse error, not silently print help).
      const first = result.args[0];
      const wantsHelp =
        first === "help" || first === "--help" || first === "-h";
      if (wantsHelp && result.node.printHelp) {
        await result.node.printHelp(result.absolutePath);
        return { kind: "help" };
      }

      if (result.node.handler) {
        await result.node.handler(result.args, ctx);
      } else if (result.args.length > 0) {
        throw new Error(
          `Unknown subcommand "${result.args[0]}" in ${pretty(
            result.absolutePath,
          )}`,
        );
      } else if (result.node.printHelp) {
        await result.node.printHelp(result.absolutePath);
        return { kind: "help" };
      }

      // Descend on bare (REPL only). `config` and `config core` already
      // printed via their handler; `experiments` printed via printHelp.
      if (
        ctx.contextPath !== null &&
        result.node.children &&
        result.args.length === 0
      ) {
        const target = result.absolutePath;
        const same =
          target.length === ctx.contextPath.length &&
          target.every((s, i) => s === ctx.contextPath![i]);
        if (!same) {
          ctx.setContextPath?.(target);
        }
      }
      return { kind: "ran", absolutePath: result.absolutePath };
    }