command_registry.cc

Go to the documentation of this file.

#include "cli/service/command_registry.h"
 
#include <algorithm>
#include <cstdio>
#include <iostream>
#include <sstream>
 
#include "absl/strings/str_cat.h"
#include "absl/strings/str_format.h"
#include "absl/strings/str_join.h"
#include "cli/handlers/command_handlers.h"
#include "cli/service/usage_schema.h"
#include "nlohmann/json.hpp"
 
namespace yaze {
namespace cli {
 
CommandRegistry& CommandRegistry::Instance() {
  static CommandRegistry instance;
  static bool initialized = false;
  if (!initialized) {
    instance.RegisterCliCommands();
    initialized = true;
  }
  return instance;
}
 
void CommandRegistry::Register(
    std::unique_ptr<resources::CommandHandler> handler,
    const CommandMetadata& metadata) {
  std::string name = handler->GetName();
 
  // Store metadata
  metadata_[name] = metadata;
 
  // Register aliases
  for (const auto& alias : metadata.aliases) {
    aliases_[alias] = name;
  }
 
  // Store handler
  handlers_[name] = std::move(handler);
}
 
void CommandRegistry::RegisterHandlers(
    std::vector<std::unique_ptr<resources::CommandHandler>> handlers) {
  for (auto& handler : handlers) {
    std::string name = handler->GetName();
 
    if (handlers_.find(name) != handlers_.end()) {
      continue;
    }
 
    // Build metadata from handler
    auto descriptor = handler->Describe();
    CommandMetadata metadata;
    metadata.name = name;
    metadata.usage = handler->GetUsage();
    metadata.available_to_agent = true;  // Most commands available to agent
    metadata.requires_rom = handler->RequiresRom();
    metadata.requires_grpc = false;
 
    // Categorize and enhance metadata based on command type
    if (name.find("resource-") == 0) {
      metadata.category = "resource";
      metadata.description = "Resource inspection and search";
      if (name == "resource-list") {
        metadata.examples = {"z3ed resource-list --type=dungeon --format=json",
                             "z3ed resource-list --type=sprite --format=table"};
      }
    } else if (name.find("dungeon-") == 0) {
      metadata.category = "dungeon";
      metadata.description = "Dungeon inspection and editing";
      if (name == "dungeon-describe-room") {
        metadata.examples = {
            "z3ed dungeon-describe-room --room=5 --format=json"};
      } else if (name == "dungeon-stream-plan") {
        metadata.description =
            "Read-only stream inventory, alias/overlap, and free-space "
            "diagnostics; replacement-aware immutable move output is pending";
        metadata.examples = {
            "z3ed dungeon-stream-plan --kind=objects "
            "--manifest=hack_manifest.json --rom=game.sfc --format=json",
            "z3ed dungeon-stream-plan --kind=pot_items "
            "--manifest=hack_manifest.json --rom=game.sfc --format=text"};
      } else if (name == "dungeon-place-sprite") {
        metadata.description =
            "Place a dungeon sprite (dry-run by default, --write to apply)";
        metadata.examples = {
            "z3ed dungeon-place-sprite --room=0x77 --id=0xA3 --x=16 --y=21 "
            "--subtype=4 --rom=Roms/oos168.sfc --format=json",
            "z3ed dungeon-place-sprite --room=0x77 --id=0xA3 --x=16 --y=21 "
            "--subtype=4 --write --rom=/tmp/oos-work.sfc --format=json"};
      } else if (name == "dungeon-remove-sprite") {
        metadata.description =
            "Remove a dungeon sprite by index or exact coordinates";
        metadata.examples = {
            "z3ed dungeon-remove-sprite --room=0x77 --index=2 "
            "--rom=/tmp/oos-work.sfc --format=json",
            "z3ed dungeon-remove-sprite --room=0x77 --x=16 --y=21 --write "
            "--rom=/tmp/oos-work.sfc --format=json"};
      } else if (name == "dungeon-place-object") {
        metadata.description =
            "Place a dungeon object with immutable capacity/COW preflight "
            "(dry-run by default)";
        metadata.examples = {
            "z3ed dungeon-place-object --room=0x98 --id=0x0031 --x=20 --y=20 "
            "--size=4 --rom=/tmp/oos-work.sfc --format=json",
            "z3ed dungeon-place-object --room=0x98 --id=0x0031 --x=20 --y=20 "
            "--size=4 --manifest=hack_manifest.json --write "
            "--rom=/tmp/oos-work.sfc --format=json"};
      } else if (name == "dungeon-remove-object") {
        metadata.description =
            "Remove one ordinary dungeon object with exact identity guards "
            "(dry-run by default)";
        metadata.examples = {
            "z3ed dungeon-remove-object --room=0x88 --index=117 "
            "--expect-id=0x0DD --expect-x=30 --expect-y=12 "
            "--expect-size=0 --expect-layer=0 "
            "--rom=/tmp/oos-work.sfc --format=json",
            "z3ed dungeon-remove-object --room=0x88 --index=117 "
            "--expect-id=0x0DD --expect-x=30 --expect-y=12 "
            "--expect-size=0 --expect-layer=0 "
            "--manifest=hack_manifest.json --write "
            "--rom=/tmp/oos-work.sfc --format=json"};
      } else if (name == "dungeon-get-palette") {
        metadata.description =
            "Resolve a US/OOS room's full 8-bit palette-set ID to its shared "
            "global dungeon palette and report every affected room; other "
            "regional layouts fail closed";
        metadata.examples = {
            "z3ed dungeon-get-palette --room=0xA8 "
            "--rom=Roms/oos168.sfc --format=json",
            "z3ed dungeon-get-palette --room=0xA8 --index=0x07 "
            "--rom=Roms/oos168.sfc --format=json"};
      } else if (name == "dungeon-set-palette-color") {
        metadata.description =
            "Dry-run or persist one US/OOS shared dungeon palette color with "
            "palette-set/index/color CAS, manifest ownership, exact fence, "
            "clean-file baseline, required backup, atomic save, and external "
            "reopen guards";
        metadata.examples = {
            "z3ed dungeon-set-palette-color --room=0xA8 --index=7 "
            "--expect-palette-set=0x07 --expect-palette-index=7 "
            "--expect-color=0x7FFF --color=0x7FFE "
            "--manifest=Roms/hack_manifest.json "
            "--rom=Roms/oos168.sfc --format=json",
            "z3ed dungeon-set-palette-color --room=0xA8 --index=7 "
            "--expect-palette-set=0x07 --expect-palette-index=7 "
            "--expect-color=0x7FFF --color=0x7FFE "
            "--manifest=Roms/hack_manifest.json --write "
            "--rom=/tmp/oos-work.sfc --format=json"};
      } else if (name == "dungeon-set-door-type") {
        metadata.description =
            "Change one existing door type with coordinate/CAS and manifest "
            "guards (dry-run by default)";
        metadata.examples = {
            "z3ed dungeon-set-door-type --room=0xA8 --x=46 --y=58 "
            "--type=0x00 --expect-type=0x18 "
            "--manifest=hack_manifest.json --rom=Roms/oos168.sfc "
            "--format=json",
            "z3ed dungeon-set-door-type --room=0xA8 --x=46 --y=58 "
            "--type=0x00 --expect-type=0x18 "
            "--manifest=hack_manifest.json --write "
            "--rom=/tmp/oos-work.sfc --format=json"};
      } else if (name == "dungeon-list-pot-items") {
        metadata.description =
            "List existing pot items with raw positions and ROM addresses";
        metadata.examples = {
            "z3ed dungeon-list-pot-items --room=0xA8 "
            "--rom=Roms/oos168.sfc --format=json"};
      } else if (name == "dungeon-set-pot-item") {
        metadata.description =
            "Change one existing pot item with index/position/item CAS and "
            "manifest guards (dry-run by default)";
        metadata.examples = {
            "z3ed dungeon-set-pot-item --room=0xA8 --index=0 "
            "--expect-position=0x198C --expect-item=0x05 --item=0x06 "
            "--manifest=Roms/hack_manifest.json --rom=Roms/oos168.sfc "
            "--format=json",
            "z3ed dungeon-set-pot-item --room=0xA8 --index=0 "
            "--expect-position=0x198C --expect-item=0x05 --item=0x06 "
            "--manifest=Roms/hack_manifest.json --write "
            "--rom=/tmp/oos-work.sfc --format=json"};
      } else if (name == "dungeon-oracle-preflight") {
        metadata.description =
            "Oracle ROM safety preflight: water-fill region/table, collision "
            "maps, and optional required-room checks";
        metadata.examples = {
            "z3ed dungeon-oracle-preflight --rom oos168x.sfc --format=json",
            "z3ed dungeon-oracle-preflight --rom oos168x.sfc "
            "--required-water-fill-rooms=0x25,0x27 --format=json",
            "z3ed dungeon-oracle-preflight --rom oos168x.sfc "
            "--report=/tmp/preflight.json"};
      } else if (name == "dungeon-set-collision-tile") {
        metadata.description =
            "Set one or more custom collision tiles in a dungeon room";
        metadata.examples = {
            "z3ed dungeon-set-collision-tile --room=0xB8 "
            "--tiles=\"10,5,0xB7;50,45,0xBA\" --rom=/tmp/oos-work.sfc "
            "--format=json",
            "z3ed dungeon-set-collision-tile --room=0xB8 "
            "--tiles=\"10,5,0xB7;50,45,0xBA\" --write "
            "--rom=/tmp/oos-work.sfc --format=json"};
      }
    } else if (name.find("overworld-") == 0) {
      metadata.category = "overworld";
      metadata.description = "Overworld inspection and editing";
      if (name == "overworld-find-tile") {
        metadata.examples = {
            "z3ed overworld-find-tile --tile=0x42 --format=json"};
      } else if (name == "overworld-allocation") {
        metadata.description =
            "Area ID allocation map ($00-$BF) and TailMapExpansion check";
        metadata.examples = {
            "z3ed overworld-allocation --rom=zelda3.sfc",
            "z3ed overworld-allocation --rom=oos168x.sfc "
            "--project=Oracle-of-Secrets.yaze --tail-check --format=json"};
      }
    } else if (name.find("project-bundle-") == 0) {
      metadata.category = "project";
      metadata.requires_rom = false;
      if (name == "project-bundle-verify") {
        metadata.description = "Project bundle verification";
        metadata.examples = {
            "z3ed project-bundle-verify --project MyProject.yazeproj "
            "--format=json",
            "z3ed project-bundle-verify --project project.yaze "
            "--report report.json",
            "z3ed project-bundle-verify --project MyProject.yazeproj "
            "--check-rom-hash --format=json"};
      } else if (name == "project-bundle-pack") {
        metadata.description = "Pack bundle into zip archive";
        metadata.examples = {
            "z3ed project-bundle-pack --project MyProject.yazeproj "
            "--out MyProject.zip --format=json",
            "z3ed project-bundle-pack --project MyProject.yazeproj "
            "--out MyProject.zip --overwrite"};
      } else if (name == "project-bundle-unpack") {
        metadata.description = "Unpack zip archive into bundle";
        metadata.examples = {
            "z3ed project-bundle-unpack --archive MyProject.zip "
            "--out ./projects --format=json",
            "z3ed project-bundle-unpack --archive MyProject.zip "
            "--out ./projects --overwrite",
            "z3ed project-bundle-unpack --archive MyProject.zip "
            "--out ./projects --keep-partial-output",
            "z3ed project-bundle-unpack --archive MyProject.zip "
            "--out ./projects --dry-run"};
      }
    } else if (name == "plan-read" || name == "plan-agent-apply") {
      metadata.category = "project";
      metadata.requires_rom = false;
      if (name == "plan-read") {
        metadata.description = "Project plan IDs, SHA-256 and agent status";
        metadata.examples = {
            "z3ed plan-read --plan oracle.plan.json --format=json",
            "z3ed plan-read --project Oracle-of-Secrets.yaze"};
      } else {
        metadata.description = "Apply agent observations to a project plan";
        metadata.examples = {
            "z3ed plan-agent-apply --plan oracle.plan.json "
            "--update update.json --dry-run --format=json",
            "z3ed plan-agent-apply --plan oracle.plan.json "
            "--update update.json --format=json"};
      }
    } else if (name.find("rom-") == 0) {
      metadata.category = "rom";
      metadata.description = "ROM inspection and validation";
      if (name == "rom-info") {
        metadata.examples = {"z3ed rom-info --rom=zelda3.sfc"};
      } else if (name == "rom-validate") {
        metadata.examples = {"z3ed rom-validate --rom=zelda3.sfc"};
      } else if (name == "rom-doctor") {
        metadata.examples = {"z3ed rom-doctor --rom=zelda3.sfc --format=json"};
      } else if (name == "rom-diff") {
        metadata.examples = {
            "z3ed rom-diff --rom_a=base.sfc --rom_b=target.sfc"};
      } else if (name == "rom-compare") {
        metadata.examples = {
            "z3ed rom-compare --rom=target.sfc --baseline=vanilla.sfc"};
      } else if (name == "rom-write") {
        metadata.examples = {
            "z3ed rom-write --rom=/tmp/oos-work.sfc --address=0x15819C "
            "--data=\"0C\" --write --format=json"};
      }
    } else if (name.find("emulator-") == 0) {
      metadata.category = "emulator";
      metadata.description = "Emulator control and debugging";
      metadata.requires_grpc = true;
      if (name == "emulator-set-breakpoint") {
        metadata.examples = {
            "z3ed emulator-set-breakpoint --address=0x83D7 --description='NMI "
            "handler'"};
      }
    } else if (name.find("mesen-") == 0) {
      metadata.category = "mesen2";
      metadata.description = "Mesen2 socket automation and introspection";
      metadata.requires_rom = false;
      if (name == "mesen-state-capture") {
        metadata.examples = {
            "z3ed mesen-state-capture --state=foo.state "
            "--rom-file=Roms/oos168x.sfc --scenario=d6_room_88",
            "z3ed mesen-state-capture --state=Roms/SaveStates/d6_room_88.state "
            "--rom-file=Roms/oos168x.sfc --slot=1 "
            "--states-dir=~/Library/Application\\ Support/Mesen2/SaveStates"};
      } else if (name == "mesen-state-hook") {
        metadata.examples = {
            "z3ed mesen-state-hook --state=foo.state "
            "--rom-file=Roms/oos168x.sfc --scenario=d6_room_88",
            "z3ed mesen-state-hook --state=foo.state "
            "--rom-file=Roms/oos168x.sfc --format=json"};
      }
    } else if (name.find("gui-") == 0) {
      metadata.category = "gui";
      metadata.description = "GUI automation";
      metadata.requires_grpc = true;
    } else if (name.find("hex-") == 0) {
      metadata.category = "graphics";
      metadata.description = "Hex data manipulation";
    } else if (name.find("palette-") == 0) {
      metadata.category = "graphics";
      metadata.description = "Palette operations";
    } else if (name.find("sprite-") == 0) {
      metadata.category = "graphics";
      metadata.description = "Sprite operations";
    } else if (name.find("message-") == 0 || name.find("dialogue-") == 0) {
      metadata.category = "game";
      metadata.description = name.find("message-") == 0 ? "Message inspection"
                                                        : "Dialogue inspection";
      if (name == "message-source-sync") {
        metadata.description =
            "Dry-run or CAS-publish a complete canonical expanded-message "
            "bundle and deterministic no-org Asar include";
        metadata.examples = {
            "z3ed message-source-sync --project=Oracle-of-Secrets.yaze "
            "--file=/tmp/message-edits.json --format=json",
            "z3ed message-source-sync --project=Oracle-of-Secrets.yaze "
            "--file=/tmp/message-edits.json "
            "--expected-source-sha256=<sha256> --write --format=json"};
      }
    } else if (name.find("music-") == 0) {
      metadata.category = "game";
      metadata.description = "Music/audio inspection";
    } else if (name.find("oracle-") == 0) {
      metadata.category = "oracle";
      metadata.description = "Oracle-of-Secrets project tooling";
      if (name == "oracle-menu-index") {
        metadata.examples = {
            "z3ed oracle-menu-index --project=/path/to/oracle-of-secrets "
            "--format=json",
            "z3ed oracle-menu-index --table=Menu_ItemCursorPositions "
            "--missing-bins --format=json"};
      } else if (name == "oracle-menu-set-offset") {
        metadata.examples = {
            "z3ed oracle-menu-set-offset "
            "--asm=Menu/menu_select_item.asm "
            "--table=Menu_ItemCursorPositions --index=0 --row=7 --col=2",
            "z3ed oracle-menu-set-offset "
            "--asm=Menu/menu_select_item.asm "
            "--table=Menu_ItemCursorPositions --index=0 --row=7 --col=2 "
            "--write"};
      } else if (name == "oracle-menu-validate") {
        metadata.examples = {
            "z3ed oracle-menu-validate --project=/path/to/oracle-of-secrets",
            "z3ed oracle-menu-validate --project=/path/to/oracle-of-secrets "
            "--strict --max-row=31 --max-col=31"};
      } else if (name == "oracle-smoke-check") {
        metadata.examples = {
            "z3ed oracle-smoke-check --rom oos168.sfc --format=json",
            "z3ed oracle-smoke-check --rom oos168.sfc --strict-readiness "
            "--format=json",
            "z3ed oracle-smoke-check --rom oos168.sfc "
            "--min-d6-track-rooms=4 --format=json",
            "z3ed oracle-smoke-check --rom oos168.sfc "
            "--report=/tmp/smoke.json"};
      }
    } else if (name == "simple-chat" || name == "chat") {
      metadata.category = "agent";
      metadata.description = "AI conversational agent";
      metadata.available_to_agent = false;  // Meta-command
      metadata.requires_rom = false;
      metadata.examples = {
          "z3ed simple-chat --rom=zelda3.sfc",
          "z3ed simple-chat \"What dungeons exist?\" --rom=zelda3.sfc"};
    } else if (name.find("tools-") == 0) {
      metadata.category = "tools";
      if (name == "tools-list") {
        metadata.description = "List available test helper tools";
        metadata.requires_rom = false;
        metadata.available_to_agent = true;
      } else if (name == "tools-harness-state") {
        metadata.description = "Generate WRAM state for test harnesses";
        metadata.examples = {
            "z3ed tools-harness-state --rom=zelda3.sfc --output=state.h"};
      } else if (name == "tools-extract-values") {
        metadata.description = "Extract vanilla ROM values";
        metadata.examples = {"z3ed tools-extract-values --rom=zelda3.sfc"};
      } else if (name == "tools-extract-golden") {
        metadata.description = "Extract comprehensive golden data for testing";
        metadata.examples = {
            "z3ed tools-extract-golden --rom=zelda3.sfc --output=golden.h"};
      } else if (name == "tools-patch-v3") {
        metadata.description = "Create v3 ZSCustomOverworld patched ROM";
        metadata.examples = {
            "z3ed tools-patch-v3 --rom=zelda3.sfc --output=patched.sfc"};
      } else {
        metadata.description = "Test helper tool";
      }
    } else if (name.find("test-") == 0) {
      metadata.category = "test";
      metadata.description = "Test discovery and execution";
      if (name == "test-list") {
        metadata.requires_rom = false;
        metadata.examples = {"z3ed test-list", "z3ed test-list --format json"};
      } else if (name == "test-run") {
        metadata.examples = {"z3ed test-run --label stable",
                             "z3ed test-run --label gui"};
      } else if (name == "test-status") {
        metadata.requires_rom = false;
        metadata.examples = {"z3ed test-status --format json"};
      }
    } else {
      metadata.category = "misc";
      metadata.description = "Miscellaneous command";
    }
 
    // Prefer handler-provided summary if present
    if (!descriptor.summary.empty() &&
        descriptor.summary != "Command summary not provided.") {
      metadata.description = descriptor.summary;
    }
 
    // Keep TODO reference if supplied by handler
    if (!descriptor.todo_reference.empty() &&
        descriptor.todo_reference != "todo#unassigned") {
      metadata.todo_reference = descriptor.todo_reference;
    }
 
    Register(std::move(handler), metadata);
  }
}
 
resources::CommandHandler* CommandRegistry::Get(const std::string& name) const {
  // Check direct name
  auto it = handlers_.find(name);
  if (it != handlers_.end()) {
    return it->second.get();
  }
 
  // Check aliases
  auto alias_it = aliases_.find(name);
  if (alias_it != aliases_.end()) {
    auto handler_it = handlers_.find(alias_it->second);
    if (handler_it != handlers_.end()) {
      return handler_it->second.get();
    }
  }
 
  return nullptr;
}
 
const CommandRegistry::CommandMetadata* CommandRegistry::GetMetadata(
    const std::string& name) const {
  // Resolve alias first
  std::string canonical_name = name;
  auto alias_it = aliases_.find(name);
  if (alias_it != aliases_.end()) {
    canonical_name = alias_it->second;
  }
 
  auto it = metadata_.find(canonical_name);
  return (it != metadata_.end()) ? &it->second : nullptr;
}
 
std::vector<std::string> CommandRegistry::GetCommandsInCategory(
    const std::string& category) const {
  std::vector<std::string> result;
  for (const auto& [name, metadata] : metadata_) {
    if (metadata.category == category) {
      result.push_back(name);
    }
  }
  return result;
}
 
std::vector<std::string> CommandRegistry::GetCategories() const {
  std::vector<std::string> categories;
  for (const auto& [_, metadata] : metadata_) {
    if (std::find(categories.begin(), categories.end(), metadata.category) ==
        categories.end()) {
      categories.push_back(metadata.category);
    }
  }
  return categories;
}
 
std::vector<std::string> CommandRegistry::GetAgentCommands() const {
  std::vector<std::string> result;
  for (const auto& [name, metadata] : metadata_) {
    if (metadata.available_to_agent) {
      result.push_back(name);
    }
  }
  return result;
}
 
std::string CommandRegistry::ExportFunctionSchemas() const {
  nlohmann::ordered_json commands = nlohmann::ordered_json::array();
  for (const auto& [_, metadata] : metadata_) {
    const std::vector<UsageParameter> parameters =
        ParseUsageParameters(metadata.usage);
 
    nlohmann::ordered_json command;
    command["name"] = metadata.name;
    command["category"] = metadata.category;
    command["description"] = metadata.description;
    command["usage"] = metadata.usage;
    command["available_to_agent"] = metadata.available_to_agent;
    command["requires_rom"] = metadata.requires_rom;
    command["requires_grpc"] = metadata.requires_grpc;
    command["todo_reference"] = metadata.todo_reference;
    command["aliases"] = metadata.aliases;
    command["examples"] = metadata.examples;
    command["parameters"] = UsageParametersToJsonSchema(parameters);
 
    nlohmann::ordered_json positional = nlohmann::ordered_json::array();
    for (const UsageParameter& parameter : parameters) {
      if (parameter.positional) {
        positional.push_back(
            {{"name", parameter.name}, {"required", parameter.required}});
      }
    }
    if (!positional.empty()) {
      command["positional_arguments"] = std::move(positional);
    }
    commands.push_back(std::move(command));
  }
 
  nlohmann::ordered_json root;
  root["commands"] = std::move(commands);
  return root.dump(2, ' ', false, nlohmann::json::error_handler_t::replace);
}
 
std::string CommandRegistry::GenerateHelp(const std::string& name,
                                          const util::AnsiStyle& style) const {
  auto* metadata = GetMetadata(name);
  if (!metadata) {
    return absl::StrFormat("Command '%s' not found", name);
  }
 
  const auto label = [&style](absl::string_view text) {
    return absl::StrCat(style.Highlight(), text, style.Reset());
  };
 
  std::ostringstream help;
  help << "\n"
       << style.Heading() << metadata->name << style.Reset() << " - "
       << metadata->description << "\n\n";
  help << label("Usage:") << "\n";
  help << "  " << metadata->usage << "\n\n";
 
  if (!metadata->examples.empty()) {
    help << label("Examples:") << "\n";
    for (const auto& example : metadata->examples) {
      help << "  " << example << "\n";
    }
    help << "\n";
  }
 
  if (metadata->requires_rom) {
    help << label("Requires:") << " ROM file (--rom=<path>)\n";
  }
  if (metadata->requires_grpc) {
    help << label("Requires:") << " YAZE running with gRPC enabled\n";
  }
 
  if (!metadata->aliases.empty()) {
    help << "\n"
         << label("Aliases:") << " " << absl::StrJoin(metadata->aliases, ", ")
         << "\n";
  }
 
  return help.str();
}
 
std::string CommandRegistry::GenerateCategoryHelp(
    const std::string& category, const util::AnsiStyle& style) const {
  auto commands = GetCommandsInCategory(category);
  if (commands.empty()) {
    return absl::StrFormat("No commands in category '%s'", category);
  }
 
  std::ostringstream help;
  help << "\n"
       << style.Heading() << category << " commands:" << style.Reset()
       << "\n\n";
 
  for (const auto& cmd : commands) {
    auto* metadata = GetMetadata(cmd);
    if (metadata) {
      help << "  " << style.Highlight() << cmd << style.Reset() << "\n";
      help << "    " << metadata->description << "\n";
      if (!metadata->usage.empty()) {
        help << "    Usage: " << metadata->usage << "\n";
      }
      help << "\n";
    }
  }
 
  return help.str();
}
 
std::string CommandRegistry::GenerateCompleteHelp(
    const util::AnsiStyle& style) const {
  std::ostringstream help;
  help << "\n"
       << style.Heading() << "All z3ed Commands:" << style.Reset() << "\n\n";
 
  auto categories = GetCategories();
  for (const auto& category : categories) {
    help << GenerateCategoryHelp(category, style);
  }
 
  return help.str();
}
 
absl::Status CommandRegistry::Execute(const std::string& name,
                                      const std::vector<std::string>& args,
                                      Rom* rom_context,
                                      std::string* captured_output) {
  auto* handler = Get(name);
  if (!handler) {
    return absl::NotFoundError(absl::StrFormat("Command '%s' not found", name));
  }
 
  const bool command_help_requested =
      std::find(args.begin(), args.end(), "--help") != args.end() ||
      std::find(args.begin(), args.end(), "-h") != args.end();
  const util::AnsiStyle help_style = captured_output == nullptr
                                         ? util::AnsiStyle::ForStream(stdout)
                                         : util::AnsiStyle(false);
  if (command_help_requested) {
    const std::string help = GenerateHelp(name, help_style);
    if (captured_output != nullptr) {
      *captured_output = help;
    } else {
      std::cout << help << "\n";
    }
    return absl::OkStatus();
  }
 
  absl::Status status = handler->Run(args, rom_context, captured_output);
 
  // If a command was invoked without its required arguments, surface full
  // command help in addition to the normal parser error/usage line.
  if (!status.ok() && status.code() == absl::StatusCode::kInvalidArgument &&
      args.empty()) {
    const std::string help = GenerateHelp(name, help_style);
    if (captured_output != nullptr) {
      if (!captured_output->empty()) {
        captured_output->append("\n\n");
      }
      captured_output->append(help);
    } else {
      std::cout << help << "\n";
    }
  }
 
  return status;
}
 
bool CommandRegistry::HasCommand(const std::string& name) const {
  return Get(name) != nullptr;
}
 
void CommandRegistry::RegisterCliCommands() {
  RegisterHandlers(handlers::CreateCliCommandHandlers());
}
 
}  // namespace cli
}  // namespace yaze