mt-lang 0.3.17 → 0.3.20

data/lib/milk_tea/tooling/cli.rb

@@ -146,1852 +146,130 @@ module MilkTea
       1
     end
 
-    private
-
-    def version_request?(command)
-      %w[version --version -V].include?(command)
-    end
-
-    def help_request?(command)
-      command.nil? || %w[help --help -h].include?(command)
-    end
-
-    # Pulls global options that may appear before the first `--` separator out of
-    # @argv so each subcommand parser sees a clean argument list. Stops at `--` so
-    # arguments forwarded to a run target (e.g. `mtc run app -- --verbose`) are
-    # preserved verbatim.
-    def extract_global_options!
-      remaining = []
-      forwarding = false
-      i = 0
-      while i < @argv.length
-        arg = @argv[i]
-        if forwarding
-          remaining << arg
-          i += 1
-          next
-        end
-
-        case arg
-        when "--"
-          forwarding = true
-          remaining << arg
-          i += 1
-        when "-v", "--verbose"
-          @verbose = true
-          i += 1
-        when "-q", "--quiet"
-          @quiet = true
-          i += 1
-        when "--color"
-          value = @argv[i + 1]
-          return invalid_color(value) unless valid_color?(value)
-
-          @color = value.to_sym
-          i += 2
-        when /\A--color=(.*)\z/
-          value = ::Regexp.last_match(1)
-          return invalid_color(value) unless valid_color?(value)
-
-          @color = value.to_sym
-          i += 1
-        else
-          remaining << arg
-          i += 1
-        end
-      end
-      @argv = remaining
-      true
-    end
-
-    def valid_color?(value)
-      %w[auto always never].include?(value)
-    end
-
-    def invalid_color(value)
-      @err.puts("--color must be auto, always, or never#{value ? " (got #{value})" : ''}")
-      false
-    end
-
-    def error_color?(io)
-      case @color
-      when :always then true
-      when :never then false
-      else io.respond_to?(:tty?) && io.tty?
-      end
-    end
-
-    # Prints an informational/progress line unless --quiet was given.
-    def info(message)
-      @out.puts(message) unless @quiet
-    end
-
-
-    def lex_command
-      path = nil
-      sexpr = false
-
-      args = @argv.dup
-      @argv = []
-      until args.empty?
-        arg = args.shift
-        next if arg == "--"
-
-        if arg == "--sexpr"
-          sexpr = true
-          next
-        end
-
-        if path.nil?
-          path = arg
-        else
-          @err.puts("unknown option: #{arg}")
-          print_usage(@err)
-          return 1
-        end
-      end
-
-      unless path
-        @err.puts("missing source file path")
-        print_usage(@err)
-        return 1
-      end
-
-      tokens = Lexer.lex(read_source_file(path), path: path)
-      if sexpr
-        @out.puts(SexprDumper.dump_tokens(tokens))
-      else
-        @out.write(PP.pp(tokens, +""))
-      end
-      0
-    end
-
-    def parse_command
-      sexpr = false
-      args = @argv.dup
-      @argv = []
-      until args.empty?
-        arg = args.shift
-        if arg == "--sexpr"
-          sexpr = true
-          next
-        end
-        @argv << arg
-      end
-
-      unless @argv.any?
-        @err.puts("missing source file path")
-        print_usage(@err)
-        return 1
-      end
-
-      resolution = extract_resolution_flags!
-      input_paths = @argv.dup
-      return 1 unless ensure_known_source_operands!("parse", input_paths)
-
-      paths = expand_source_paths(input_paths)
-      return 0 if print_no_source_files_if_empty(paths, input_paths)
-
-      ensure_current_lockfiles!(paths) if resolution[:frozen]
-
-      multiple = paths.length > 1
-      paths.each_with_index do |path, index|
-        ast = make_module_loader(path, locked: resolution[:locked], platform: ModuleLoader.default_host_platform).load_file(path)
-        if multiple
-          @out.puts("# --- #{path} ---") unless sexpr
-        end
-        if sexpr
-          @out.puts(SexprDumper.dump_ast(ast))
-        else
-          @out.write(PrettyPrinter.format_ast(ast))
-        end
-        @out.puts if multiple && index < paths.length - 1
-      end
-      0
-    end
-
-    def format_command
-      parsed = parse_format_options
-      return 1 unless parsed
-
-      options = parsed[:options]
-      input_paths = parsed[:input_paths]
-
-      if input_paths.empty?
-        @err.puts("missing source file path")
-        print_usage(@err)
-        return 1
-      end
-
-      paths = expand_source_paths(input_paths)
-      return 0 if print_no_source_files_if_empty(paths, input_paths)
-
-      multiple_sources = input_paths.length > 1 || input_paths.any? { |path| File.directory?(path) }
-      if multiple_sources
-        unless options[:check] || options[:write]
-          @err.puts("format on multiple sources requires --check or --write")
-          print_usage(@err)
-          return 1
-        end
-
-        return format_paths(paths, options)
-      end
-
-      path = paths.first
-
-      source = read_source_file(path)
-      format_profile = options[:profile] ? Linter::Profile.new : nil
-      start_time = options[:profile] ? Process.clock_gettime(Process::CLOCK_MONOTONIC) : nil
-      result = Formatter.check_source(source, path: path, mode: options[:mode], max_line_length: options[:max_line_length], profile: format_profile)
-      elapsed_ms = start_time ? ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - start_time) * 1000.0).round(1) : nil
-
-      rc = if options[:check]
-        announce_file_action(path, "format-check")
-        if result.changed
-          info("needs formatting #{path}")
-          1
-        else
-          info("already formatted #{path}")
-          0
-        end
-      elsif options[:write]
-        announce_file_action(path, "format-write")
-        if result.changed
-          File.write(path, result.formatted_source)
-          info("formatted #{path}")
-        else
-          info("already formatted #{path}")
-        end
-        0
-      else
-        @out.write(result.formatted_source)
-        0
-      end
-
-      print_file_profiles([{ path:, total_ms: elapsed_ms, profile: format_profile }], "format") if options[:profile]
-      rc
-    end
-
-    def format_paths(paths, options)
-      format_profiles = []
-      if options[:check]
-        needs_fmt = []
-        paths.each do |p|
-          announce_file_action(p, "format-check")
-          format_profile = options[:profile] ? Linter::Profile.new : nil
-          start_time = options[:profile] ? Process.clock_gettime(Process::CLOCK_MONOTONIC) : nil
-          result = Formatter.check_source(read_source_file(p), path: p, mode: options[:mode], max_line_length: options[:max_line_length], profile: format_profile)
-          elapsed_ms = start_time ? ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - start_time) * 1000.0).round(1) : nil
-          format_profiles << { path: p, total_ms: elapsed_ms, profile: format_profile } if options[:profile]
-          needs_fmt << p if result.changed
-        end
-        print_file_profiles(format_profiles, "format") if options[:profile]
-        if needs_fmt.empty?
-          info("all #{paths.size} file(s) already formatted")
-          return 0
-        end
-        needs_fmt.each { |p| info("needs formatting #{p}") }
-        info("#{needs_fmt.size} file(s) need formatting")
-        return 1
-      end
-
-      # --write
-      changed = 0
-      paths.each do |p|
-        announce_file_action(p, "format-write")
-        format_profile = options[:profile] ? Linter::Profile.new : nil
-        start_time = options[:profile] ? Process.clock_gettime(Process::CLOCK_MONOTONIC) : nil
-        result = Formatter.check_source(read_source_file(p), path: p, mode: options[:mode], max_line_length: options[:max_line_length], profile: format_profile)
-        elapsed_ms = start_time ? ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - start_time) * 1000.0).round(1) : nil
-        format_profiles << { path: p, total_ms: elapsed_ms, profile: format_profile } if options[:profile]
-        if result.changed
-          File.write(p, result.formatted_source)
-          info("formatted #{p}")
-          changed += 1
-        end
-      end
-      print_file_profiles(format_profiles, "format") if options[:profile]
-      info("formatted #{changed} of #{paths.size} file(s)")
-      0
-    end
-
-    def lint_command
-      resolution = { locked: false, frozen: false }
-      select = nil
-      ignore = nil
-      fix = false
-      init = false
-      ignore_generated = false
-      profile = false
-      input_paths = []
-      until @argv.empty?
-        arg = @argv.shift
-        unless arg.start_with?("--")
-          input_paths << arg
-          next
-        end
-
-        flag = arg
-        case flag
-        when "--select"
-          arg = @argv.shift
-          unless arg
-            @err.puts("--select requires a comma-separated list of rule codes")
-            return 1
-          end
-          select = arg.split(",").map(&:strip).to_set
-        when "--ignore"
-          arg = @argv.shift
-          unless arg
-            @err.puts("--ignore requires a comma-separated list of rule codes")
-            return 1
-          end
-          ignore = arg.split(",").map(&:strip).to_set
-        when "--fix"
-          fix = true
-        when "--init"
-          init = true
-        when "--locked"
-          resolution[:locked] = true
-        when "--frozen"
-          resolution[:locked] = true
-          resolution[:frozen] = true
-        when "--ignore-generated"
-          ignore_generated = true
-        when "--timings"
-          profile = true
-        when "--"
-          input_paths.concat(@argv)
-          @argv.clear
-        else
-          @err.puts("unknown lint flag: #{flag}")
-          return 1
-        end
-      end
-
-      if init
-        if input_paths.empty? && !select && !ignore && !fix && !resolution[:locked] && !resolution[:frozen]
-          return init_lint_config
-        end
-
-        @err.puts("--init does not accept source paths or lint options")
-        return 1
-      end
-
-      if input_paths.empty?
-        @err.puts("missing source file path")
-        print_usage(@err)
-        return 1
-      end
-
-      paths = input_paths.flat_map do |path|
-        if File.directory?(path)
-          Dir.glob(File.join(path, "**/*.mt")).sort
-        else
-          [path]
-        end
-      end.uniq
-
-      if paths.empty?
-        label = input_paths.length == 1 ? input_paths.first : input_paths.join(", ")
-        @out.puts("no .mt files found in #{label}")
-        return 0
-      end
-
-      ensure_current_lockfiles!(paths) if resolution[:frozen]
-
-      if fix
-        lint_profiles = []
-        paths.each do |p|
-          announce_file_action(p, "lint-fix")
-          source = read_source_file(p)
-          if ignore_generated && generated_source?(source)
-            @out.puts("ignored generated #{p}")
-            next
-          end
-
-          facts = lint_sema_facts_for(source, p, locked: resolution[:locked])
-          prof = profile ? Linter::Profile.new : nil
-          start_time = profile ? Process.clock_gettime(Process::CLOCK_MONOTONIC) : nil
-
-          fixed = Linter.fix_source(
-            source,
-            path: p,
-            sema_facts: facts,
-            select:,
-            ignore:,
-            profile: prof,
-          )
-          total_ms = start_time ? ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - start_time) * 1000.0).round(1) : nil
-          lint_profiles << { path: p, profile: prof, mode: :pre_fix_scan, total_ms: } if prof
-          if fixed != source
-            File.write(p, fixed)
-            @out.puts("fixed #{p}")
-          end
-        end
-        print_lint_rule_profiles(lint_profiles) if profile
-        print_lint_file_profiles(lint_profiles) if profile
-        return 0
-      end
-
-      lint_profiles = []
-      all_warnings = paths.flat_map do |p|
-        announce_file_action(p, "lint")
-        source = read_source_file(p)
-        next [] if ignore_generated && generated_source?(source)
-
-        facts = lint_sema_facts_for(source, p, locked: resolution[:locked])
-        prof = profile ? Linter::Profile.new : nil
-        start_time = profile ? Process.clock_gettime(Process::CLOCK_MONOTONIC) : nil
-        warnings = Linter.lint_source(source, path: p, select:, ignore:, sema_facts: facts, profile: prof)
-        total_ms = start_time ? ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - start_time) * 1000.0).round(1) : nil
-        lint_profiles << { path: p, profile: prof, mode: :lint, total_ms: } if prof
-        warnings
-      end
-
-      if all_warnings.empty?
-        if input_paths.length == 1
-          info("clean #{input_paths.first}")
-        else
-          info("clean #{paths.size} file(s)")
-        end
-        print_lint_file_profiles(lint_profiles) if profile
-        return 0
-      end
-
-      all_warnings.each do |warning|
-        @out.puts("#{warning.path}:#{warning.line}: #{warning.code}: #{warning.message}")
-      end
-
-      print_lint_rule_profiles(lint_profiles) if profile
-      print_lint_file_profiles(lint_profiles) if profile
-
-      file_count = all_warnings.map(&:path).uniq.size
-      noun = all_warnings.size == 1 ? "warning" : "warnings"
-      files_str = file_count == 1 ? "1 file" : "#{file_count} files"
-      @out.puts("Found #{all_warnings.size} #{noun} in #{files_str}.")
-      1
-    end
-
-    def init_lint_config
-      path = File.join(Dir.pwd, Linter::DEFAULT_CONFIG_FILE_NAME)
-      if File.exist?(path)
-        @err.puts("lint config already exists at #{path}")
-        return 1
-      end
-
-      File.write(path, Linter.default_config_source)
-      info("created #{path}")
-      0
-    end
-
-    def print_lint_rule_profiles(lint_profiles, limit: 12)
-      lint_profiles.each do |entry|
-        profile = entry[:profile]
-        next unless profile
-
-        rows = profile.rule_breakdown(limit:, min_ms: 0.0)
-        rule_total = profile.total_time_ms(prefix: "rule.")
-        overall_total = profile.total_time_ms
-        mode_label = entry[:mode] == :pre_fix_scan ? "pre-fix scan" : "lint scan"
-        @out.puts("lint profile #{entry[:path]} (#{mode_label}): rules=#{format('%.1f', rule_total)}ms total=#{format('%.1f', overall_total)}ms")
-
-        if rows.empty?
-          @out.puts("  no rule timing data captured")
-          next
-        end
-
-        rows.each do |row|
-          share = rule_total.positive? ? ((row[:total_ms] / rule_total) * 100.0) : 0.0
-          @out.puts(
-            "  #{row[:code]}: #{row[:count]}x total=#{format('%.1f', row[:total_ms])}ms avg=#{format('%.2f', row[:avg_ms])}ms share=#{format('%.1f', share)}%"
-          )
-        end
-
-        non_rule_rows = profile.timings_ms
-          .filter_map do |name, total_ms|
-            next if name.start_with?("rule.")
-            next if total_ms < 1.0
-
-            [name, total_ms]
-          end
-          .sort_by { |_name, total_ms| -total_ms }
-          .first(5)
-          .map do |name, total_ms|
-            count = profile.counts[name]
-            "#{name}:#{count}x/#{format('%.1f', total_ms)}ms"
-          end
-
-        @out.puts("  non-rule hot phases: #{non_rule_rows.join(', ')}") unless non_rule_rows.empty?
-      end
-    end
-
-    def print_lint_file_profiles(lint_profiles)
-      file_entries = lint_profiles.filter_map do |entry|
-        total = entry[:total_ms]
-        next unless total
-
-        phases = entry[:profile]&.timings_ms&.reject { |name, _| name.start_with?("rule.") }&.sort_by { |_, ms| -ms }
-        { path: entry[:path], total_ms: total, phases: }
-      end
-      return if file_entries.empty?
-
-      sorted = file_entries.sort_by { |e| -e[:total_ms] }
-      @out.puts
-      @out.puts("Profile (lint): #{sorted.size} file(s)")
-      sorted.each do |entry|
-        phase_str = entry[:phases]&.filter_map { |name, ms| "#{name}: #{format('%.1f', ms)}ms" if ms >= 1.0 }&.join(", ")
-        detail = phase_str && !phase_str.empty? ? " (#{phase_str})" : ""
-        @out.puts("  #{entry[:path]}: #{format('%.1f', entry[:total_ms])}ms#{detail}")
-      end
-      total = sorted.sum { |e| e[:total_ms] }
-      @out.puts("Total: #{format('%.1f', total)}ms")
-    end
-
-    def print_file_profiles(file_profiles, label)
-      sorted = file_profiles.sort_by { |fp| -fp[:total_ms] }
-      return if sorted.empty?
-
-      @out.puts
-      if sorted.size == 1
-        entry = sorted.first
-        phases = entry[:profile]&.timings_ms&.sort_by { |_, ms| -ms }
-        phase_str = phases&.filter_map { |name, ms| "#{name}: #{format('%.1f', ms)}ms" if ms >= 0.1 }&.join(", ")
-        detail = phase_str && !phase_str.empty? ? " (#{phase_str})" : ""
-        @out.puts("#{label} profile #{entry[:path]}: #{format('%.1f', entry[:total_ms])}ms#{detail}")
-        return
-      end
-
-      @out.puts("Profile (#{label}): #{sorted.size} file(s)")
-      sorted.each do |entry|
-        phases = entry[:profile]&.timings_ms&.sort_by { |_, ms| -ms }
-        phase_str = phases&.filter_map { |name, ms| "#{name}: #{format('%.1f', ms)}ms" if ms >= 1.0 }&.join(", ")
-        detail = phase_str && !phase_str.empty? ? " (#{phase_str})" : ""
-        @out.puts("  #{entry[:path]}: #{format('%.1f', entry[:total_ms])}ms#{detail}")
-      end
-      total = sorted.sum { |fp| fp[:total_ms] }
-      @out.puts("Total: #{format('%.1f', total)}ms")
-    end
-
-    def check_command
-      args = @argv.dup
-      @argv = []
-      until args.empty?
-        arg = args.shift
-        @argv << arg
-      end
-
-      unless @argv.any?
-        @err.puts("missing source file path")
-        print_usage(@err)
-        return 1
-      end
-
-      resolution = extract_resolution_flags!
-      input_paths = @argv.dup
-      return 1 unless ensure_known_source_operands!("check", input_paths)
-
-      paths = expand_source_paths(input_paths)
-      return 0 if print_no_source_files_if_empty(paths, input_paths)
-
-      ensure_current_lockfiles!(paths) if resolution[:frozen]
-
-      all_diagnostics = []
-      paths.each do |path|
-        diagnostics, module_name, closure_errors = check_single_reporting_all(path, locked: resolution[:locked])
-        closure_errors = [] if paths.length > 1
-        diagnostics = sort_by_location(diagnostics)
-
-        if diagnostics.any? || closure_errors.any?
-          main_source = read_source_file(path)
-          main_abs = File.expand_path(path)
-          diagnostics.each do |d|
-            same_file = !d.respond_to?(:path) || d.path.nil? || File.expand_path(d.path) == main_abs
-            source = same_file ? main_source : nil
-            @err.puts(ErrorFormatter.format(d, source:, color: error_color?(@err)))
-          end
-          closure_errors.each do |d|
-            same_file = !d.respond_to?(:path) || d.path.nil? || File.expand_path(d.path) == main_abs
-            source = same_file ? main_source : nil
-            @err.puts(ErrorFormatter.format(d, source:, color: error_color?(@err)))
-          end
-          all_diagnostics.concat(diagnostics)
-          all_diagnostics.concat(closure_errors)
-        elsif module_name
-          info("checked #{path} as #{module_name}")
-        end
-      end
-
-      return 0 if all_diagnostics.empty?
-
-      error_count = all_diagnostics.count { |d| !d.respond_to?(:severity) || d.severity == :error }
-      warning_count = all_diagnostics.count { |d| d.respond_to?(:severity) && d.severity == :warning }
-      info_count = all_diagnostics.count { |d| d.respond_to?(:severity) && (d.severity == :info || d.severity == :hint) }
-
-      @err.puts
-      parts = []
-      parts << "#{error_count} #{error_count == 1 ? 'error' : 'errors'}" if error_count > 0
-      parts << "#{warning_count} #{warning_count == 1 ? 'warning' : 'warnings'}" if warning_count > 0
-      parts << "#{info_count} #{info_count == 1 ? 'note' : 'notes'}" if info_count > 0
-      body = parts.join("; ")
-      if error_count > 0
-        @err.puts("#{body} found")
-      elsif warning_count > 0
-        @err.puts("#{body}")
-      end
-      final_error_count = error_count + (resolution[:warnings_as_errors] ? warning_count : 0)
-      final_error_count > 0 ? 1 : 0
-    end
-
-    def check_single_reporting_all(path, locked: false)
-      loader = make_module_loader(path, locked:, platform: ModuleLoader.default_host_platform)
-      resolved_path = File.expand_path(path)
-      ast = loader.load_file(resolved_path)
-      module_name = ast.module_name.to_s
-
-      import_result = loader.send(:imported_modules_for_ast_collecting_errors, ast, importer_path: resolved_path)
-      errors = import_result.errors.dup
-
-      analysis = nil
-      begin
-        result = SemanticAnalyzer.check_collecting_errors(ast, imported_modules: import_result.modules, path: resolved_path)
-        errors.concat(result[:errors])
-        analysis = result[:analysis]
-      rescue SemanticError => e
-        errors << e
-      end
-
-      if analysis && errors.empty?
-        source = read_source_file(path)
-        warnings = Linter.lint_source(source, path: resolved_path, sema_facts: analysis, lint_tier: :full)
-        errors.concat(warnings)
-      end
-
-      closure_errors = loader.collecting_path_errors.values.flatten.compact
-      [errors, module_name, closure_errors]
-    rescue ModuleLoadError, PackageLockError, SemanticError => e
-      [[e], nil, []]
-    end
-
-    def sort_by_location(errors)
-      errors.sort_by do |e|
-        actual = e.respond_to?(:error) ? e.error : e
-        line = actual.respond_to?(:line) ? actual.line.to_i : 0
-        column = actual.respond_to?(:column) ? actual.column.to_i : 0
-        [line, column]
-      end
-    end
-
-    def lower_command
-      sexpr = false
-      args = @argv.dup
-      @argv = []
-      until args.empty?
-        arg = args.shift
-        if arg == "--sexpr"
-          sexpr = true
-          next
-        end
-        @argv << arg
-      end
-
-      unless @argv.any?
-        @err.puts("missing source file path")
-        print_usage(@err)
-        return 1
-      end
-
-      resolution = extract_resolution_flags!
-      input_paths = @argv.dup
-      return 1 unless ensure_known_source_operands!("lower", input_paths)
-
-      paths = expand_source_paths(input_paths)
-      return 0 if print_no_source_files_if_empty(paths, input_paths)
-
-      ensure_current_lockfiles!(paths) if resolution[:frozen]
-
-      multiple = paths.length > 1
-      paths.each_with_index do |path, index|
-        program = make_module_loader(path, locked: resolution[:locked], platform: ModuleLoader.default_host_platform).check_program(path)
-        if multiple
-          @out.puts("# --- #{path} ---") unless sexpr
-        end
-        if sexpr
-          @out.puts(SexprDumper.dump_ir(Lowering.lower(program)))
-        else
-          @out.write(PrettyPrinter.format_ir(Lowering.lower(program)))
-        end
-      end
-      0
-    end
-
-    def emit_c_command
-      args = @argv.dup
-      @argv = []
-      until args.empty?
-        arg = args.shift
-        @argv << arg
-      end
-
-      unless @argv.any?
-        @err.puts("missing source file path")
-        print_usage(@err)
-        return 1
-      end
-
-      resolution = extract_resolution_flags!
-      input_paths = @argv.dup
-      return 1 unless ensure_known_source_operands!("emit-c", input_paths)
-
-      program_paths = input_paths.map { |p| resolve_program_path(p) }
-      return 1 if program_paths.include?(nil)
-
-      ensure_current_lockfiles!(input_paths) if resolution[:frozen]
-
-      multiple = program_paths.length > 1
-      program_paths.each_with_index do |path, index|
-        program = make_module_loader(path, locked: resolution[:locked], platform: ModuleLoader.default_host_platform).check_program(path)
-        if multiple
-          @out.puts("/* --- #{path} --- */")
-        end
-        @out.write(CBackend.generate_c(Lowering.lower(program), emit_line_directives: false))
-        @out.puts if multiple && index < program_paths.length - 1
-      end
-      0
-    end
-
-    def resolve_program_path(path)
-      return path unless File.directory?(path)
-
-      manifest_path = File.join(path, "package.toml")
-      unless File.file?(manifest_path)
-        @err.puts("no package.toml found in #{path}")
-        return nil
-      end
-
-      manifest = PackageManifest.load(path)
-      entry_path = manifest.source_path
-      unless entry_path && File.file?(entry_path)
-        @err.puts("no build entry found for #{path}")
-        return nil
-      end
-
-      entry_path
-    rescue PackageManifestError => e
-      @err.puts("failed to load package manifest for #{path}: #{e.message}")
-      nil
-    end
-
-    def build_command
-      path, options = extract_path_and_options(allow_clean: true)
-      return 1 unless path
-
-      if options.delete(:clean)
-        cleaned_path = Build.clean(path, output_path: options[:output_path], profile: options[:profile], platform: options[:platform], bundle: options[:bundle], archive: options[:archive])
-        info("cleaned #{cleaned_path}")
-        return 0
-      end
-
-      frozen = options.delete(:frozen)
-      ensure_current_lockfile!(path) if frozen
-      locked = options.delete(:locked)
-      bundle = options[:bundle]
-      package_graph = package_graph_for(path, locked:)
-      result = Build.build(path, module_roots: module_roots_for(path, locked:), package_graph:, frontend: @build_frontend, **options.except(:timings))
-      if bundle
-        info("built #{path} -> #{File.dirname(result.output_path)}")
-        info("entry executable #{result.output_path}")
-        info("  [cached]") if result.cached
-        info("archive #{result.archive_path}") if result.archive_path
-      elsif result.cached
-        info("built #{path} -> #{result.output_path}  [cached]")
-      else
-        info("built #{path} -> #{result.output_path}")
-      end
-      info("saved C to #{result.c_path}") if result.c_path
-      0
-    end
-
-    def test_command
-      limits = extract_test_limit_flags!
-      return 1 unless limits
-
-      @test_timeout_seconds, @test_memory_bytes, @test_jobs, @test_sanitize, @test_filter, @test_format = limits
-
-      path, options = extract_path_and_options
-      return 1 unless path
-
-      frozen = options.delete(:frozen)
-      ensure_current_lockfile!(path) if frozen
-      locked = options.delete(:locked)
-
-      return dispatch_test_run(path, options:, locked:) if @test_format == :human
-
-      buffer = StringIO.new
-      real_out = @out
-      real_err = @err
-      @out = buffer
-      @err = buffer
-      begin
-        exit_code = dispatch_test_run(path, options:, locked:)
-      ensure
-        @out = real_out
-        @err = real_err
-      end
-
-      emit_machine_results(parse_test_output(buffer.string), @test_format, real_out)
-      exit_code
-    end
-
-    def dispatch_test_run(path, options:, locked:)
-      if File.directory?(path)
-        run_test_directory(path, options:, locked:)
-      elsif File.file?(path)
-        if compile_fail_fixture?(File.read(path))
-          run_compile_fail_test(path) ? 0 : 1
-        else
-          run_test_file(path, options:, locked:)
-        end
-      else
-        @err.puts("mtc test: not a file or directory: #{path}")
-        1
-      end
-    end
-
-    def extract_test_limit_flags!
-      timeout_seconds = TEST_RUN_TIMEOUT_SECONDS
-      memory_bytes = TEST_RUN_MEMORY_LIMIT_BYTES
-      jobs = 1
-      sanitize = false
-      filter = nil
-      format = :human
-      remaining = []
-      until @argv.empty?
-        arg = @argv.shift
-        case arg
-        when "--timeout"
-          value = @argv.shift
-          seconds = value && Integer(value, exception: false)
-          unless seconds&.positive?
-            @err.puts("--timeout requires a positive integer (seconds)")
-            return nil
-          end
-          timeout_seconds = seconds
-        when "--mem"
-          value = @argv.shift
-          megabytes = value && Integer(value, exception: false)
-          unless megabytes&.positive?
-            @err.puts("--mem requires a positive integer (megabytes)")
-            return nil
-          end
-          memory_bytes = megabytes * 1024 * 1024
-        when "--jobs"
-          value = @argv.shift
-          count = value && Integer(value, exception: false)
-          unless count&.positive?
-            @err.puts("--jobs requires a positive integer")
-            return nil
-          end
-          jobs = count
-        when "--sanitize"
-          sanitize = true
-        when "-n", "--name"
-          value = @argv.shift
-          unless value
-            @err.puts("-n requires a name substring")
-            return nil
-          end
-          filter = value
-        when "--format"
-          value = @argv.shift
-          unless %w[human tap junit].include?(value)
-            @err.puts("--format must be human, tap, or junit")
-            return nil
-          end
-          format = value.to_sym
-        when "--"
-          remaining << arg
-          remaining.concat(@argv)
-          @argv.clear
-        else
-          remaining << arg
-        end
-      end
-      @argv.replace(remaining)
-      [timeout_seconds, memory_bytes, jobs, sanitize, filter, format]
-    end
-
-    TestResult = Data.define(:name, :status, :detail)
-
-    def parse_test_output(text)
-      results = []
-      current_file = nil
-      text.each_line do |raw|
-        line = raw.chomp
-        case line
-        when /\A# (.+)\z/
-          current_file = ::Regexp.last_match(1)
-        when /\Aok   - (.+)\z/
-          results << TestResult.new(name: ::Regexp.last_match(1), status: :pass, detail: nil)
-        when /\Askip - (.+?)(?:: (.*))?\z/
-          results << TestResult.new(name: ::Regexp.last_match(1), status: :skip, detail: ::Regexp.last_match(2))
-        when /\AFAIL - (.+?)(?:: (.*))?\z/
-          results << TestResult.new(name: ::Regexp.last_match(1), status: :fail, detail: ::Regexp.last_match(2))
-        when /\AFAILED - (.+?) \(build error\)\z/
-          results << TestResult.new(name: "#{::Regexp.last_match(1)} (build error)", status: :fail, detail: "build error")
-        when /\Atest run (?:timed out|crashed)/, /\ASUMMARY: \w+Sanitizer/
-          results << TestResult.new(name: "#{current_file || 'test'} (#{line})", status: :fail, detail: line)
-        end
-      end
-      results
-    end
-
-    def emit_machine_results(results, format, out)
-      case format
-      when :tap then emit_tap(results, out)
-      when :junit then emit_junit(results, out)
-      end
-    end
-
-    def emit_tap(results, out)
-      out.puts("TAP version 13")
-      out.puts("1..#{results.length}")
-      results.each_with_index do |result, index|
-        number = index + 1
-        case result.status
-        when :pass
-          out.puts("ok #{number} - #{result.name}")
-        when :skip
-          out.puts("ok #{number} - #{result.name} # SKIP#{result.detail ? " #{result.detail}" : ''}")
-        when :fail
-          out.puts("not ok #{number} - #{result.name}")
-          next unless result.detail
-
-          out.puts("  ---")
-          out.puts("  message: #{result.detail}")
-          out.puts("  ...")
-        end
-      end
-    end
-
-    def emit_junit(results, out)
-      failures = results.count { |result| result.status == :fail }
-      skipped = results.count { |result| result.status == :skip }
-      out.puts(%(<?xml version="1.0" encoding="UTF-8"?>))
-      out.puts(%(<testsuites tests="#{results.length}" failures="#{failures}" skipped="#{skipped}">))
-      out.puts(%(  <testsuite name="mtc test" tests="#{results.length}" failures="#{failures}" skipped="#{skipped}">))
-      results.each do |result|
-        name = xml_escape(result.name)
-        case result.status
-        when :pass
-          out.puts(%(    <testcase name="#{name}"/>))
-        when :skip
-          out.puts(%(    <testcase name="#{name}"><skipped/></testcase>))
-        when :fail
-          out.puts(%(    <testcase name="#{name}"><failure message="#{xml_escape(result.detail || 'failed')}"/></testcase>))
-        end
-      end
-      out.puts("  </testsuite>")
-      out.puts("</testsuites>")
-    end
-
-    def xml_escape(value)
-      value.to_s.gsub("&", "&amp;").gsub("<", "&lt;").gsub(">", "&gt;").gsub('"', "&quot;")
-    end
-
-    def run_test_directory(directory, options:, locked:)
-      test_files = discover_test_files(directory)
-      if test_files.empty?
-        if @test_filter
-          @out.puts("no tests matched -n '#{@test_filter}' under #{directory}")
-        else
-          @out.puts("no @[test] functions or # expect-error: fixtures found under #{directory}")
-        end
-        return 0
-      end
-
-      jobs = @test_jobs || 1
-      return run_test_files_parallel(test_files, jobs:, options:, locked:) if jobs > 1 && Process.respond_to?(:fork)
-
-      failed = 0
-      test_files.each do |file, kind|
-        @out.puts("# #{file}")
-        @out.flush if @out.respond_to?(:flush)
-        failed += 1 unless run_classified_file(file, kind, options:, locked:).zero?
-      end
-
-      @out.puts("")
-      @out.puts("#{test_files.length} test file(s), #{failed} failed")
-      failed.zero? ? 0 : 1
-    end
-
-    def run_classified_file(file, kind, options:, locked:)
-      if kind == :compile_fail
-        run_compile_fail_test(file) ? 0 : 1
-      else
-        run_test_file_guarded(file, options:, locked:)
-      end
-    end
-
-    def run_compile_fail_test(path)
-      source = File.read(path)
-      expectations = extract_expect_error_directives(source)
-      messages = compile_fail_diagnostics(path)
-
-      if messages.empty?
-        @out.puts("FAIL - #{path} (compile-fail): expected a compile error, but it compiled cleanly")
-        @out.flush if @out.respond_to?(:flush)
-        return false
-      end
-
-      unmatched = expectations.find { |expected| messages.none? { |message| message.include?(expected) } }
-      if unmatched
-        @out.puts("FAIL - #{path} (compile-fail): no diagnostic matched #{unmatched.inspect}")
-        @out.flush if @out.respond_to?(:flush)
-        return false
-      end
-
-      @out.puts("ok   - #{path} (compile-fail)")
-      @out.flush if @out.respond_to?(:flush)
-      true
-    end
-
-    def extract_expect_error_directives(source)
-      source.each_line.filter_map do |line|
-        match = line.match(/^\s*#\s*expect-error:\s*(.+?)\s*$/)
-        match && match[1]
-      end
-    end
-
-    def compile_fail_diagnostics(path)
-      errors, = check_single_reporting_all(path, locked: false)
-      errors
-        .select { |diagnostic| !diagnostic.respond_to?(:severity) || diagnostic.severity == :error }
-        .map { |diagnostic| ErrorFormatter.format(diagnostic, color: false) }
-    rescue StandardError => e
-      raise unless handled_cli_error?(e)
-
-      [ErrorFormatter.format(e, color: false)]
-    end
-
-    def run_test_file_guarded(file, options:, locked:)
-      run_test_file(file, options:, locked:)
-    rescue StandardError => e
-      raise unless handled_cli_error?(e)
-
-      @err.puts("FAILED - #{file} (build error)")
-      @err.puts(ErrorFormatter.format(e, color: error_color?(@err)))
-      1
-    end
-
-    def run_test_files_parallel(test_files, jobs:, options:, locked:)
-      results = Array.new(test_files.length)
-      result_paths = {}
-      active = {}
-      cursor = 0
-
-      while cursor < test_files.length || !active.empty?
-        while active.size < jobs && cursor < test_files.length
-          index = cursor
-          cursor += 1
-          result_path = File.join(Dir.tmpdir, "mttest_result_#{Process.pid}_#{index}")
-          result_paths[index] = result_path
-          pid = fork do
-            captured = StringIO.new
-            @out = captured
-            @err = captured
-            file, kind = test_files[index]
-            code = run_classified_file(file, kind, options:, locked:)
-            File.binwrite(result_path, [code].pack("N") + captured.string)
-            exit!(0)
-          end
-          active[pid] = index
-        end
-
-        finished_pid, = Process.wait2
-        index = active.delete(finished_pid)
-        next unless index
-
-        path = result_paths[index]
-        data = begin
-          File.binread(path)
-        rescue StandardError
-          (+"").b
-        end
-        File.delete(path) if File.exist?(path)
-        results[index] =
-          if data.bytesize >= 4
-            [data[0, 4].unpack1("N"), data.byteslice(4..).force_encoding(Encoding::UTF_8)]
-          else
-            [1, +""]
-          end
-      end
-
-      failed = 0
-      test_files.each_with_index do |(file, _kind), index|
-        code, output = results[index]
-        @out.puts("# #{file}")
-        @out.write(output.to_s)
-        failed += 1 unless code&.zero?
-      end
-      @out.flush if @out.respond_to?(:flush)
-      @out.puts("")
-      @out.puts("#{test_files.length} test file(s), #{failed} failed")
-      failed.zero? ? 0 : 1
-    end
-
-    def discover_test_files(directory)
-      Dir.glob(File.join(directory, "**", "*.mt")).sort.filter_map do |file|
-        next if File.basename(file).start_with?("__mt_test_runner_")
-
-        kind = classify_test_file(file)
-        kind && [file, kind]
-      end
-    end
-
-    def classify_test_file(file)
-      source = File.read(file)
-      if compile_fail_fixture?(source)
-        return nil if @test_filter && !File.basename(file, ".mt").include?(@test_filter)
-
-        return :compile_fail
-      end
-
-      ast = begin
-        MilkTea::Parser.parse(source, path: file)
-      rescue ParseError
-        return nil
-      end
-      has_match = ast.declarations.any? do |decl|
-        decl.is_a?(AST::FunctionDef) && test_attribute?(decl) && matches_filter?(decl.name)
-      end
-      has_match ? :test : nil
-    end
-
-    def compile_fail_fixture?(source)
-      source.match?(/^\s*#\s*expect-error:/)
-    end
-
-    def test_attribute?(decl)
-      decl.attributes.any? { |attribute| attribute.name.parts == ["test"] }
-    end
-
-    def matches_filter?(name)
-      @test_filter.nil? || name.include?(@test_filter)
-    end
-
-    def run_test_file(path, options:, locked:)
-      source = File.read(path)
-      ast = MilkTea::Parser.parse(source, path:)
-
-      if ast.declarations.any? { |decl| decl.is_a?(AST::FunctionDef) && decl.name == "main" }
-        @err.puts("a test file must not define 'main': #{path}")
-        return 1
-      end
-
-      tests = ast.declarations.select { |decl| decl.is_a?(AST::FunctionDef) && test_attribute?(decl) }
-
-      if tests.empty?
-        @out.puts("no @[test] functions found in #{path}")
-        return 0
-      end
-
-      tests = tests.select { |test| matches_filter?(test.name) }
-      return 0 if tests.empty?
-
-      invalid = tests.find { |test| !test.params.empty? }
-      if invalid
-        @err.puts("@[test] function '#{invalid.name}' must take no parameters")
-        return 1
-      end
-
-      testing_import = ast.imports.find { |import| import.path.parts == %w[std testing] }
-      unless testing_import
-        @err.puts("a test file must import std.testing: #{path}")
-        return 1
-      end
-      testing_alias = testing_import.alias_name || testing_import.path.parts.last
-
-      death_tests, normal_tests = tests.partition { |test| expect_fatal_attribute?(test) }
-
-      exit_code = 0
-
-      unless normal_tests.empty?
-        runner_source = source.dup
-        runner_source << "\n\n" << test_runner_main(testing_alias, normal_tests.map(&:name))
-        exit_code = run_synthesized_tests(path, runner_source, options:, locked:)
-      end
-
-      death_tests.each do |death_test|
-        exit_code = 1 unless run_death_test(path, source, death_test.name, options:, locked:)
-      end
-
-      exit_code
-    end
-
-    def expect_fatal_attribute?(decl)
-      decl.attributes.any? { |attribute| attribute.name.parts == ["expect_fatal"] }
-    end
-
-    def run_death_test(source_path, source, test_name, options:, locked:)
-      runner_source = source.dup
-      runner_source << "\n\n" << death_test_runner_main(test_name)
-      classification = with_synthesized_binary(source_path, runner_source, options:, locked:) do |binary_path|
-        classify_death_test(binary_path)
-      end
-
-      passed = classification == :aborted
-      line =
-        if passed
-          "ok   - #{test_name} (expect_fatal)"
-        elsif classification == :timed_out
-          "FAIL - #{test_name} (expect_fatal): timed out"
-        else
-          "FAIL - #{test_name} (expect_fatal): expected a fatal abort, but the test returned"
-        end
-      @out.puts(line)
-      @out.flush if @out.respond_to?(:flush)
-      passed
-    end
-
-    def classify_death_test(binary_path)
-      _output, status, timed_out = spawn_sandboxed(binary_path)
-      return :timed_out if timed_out
-      return :returned if status&.exited? && status.exitstatus&.zero?
-
-      :aborted
-    end
-
-    def death_test_runner_main(test_name)
-      [
-        "function main() -> int:",
-        "    match #{test_name}():",
-        "        Result.success:",
-        "            return 0",
-        "        Result.failure:",
-        "            return 0",
-      ].join("\n") + "\n"
-    end
-
-    def test_runner_main(testing_alias, test_names)
-      lines = ["function main() -> int:"]
-      lines << "    var __mt_test_stats = #{testing_alias}.Stats.create()"
-      test_names.each do |name|
-        lines << "    __mt_test_stats = #{testing_alias}.record(__mt_test_stats, #{name.inspect}, #{name}())"
-      end
-      lines << "    return #{testing_alias}.summarize(__mt_test_stats)"
-      lines.join("\n") + "\n"
-    end
-
-    def run_synthesized_tests(source_path, runner_source, options:, locked:)
-      with_synthesized_binary(source_path, runner_source, options:, locked:) do |binary_path|
-        run_test_binary(binary_path)
-      end
-    end
-
-    def with_synthesized_binary(source_path, runner_source, options:, locked:)
-      directory = File.dirname(File.expand_path(source_path))
-      runner_path = File.join(directory, "__mt_test_runner_#{Process.pid}.mt")
-      binary_path = File.join(Dir.tmpdir, "__mt_test_runner_#{Process.pid}")
-
-      File.write(runner_path, runner_source)
-      begin
-        build_opts = options.except(:timings, :output_path, :bundle, :archive)
-        build_opts[:debug_guards] = false
-        Build.build(
-          runner_path,
-          output_path: binary_path,
-          module_roots: module_roots_for(source_path, locked:),
-          package_graph: package_graph_for(source_path, locked:),
-          frontend: @build_frontend,
-          sanitize: @test_sanitize,
-          **build_opts,
-        )
-        yield binary_path
-      ensure
-        File.delete(runner_path) if File.exist?(runner_path)
-        File.delete(binary_path) if File.exist?(binary_path)
-      end
-    end
-
-    TEST_RUN_TIMEOUT_SECONDS = 30
-    TEST_RUN_MEMORY_LIMIT_BYTES = 1024 * 1024 * 1024
-
-    def run_test_binary(binary_path)
-      output, status, timed_out = spawn_sandboxed(binary_path)
-      @out.write(output)
-      @out.flush if @out.respond_to?(:flush)
-
-      if timed_out
-        @err.puts("test run timed out after #{@test_timeout_seconds || TEST_RUN_TIMEOUT_SECONDS}s")
-        return 1
-      end
-      if status&.signaled?
-        @err.puts("test run crashed (signal #{status.termsig})")
-        return 1
-      end
-
-      status&.exitstatus || 1
-    end
-
-    def spawn_sandboxed(binary_path)
-      timeout_seconds = @test_timeout_seconds || TEST_RUN_TIMEOUT_SECONDS
-      memory_bytes = @test_memory_bytes || TEST_RUN_MEMORY_LIMIT_BYTES
-      reader, writer = IO.pipe
-      spawn_options = { out: writer, err: writer, pgroup: true }
-      spawn_options[:rlimit_as] = memory_bytes unless @test_sanitize
-      pid = Process.spawn(binary_path, **spawn_options)
-      writer.close
-
-      status = nil
-      timed_out = false
-      begin
-        Timeout.timeout(timeout_seconds) { _, status = Process.wait2(pid) }
-      rescue Timeout::Error
-        timed_out = true
-        begin
-          Process.kill("-KILL", Process.getpgid(pid))
-          Process.wait(pid)
-        rescue StandardError
-          nil
-        end
-      end
-
-      output = reader.read
-      reader.close
-      [output, status, timed_out]
-    end
-
-    def run_command
-      path, options = extract_path_and_options
-      return 1 unless path
-
-      run_and_print_result(path, options)
-    end
-
-    def app_command
-      options = parse_build_options
-      return 1 unless options
-
-      module_name = @argv.shift
-      unless module_name
-        @err.puts("missing module name")
-        print_usage(@err)
-        return 1
-      end
-
-      path = resolve_app_module(module_name)
-      unless path
-        @err.puts("run-module module not found: #{module_name}")
-        return 1
-      end
-
-      frozen = options.delete(:frozen)
-      ensure_current_lockfile!(path) if frozen
-
-      run_and_print_result(path, options)
-    end
-
-    def extract_path_and_options(allow_clean: false)
-      options = parse_build_options(allow_clean:)
-      return nil unless options
-
-      path = @argv.shift
-      unless path
-        if File.file?(File.join(Dir.pwd, "package.toml"))
-          path = Dir.pwd
-        else
-          @err.puts("missing source file path")
-          print_usage(@err)
-          return nil
-        end
-      end
-
-      [path, options]
-    end
-
-    def run_and_print_result(path, options)
-      frozen = options.delete(:frozen)
-      ensure_current_lockfile!(path) if frozen
-      locked = options.delete(:locked)
-      package_graph = package_graph_for(path, locked:)
-      preview_notice_emitted = false
-      preview_started = lambda do |message|
-        preview_notice_emitted = true
-        @out.write(message)
-        @out.flush if @out.respond_to?(:flush)
-      end
-
-      result = Run.run(
-        path,
-        module_roots: module_roots_for(path, locked:),
-        package_graph:,
-        frontend: @build_frontend,
-        preview_started:,
-        argv: @argv.dup,
-        **options.except(:timings)
-      )
-      unless @out.equal?($stdout) || preview_notice_emitted
-        @out.write(result.stdout)
-      end
-      @out.flush if @out.respond_to?(:flush)
-      @err.write(result.stderr) unless @err.equal?($stderr)
-      info("[cached]") if result.cached
-      result.exit_status
-    end
-
-    def resolve_app_module(name)
-      relative = name.tr(".", "/").sub(%r{^/}, "") + ".mt"
-
-      module_roots_for(Dir.pwd).each do |root|
-        candidate = File.join(root, "std", relative)
-        return File.expand_path(candidate) if File.file?(candidate)
-
-        candidate = File.join(root, relative)
-        return File.expand_path(candidate) if File.file?(candidate)
-      end
-
-      nil
-    end
+    require_relative "cli/commands/command_base"
+    require_relative "cli/commands/lex"
+    require_relative "cli/commands/parse"
+    require_relative "cli/commands/format"
+    require_relative "cli/commands/lint"
+    require_relative "cli/commands/check"
+    require_relative "cli/commands/lower"
+    require_relative "cli/commands/emit_c"
+    require_relative "cli/commands/build"
+    require_relative "cli/commands/test"
+    require_relative "cli/commands/run"
+    require_relative "cli/commands/new"
+    require_relative "cli/commands/debug"
+    require_relative "cli/commands/toolchain"
+    require_relative "cli/commands/deps"
+    require_relative "cli/commands/bindgen"
+    require_relative "cli/commands/cache"
+    require_relative "cli/commands/docs"
+    require_relative "cli/commands/snapshot"
+    require_relative "cli/commands/lsp"
+    require_relative "cli/commands/dap"
+    require_relative "cli/commands/completions"
+
+    include CommandBase
+    include CommandLex
+    include CommandParse
+    include CommandFormat
+    include CommandLint
+    include CommandCheck
+    include CommandLower
+    include CommandEmitC
+    include CommandBuild
+    include CommandTest
+    include CommandRun
+    include CommandNew
+    include CommandDebug
+    include CommandToolchain
+    include CommandDeps
+    include CommandBindgen
+    include CommandCache
+    include CommandDocs
+    include CommandSnapshot
+    include CommandLsp
+    include CommandDap
+    include CommandCompletions
 
-    def new_command
-      name = @argv.shift
-      unless name
-        @err.puts("missing project name")
-        print_usage(@err)
-        return 1
-      end
-
-      if @argv.any?
-        @err.puts("unknown new option #{@argv.first}")
-        print_usage(@err)
-        return 1
-      end
-
-      result = ProjectScaffold.create(name)
-      info("created #{result.root_path}")
-      0
-    end
-
-    def deps_command
-      PackageManagerCLI.start(
-        @argv,
-        out: @out,
-        err: @err,
-        help_printer: method(:print_deps_help),
-        services: package_services,
-      )
-    end
-
-    def docs_command
-      port = nil
-      open_flag = false
-
-      while (arg = @argv.first)
-        case arg
-        when "--port", "-p"
-          @argv.shift
-          port = @argv.shift.to_i
-          port = nil if port <= 0 || port > 65535
-        when "--open", "-o"
-          open_flag = true
-          @argv.shift
-        else
-          break
-        end
-      end
-
-      port = resolve_docs_port(port)
-
-      DocsApp.set :port, port
-      DocsApp.set :bind, "127.0.0.1"
-      DocsApp.set :environment, :production
-      DocsApp.set :server, :puma
-
-      url = "http://127.0.0.1:#{port}/"
-
-      @out.puts("Serving Milk Tea docs at #{url}")
-      @out.puts("Press Ctrl+C to stop.")
-
-      if open_flag
-        open_browser(url)
-      end
+    private
 
-      DocsApp.run!
-      0
-    rescue Interrupt
-      0
+    def version_request?(command)
+      %w[version --version -V].include?(command)
     end
 
-    def resolve_docs_port(preferred)
-      return preferred if preferred
-
-      server = TCPServer.new("127.0.0.1", 0)
-      port = server.addr[1]
-      server.close
-      port
-    rescue StandardError
-      4567
+    def help_request?(command)
+      command.nil? || %w[help --help -h].include?(command)
     end
 
-    def snapshot_command
-      input_path = nil
-      theme_path = nil
-      output_path = nil
-      textmate_only = false
-
-      until @argv.empty?
-        arg = @argv.first
-        case arg
-        when "--theme", "-t"
-          @argv.shift
-          theme_path = @argv.shift
-          unless theme_path
-            @err.puts("snapshot: missing value for --theme")
-            return 1
-          end
-        when "--output", "-o"
-          @argv.shift
-          output_path = @argv.shift
-          unless output_path
-            @err.puts("snapshot: missing value for --output")
-            return 1
-          end
-        when "--textmate-only"
-          @argv.shift
-          textmate_only = true
-        else
-          if arg.start_with?("-")
-            @err.puts("snapshot: unknown option #{arg}")
-            return 1
-          end
-          unless input_path
-            input_path = @argv.shift
-          else
-            @err.puts("snapshot: unexpected argument #{@argv.shift}")
-            return 1
-          end
-        end
-      end
-
-      unless input_path
-        @err.puts("snapshot: missing source file path")
-        print_usage(@err)
-        return 1
-      end
-
-      unless File.file?(input_path)
-        @err.puts("snapshot: source file not found: #{input_path}")
-        return 1
-      end
-
-      input_path = File.expand_path(input_path)
-      theme_path = File.expand_path(theme_path) if theme_path
-      output_path = File.expand_path(output_path) if output_path
-
-      if theme_path && !File.file?(theme_path)
-        @err.puts("snapshot: theme file not found: #{theme_path}")
-        return 1
-      end
-
-      snapshot_script = MilkTea.root.join("bindings/vscode/scripts/snapshot.js").to_s
-      unless File.file?(snapshot_script)
-        @err.puts("snapshot: internal script not found at #{snapshot_script}")
-        return 1
-      end
-
-      args = ["node", snapshot_script, input_path]
-      args.push("-t", theme_path) if theme_path
-      args.push("-o", output_path) if output_path
-
-      semantic_result = nil
-      unless textmate_only
-        begin
-          semantic_result = MilkTea::LSP::Server.semantic_tokens_for_path(input_path)
-        rescue => e
-          @err.puts("snapshot: semantic analysis skipped: #{e.message}")
-        end
-      end
-
-      if semantic_result && semantic_result[:entries] && !semantic_result[:entries].empty?
-        source = File.read(input_path)
-        lines = source.split("\n", -1)
-        semantic_result[:entries].each do |entry|
-          byte_start = entry[:startChar]
-          byte_len = entry[:length]
-          line_text = lines[entry[:line]]
-          unless line_text && byte_start && byte_len
-            entry[:startChar] = 0
-            entry[:length] = 0
-            next
-          end
-          char_start = line_text.byteslice(0, byte_start).length
-          char_length = line_text.byteslice(byte_start, byte_len).length
-          char_length = line_text.length - char_start if char_start + char_length > line_text.length
-          entry[:startChar] = char_start
-          entry[:length] = char_length
+    # Pulls global options that may appear before the first `--` separator out of
+    # @argv so each subcommand parser sees a clean argument list. Stops at `--` so
+    # arguments forwarded to a run target (e.g. `mtc run app -- --verbose`) are
+    # preserved verbatim.
+    def extract_global_options!
+      remaining = []
+      forwarding = false
+      i = 0
+      while i < @argv.length
+        arg = @argv[i]
+        if forwarding
+          remaining << arg
+          i += 1
+          next
         end
 
-        temp = Tempfile.new(["mt_semantic", ".json"])
-        temp.write(JSON.generate(semantic_result[:entries]))
-        temp.close
-        args.push("-s", temp.path)
-        system(*args)
-        temp.unlink
-      else
-        system(*args)
-      end
-      $?.success? ? 0 : 1
-    end
-
-    def lsp_command
-      log_level = nil
-
-      until @argv.empty?
-        arg = @argv.shift
         case arg
-        when "--log-level"
-          log_level = @argv.shift&.downcase
-          unless log_level && %w[trace debug info warn error].include?(log_level)
-            @err.puts("lsp: invalid --log-level #{log_level.inspect} (expected trace, debug, info, warn, or error)")
-            return 1
-          end
-        when /\A--log-level=(.+)\z/
-          log_level = ::Regexp.last_match(1).downcase
-          unless %w[trace debug info warn error].include?(log_level)
-            @err.puts("lsp: invalid --log-level #{log_level.inspect} (expected trace, debug, info, warn, or error)")
-            return 1
-          end
-        when "--stdio"
-          # stdio is the only transport; accept the flag as a no-op
-        else
-          if arg.start_with?("-")
-            @err.puts("lsp: unknown option #{arg}")
-            return 1
-          end
-          @err.puts("lsp: unexpected argument #{arg}")
-          return 1
-        end
-      end
-
-      require "milk_tea/lsp/server" unless defined?(MilkTea::LSP::Server)
-      server = MilkTea::LSP::Server.new
-      server.run
-      0
-    end
+        when "--"
+          forwarding = true
+          remaining << arg
+          i += 1
+        when "-v", "--verbose"
+          @verbose = true
+          i += 1
+        when "-q", "--quiet"
+          @quiet = true
+          i += 1
+        when "--color"
+          value = @argv[i + 1]
+          return invalid_color(value) unless valid_color?(value)
 
-    def dap_command
-      preferred_backend_kind = "process"
-      adapter_command = nil
+          @color = value.to_sym
+          i += 2
+        when /\A--color=(.*)\z/
+          value = ::Regexp.last_match(1)
+          return invalid_color(value) unless valid_color?(value)
 
-      until @argv.empty?
-        arg = @argv.shift
-        case arg
-        when "--log-level"
-          @argv.shift
-        when /\A--log-level=(.+)\z/
-          # accept and ignore
-        when "--backend"
-          preferred_backend_kind = @argv.shift&.downcase
-        when /\A--backend=(.+)\z/
-          preferred_backend_kind = ::Regexp.last_match(1).downcase
-        when "--adapter-path"
-          adapter_path = @argv.shift
-          adapter_command = resolve_adapter_path(adapter_path)
-          return 1 unless adapter_command
-        when /\A--adapter-path=(.+)\z/
-          adapter_path = ::Regexp.last_match(1)
-          adapter_command = resolve_adapter_path(adapter_path)
-          return 1 unless adapter_command
+          @color = value.to_sym
+          i += 1
         else
-          if arg.start_with?("-")
-            @err.puts("dap: unknown option #{arg}")
-            return 1
-          end
-          @err.puts("dap: unexpected argument #{arg}")
-          return 1
-        end
-      end
-
-      require "milk_tea/dap/server" unless defined?(MilkTea::DAP::Server)
-      server = MilkTea::DAP::Server.new(
-        preferred_backend_kind:,
-        adapter_command:,
-      )
-      server.run
-      0
-    end
-
-    def resolve_adapter_path(adapter_path)
-      unless adapter_path && File.file?(adapter_path)
-        @err.puts("dap: adapter path not found: #{adapter_path}")
-        return nil
-      end
-      expanded = File.expand_path(adapter_path)
-      adapter_path.end_with?(".rb") ? [RbConfig.ruby, expanded] : [expanded]
-    end
-
-    def toolchain_command
-      ToolchainCLI.start(
-        @argv,
-        out: @out,
-        err: @err,
-        help_printer: method(:print_toolchain_help),
-      )
-    end
-
-    def debug_command
-      unless @argv.any?
-        @err.puts("missing source file path")
-        print_usage(@err)
-        return 1
-      end
-
-      resolution = extract_resolution_flags!
-      input_paths = @argv.dup
-      return 1 unless ensure_known_source_operands!("debug", input_paths)
-
-      path = expand_source_paths(input_paths).first
-      unless path
-        @err.puts("no .mt files found in #{input_paths.join(', ')}")
-        return 1
-      end
-
-      ensure_current_lockfile!(path) if resolution[:frozen]
-
-      source = read_source_file(path)
-      resolved_path = File.expand_path(path)
-
-      tokens = MilkTea::Lexer.lex(source, path: resolved_path)
-
-      parse_result = MilkTea::Parser.parse_collecting_errors(source, path: resolved_path)
-      ast = parse_result.ast
-      parse_errors = parse_result.errors.dup
-
-      facts = nil
-      snapshot = nil
-      loader_ast = ast
-
-      if ast && parse_errors.empty?
-        begin
-          loader = make_module_loader(path, locked: resolution[:locked], platform: ModuleLoader.default_host_platform)
-          loader_ast = loader.load_file(resolved_path)
-
-          import_result = loader.send(:imported_modules_for_ast_collecting_errors, loader_ast, importer_path: resolved_path)
-          import_errors = import_result.respond_to?(:errors) ? import_result.errors : []
-          parse_errors.concat(import_errors) unless import_errors.empty?
-
-          snapshot = MilkTea::SemanticAnalyzer.tooling_snapshot(
-            loader_ast,
-            imported_modules: import_result.modules,
-            allow_missing_imports: true,
-            path: resolved_path,
-          )
-          facts = snapshot&.facts
-        rescue MilkTea::LexError, MilkTea::ParseError, ModuleLoadError, SemanticError => e
-          parse_errors << e
+          remaining << arg
+          i += 1
         end
       end
-
-      text = DebugInfoFormatter.format_all(
-        content: source,
-        tokens: tokens,
-        ast: loader_ast,
-        parse_errors: parse_errors,
-        facts: facts,
-        snapshot: snapshot,
-        path: resolved_path,
-      )
-
-      @out.puts(text)
-      0
-    rescue MilkTea::LexError => e
-      @err.puts(ErrorFormatter.format(e, color: error_color?(@err)))
-      1
+      @argv = remaining
+      true
     end
 
-    def bindgen_command
-      BindgenCLI.start(@argv, out: @out, err: @err, help_printer: method(:print_bindgen_help))
+    def valid_color?(value)
+      %w[auto always never].include?(value)
     end
 
-    def cache_command
-      subcommand = @argv.shift
-      unless subcommand
-        @err.puts("missing cache subcommand")
-        print_command_help("cache", @err)
-        return 1
-      end
-
-      cache_root = MilkTea.data_root.join("tmp", "mtc-cache")
-
-      case subcommand
-      when "purge"
-        if File.directory?(cache_root)
-          FileUtils.rm_rf(cache_root)
-          @out.puts("purged #{cache_root}")
-        else
-          @out.puts("cache is already empty")
-        end
-        0
-      when "status"
-        unless File.directory?(cache_root)
-          @out.puts("cache directory does not exist: #{cache_root}")
-          return 0
-        end
-        program_dirs = Dir.glob(File.join(cache_root, "programs", "*", "*")).select { |d| File.directory?(d) }
-        binary_files = Dir.glob(File.join(cache_root, "binaries", "*", "*", "binary")).select { |f| File.file?(f) }
-        total_size = (program_dirs + binary_files).sum { |p|
-          File.file?(p) ? File.size(p) : Dir.glob(File.join(p, "**", "*")).sum { |f| File.file?(f) ? File.size(f) : 0 }
-        }
-        @out.puts("cache  #{program_dirs.length} programs, #{binary_files.length} binaries  (#{format_size(total_size)})")
-        @out.puts("  root  #{cache_root}")
-        0
-      else
-        @err.puts("unknown cache subcommand #{subcommand}")
-        print_command_help("cache", @err)
-        1
-      end
+    def invalid_color(value)
+      @err.puts("--color must be auto, always, or never#{value ? " (got #{value})" : ''}")
+      false
     end
 
-    def completions_command
-      shell = @argv.shift
-      unless %w[bash zsh fish].include?(shell)
-        @err.puts("completions: shell must be bash, zsh, or fish")
-        print_command_help("completions", @err)
-        return 1
+    def error_color?(io)
+      case @color
+      when :always then true
+      when :never then false
+      else io.respond_to?(:tty?) && io.tty?
       end
-
-      @out.puts(completion_script(shell))
-      0
     end
 
-    def completion_script(shell)
-      names = COMMANDS.map(&:first)
-      case shell
-      when "bash"
-        [
-          "# mtc bash completion. Source this file or install it into your bash",
-          "# completion directory (e.g. /etc/bash_completion.d/mtc).",
-          "_mtc() {",
-          %(  local cur="${COMP_WORDS[COMP_CWORD]}"),
-          %(  if [ "${COMP_CWORD}" -eq 1 ]; then),
-          %(    COMPREPLY=( $(compgen -W "#{(names + %w[help version]).join(' ')}" -- "${cur}") )),
-          "  fi",
-          "}",
-          "complete -F _mtc mtc",
-        ].join("\n")
-      when "zsh"
-        lines = ["#compdef mtc", "# mtc zsh completion. Install onto your $fpath as _mtc.", "_mtc() {", "  local -a commands", "  commands=("]
-        COMMANDS.each { |name, summary| lines << "    '#{name}:#{summary}'" }
-        lines.concat(["  )", "  if (( CURRENT == 2 )); then", "    _describe 'mtc command' commands", "  fi", "}", %(_mtc "$@")])
-        lines.join("\n")
-      when "fish"
-        lines = ["# mtc fish completion. Install into ~/.config/fish/completions/mtc.fish."]
-        COMMANDS.each do |name, summary|
-          lines << "complete -c mtc -f -n '__fish_use_subcommand' -a #{name} -d '#{summary}'"
-        end
-        lines.join("\n")
-      end
+    # Prints an informational/progress line unless --quiet was given.
+    def info(message)
+      @out.puts(message) unless @quiet
     end
 
     def parse_build_options(allow_clean: false)
@@ -2097,68 +375,6 @@ module MilkTea
       options
     end
 
-    def parse_format_options
-      options = {
-        check: false,
-        write: false,
-        mode: :safe,
-        max_line_length: nil,
-        profile: false,
-      }
-      input_paths = []
-
-      until @argv.empty?
-        option = @argv.shift
-        if option.start_with?("-")
-          case option
-          when "--check"
-            options[:check] = true
-          when "--write", "-w"
-            options[:write] = true
-          when "--preserve"
-            options[:mode] = :preserve
-          when "--canonical"
-            options[:mode] = :canonical
-          when "--safe"
-            options[:mode] = :safe
-          when "--tidy"
-            options[:mode] = :tidy
-          when "--max-line-length"
-            value = @argv.shift
-            return missing_option_value(option) unless value
-
-            line_length = Integer(value, exception: false)
-            unless line_length && line_length.positive?
-              @err.puts("--max-line-length must be a positive integer")
-              print_usage(@err)
-              return nil
-            end
-
-            options[:max_line_length] = line_length
-          when "--timings"
-            options[:profile] = true
-          when "--"
-            input_paths.concat(@argv)
-            @argv.clear
-          else
-            @err.puts("unknown format option #{option}")
-            print_usage(@err)
-            return nil
-          end
-        else
-          input_paths << option
-        end
-      end
-
-      if options[:check] && options[:write]
-        @err.puts("format options --check and --write cannot be combined")
-        print_usage(@err)
-        return nil
-      end
-
-      { options:, input_paths: }
-    end
-
     def ensure_known_source_operands!(command, operands)
       return true unless operands.any? { |arg| arg.start_with?("-") }
 
@@ -2333,14 +549,6 @@ module MilkTea
       end
     end
 
-    def lint_sema_facts_for(source, path, locked: false)
-      ast = Parser.parse(source, path: path)
-      imported_modules = make_module_loader(path, locked:, platform: ModuleLoader.default_host_platform).imported_modules_for_ast(ast, importer_path: path)
-      SemanticAnalyzer.tooling_snapshot(ast, imported_modules: imported_modules, path: path).facts
-    rescue MilkTea::LexError, MilkTea::ParseError, SemanticError, ModuleLoadError
-      nil
-    end
-
     def extract_include_paths!
       remaining = []
       i = 0