message_commands.cc

Go to the documentation of this file.

#include "cli/handlers/game/message_commands.h"
 
#include <algorithm>
#include <cstddef>
#include <exception>
#include <filesystem>
#include <fstream>
#include <limits>
#include <optional>
#include <sstream>
 
#include "absl/flags/declare.h"
#include "absl/flags/flag.h"
#include "absl/strings/ascii.h"
#include "absl/strings/match.h"
#include "absl/strings/str_cat.h"
#include "absl/strings/str_format.h"
#include "absl/strings/str_join.h"
 
#include "app/editor/message/message_data.h"
#include "app/editor/message/message_source_sync.h"
#include "rom/snes.h"
#include "rom/transaction.h"
#include "util/macro.h"
#include "zelda3/resource_labels.h"
 
ABSL_DECLARE_FLAG(std::string, rom);
 
namespace yaze {
namespace cli {
namespace handlers {
 
namespace {
std::string NormalizeRange(const std::string& range) {
  return absl::AsciiStrToLower(range);
}
 
bool IncludeVanilla(const std::string& range) {
  return range == "all" || range == "vanilla";
}
 
bool IncludeExpanded(const std::string& range) {
  return range == "all" || range == "expanded";
}
 
std::string BankLabel(editor::MessageBank bank) {
  return editor::MessageBankToString(bank);
}
 
std::vector<editor::MessageData> ReadExpandedMessages(const Rom& rom) {
  const int start = editor::GetExpandedTextDataStart();
  if (start < 0 || static_cast<size_t>(start) >= rom.size()) {
    return {};
  }
  const int end = std::min(editor::GetExpandedTextDataEnd(),
                           static_cast<int>(rom.size()) - 1);
  return editor::ReadExpandedTextData(const_cast<uint8_t*>(rom.data()), start,
                                      end);
}
 
std::vector<editor::MessageData> ReadExpandedMessages(const Rom& rom, int start,
                                                      int end) {
  if (start < 0 || end < start || static_cast<size_t>(start) >= rom.size()) {
    return {};
  }
  end = std::min(end, static_cast<int>(rom.size()) - 1);
  return editor::ReadExpandedTextData(const_cast<uint8_t*>(rom.data()), start,
                                      end);
}
 
struct ProjectMutationContext {
  project::YazeProject project;
  std::filesystem::path canonical_rom_path;
};
 
struct ExpandedMutationContext {
  int start = 0;
  int end = 0;
  int message_limit = -1;
  std::string policy_warning;
};
 
class ScopedHackManifestBindingRestore {
 public:
  explicit ScopedHackManifestBindingRestore(
      zelda3::ResourceLabelProvider& provider)
      : provider_(provider), previous_(provider.hack_manifest()) {}
 
  ScopedHackManifestBindingRestore(const ScopedHackManifestBindingRestore&) =
      delete;
  ScopedHackManifestBindingRestore& operator=(
      const ScopedHackManifestBindingRestore&) = delete;
 
  ~ScopedHackManifestBindingRestore() { provider_.SetHackManifest(previous_); }
 
 private:
  zelda3::ResourceLabelProvider& provider_;
  const core::HackManifest* previous_ = nullptr;
};
 
absl::StatusOr<std::filesystem::path> CanonicalExistingPath(
    const std::string& path, absl::string_view label) {
  if (path.empty()) {
    return absl::FailedPreconditionError(
        absl::StrFormat("%s path is empty", label));
  }
 
  std::error_code ec;
  auto canonical_path = std::filesystem::canonical(path, ec);
  if (ec) {
    return absl::FailedPreconditionError(absl::StrFormat(
        "Cannot resolve %s path '%s': %s", label, path, ec.message()));
  }
  return canonical_path;
}
 
absl::Status EnsureConfiguredHackManifestLoaded(
    project::YazeProject* project, absl::string_view project_path) {
  if (project->hack_manifest.loaded() || project->hack_manifest_file.empty()) {
    return absl::OkStatus();
  }
 
  const std::string manifest_path =
      project->GetAbsolutePath(project->hack_manifest_file);
  const absl::Status manifest_status =
      project->hack_manifest.LoadFromFile(manifest_path);
  if (manifest_status.ok()) {
    return absl::OkStatus();
  }
  return absl::Status(
      manifest_status.code(),
      absl::StrFormat("Cannot load project '%s': hack manifest '%s': %s",
                      project_path, manifest_path, manifest_status.message()));
}
 
std::string FormatManifestConflict(const core::WriteConflict& conflict) {
  std::string result =
      absl::StrFormat("address 0x%06X is %s", conflict.address,
                      core::AddressOwnershipToString(conflict.ownership));
  if (!conflict.module.empty()) {
    absl::StrAppend(&result, " (Module: ", conflict.module, ")");
  }
  return result;
}
 
bool IsCanonicalMappedLoRomAddress(uint32_t address) {
  const uint8_t bank = static_cast<uint8_t>((address >> 16) & 0xFFu);
  if (bank == 0x7E || bank == 0x7F || (address & 0xFFFFu) < 0x8000u) {
    return false;
  }
  return PcToSnes(SnesToPc(address)) == address;
}
 
absl::StatusOr<ProjectMutationContext> LoadProjectMutationContext(
    const resources::ArgumentParser& parser, const Rom& rom,
    absl::string_view mutation_scope) {
  auto project_path = parser.GetString("project");
  if (!project_path.has_value() || project_path->empty()) {
    return absl::FailedPreconditionError(absl::StrFormat(
        "%s requires explicit --project so Yaze can verify ROM ownership and "
        "write policy",
        mutation_scope));
  }
  if (!rom.is_loaded()) {
    return absl::FailedPreconditionError("ROM is not loaded");
  }
 
  ProjectMutationContext context;
  auto& resource_labels = zelda3::GetResourceLabels();
  absl::Status open_status;
  {
    // YazeProject::Open temporarily installs its manifest in the
    // process-global label provider. Restore the embedding application's prior
    // non-owning pointer on every path, including malformed project data that
    // throws from a parser.
    ScopedHackManifestBindingRestore restore_manifest(resource_labels);
    try {
      open_status = context.project.Open(*project_path);
    } catch (const std::exception& error) {
      return absl::InvalidArgumentError(absl::StrFormat(
          "Cannot load project '%s': %s", *project_path, error.what()));
    } catch (...) {
      return absl::InvalidArgumentError(absl::StrFormat(
          "Cannot load project '%s': unknown project parse error",
          *project_path));
    }
  }
  if (!open_status.ok()) {
    return absl::Status(open_status.code(),
                        absl::StrFormat("Cannot load project '%s': %s",
                                        *project_path, open_status.message()));
  }
  if (context.project.rom_metadata.write_policy ==
      project::RomWritePolicy::kReadOnly) {
    return absl::PermissionDeniedError(
        "Message mutation is disabled by the project's read-only policy");
  }
  if (absl::Status manifest_status =
          EnsureConfiguredHackManifestLoaded(&context.project, *project_path);
      !manifest_status.ok()) {
    return manifest_status;
  }
 
  auto active_rom_path_or = CanonicalExistingPath(rom.filename(), "active ROM");
  if (!active_rom_path_or.ok()) {
    return active_rom_path_or.status();
  }
  auto project_rom_path_or = CanonicalExistingPath(
      context.project.GetAbsolutePath(context.project.rom_filename),
      "project ROM");
  if (!project_rom_path_or.ok()) {
    return project_rom_path_or.status();
  }
  if (*active_rom_path_or != *project_rom_path_or) {
    return absl::FailedPreconditionError(absl::StrFormat(
        "Project ROM mismatch: active ROM is '%s' but --project binds to '%s'",
        active_rom_path_or->string(), project_rom_path_or->string()));
  }
  std::error_code file_size_ec;
  const uintmax_t raw_file_size =
      std::filesystem::file_size(*active_rom_path_or, file_size_ec);
  if (file_size_ec) {
    return absl::FailedPreconditionError(
        absl::StrFormat("Cannot inspect active ROM size '%s': %s",
                        active_rom_path_or->string(), file_size_ec.message()));
  }
  constexpr uintmax_t kSnesBankSize = 0x8000;
  constexpr uintmax_t kCopierHeaderSize = 0x200;
  if (raw_file_size >= kCopierHeaderSize &&
      raw_file_size % kSnesBankSize == kCopierHeaderSize) {
    return absl::FailedPreconditionError(
        "Message mutation requires a headerless ROM file; remove the "
        "512-byte copier header and reopen the ROM");
  }
  if (raw_file_size != rom.size()) {
    return absl::FailedPreconditionError(absl::StrFormat(
        "Message mutation requires a headerless ROM file: disk size is 0x%zX "
        "but the loaded ROM is 0x%zX bytes",
        static_cast<size_t>(raw_file_size), rom.size()));
  }
  context.canonical_rom_path = *active_rom_path_or;
 
  const auto& manifest = context.project.hack_manifest;
  if (!manifest.loaded()) {
    return absl::FailedPreconditionError(absl::StrFormat(
        "Project '%s' has no loaded hack manifest; configure a valid "
        "hack_manifest_file before mutating messages",
        *project_path));
  }
 
  return context;
}
 
absl::StatusOr<ExpandedMutationContext> PreflightExpandedMutation(
    const project::YazeProject& yaze_project, const Rom& rom) {
  ExpandedMutationContext context;
  const auto& manifest = yaze_project.hack_manifest;
  const auto& layout = manifest.message_layout();
  if (layout.data_start == 0 || layout.data_end == 0 ||
      layout.data_end < layout.data_start ||
      !IsCanonicalMappedLoRomAddress(layout.data_start) ||
      !IsCanonicalMappedLoRomAddress(layout.data_end)) {
    return absl::FailedPreconditionError(
        "Hack manifest does not define a valid LoROM expanded message region");
  }
 
  const uint32_t start = SnesToPc(layout.data_start);
  const uint32_t end = SnesToPc(layout.data_end);
  if (end < start ||
      end > static_cast<uint32_t>(std::numeric_limits<int>::max()) ||
      end >= rom.size()) {
    return absl::OutOfRangeError(absl::StrFormat(
        "Configured expanded message region [0x%06X, 0x%06X] is outside the "
        "active ROM (size=0x%zX)",
        start, end, rom.size()));
  }
  context.start = static_cast<int>(start);
  context.end = static_cast<int>(end);
 
  // Even a manifest without ID metadata has a strict physical upper bound:
  // each message requires at least a 0x7F terminator and the bank needs a final
  // 0xFF. Keeping this limit finite prevents hostile IDs from driving a huge
  // sparse-vector allocation.
  const int region_capacity = context.end - context.start + 1;
  const int capacity_message_limit = std::max(0, region_capacity - 1);
  context.message_limit = capacity_message_limit;
  if (layout.expanded_count > 0) {
    context.message_limit =
        std::min(layout.expanded_count, capacity_message_limit);
  }
  if (layout.last_expanded_id >= layout.first_expanded_id &&
      (layout.first_expanded_id != 0 || layout.last_expanded_id != 0)) {
    const int declared_limit =
        static_cast<int>(layout.last_expanded_id - layout.first_expanded_id) +
        1;
    context.message_limit = std::min(context.message_limit, declared_limit);
  }
 
  const std::string lowered_hack_name =
      absl::AsciiStrToLower(manifest.hack_name());
  if (yaze_project.rom_metadata.write_policy ==
          project::RomWritePolicy::kBlock &&
      absl::StrContains(lowered_hack_name, "oracle of secrets")) {
    return absl::PermissionDeniedError(editor::kOracleExpandedRomWriteRefusal);
  }
 
  const auto conflicts =
      manifest.AnalyzePcWriteRanges({{start, static_cast<uint32_t>(end + 1u)}});
  if (!conflicts.empty()) {
    const std::string detail = FormatManifestConflict(conflicts.front());
    if (yaze_project.rom_metadata.write_policy ==
        project::RomWritePolicy::kBlock) {
      return absl::PermissionDeniedError(absl::StrFormat(
          "Expanded message mutation blocked by hack manifest: %s", detail));
    }
    if (yaze_project.rom_metadata.write_policy ==
        project::RomWritePolicy::kWarn) {
      context.policy_warning = absl::StrFormat(
          "Expanded message region conflicts with hack manifest: %s", detail);
    }
  }
 
  return context;
}
 
absl::Status VerifyCleanDiskSnapshot(const Rom& rom,
                                     std::vector<uint8_t>* baseline) {
  if (rom.dirty()) {
    return absl::FailedPreconditionError(
        "Message bundle apply requires a clean ROM; save or discard existing "
        "in-memory changes before retrying");
  }
 
  Rom disk_rom;
  Rom::LoadOptions load_options;
  load_options.load_resource_labels = false;
  const absl::Status load_status =
      disk_rom.LoadFromFile(rom.filename(), load_options);
  if (!load_status.ok()) {
    return load_status;
  }
  if (disk_rom.vector() != rom.vector()) {
    return absl::FailedPreconditionError(
        "Active ROM no longer matches the file on disk; reopen it before "
        "applying a message bundle");
  }
  if (baseline != nullptr) {
    *baseline = disk_rom.vector();
  }
  return absl::OkStatus();
}
 
absl::Status VerifyDiskSnapshotUnchanged(
    const std::filesystem::path& rom_path,
    const std::vector<uint8_t>& expected_bytes) {
  std::error_code file_size_ec;
  const uintmax_t raw_file_size =
      std::filesystem::file_size(rom_path, file_size_ec);
  if (file_size_ec ||
      raw_file_size != static_cast<uintmax_t>(expected_bytes.size())) {
    return absl::AbortedError(
        "ROM size changed on disk after message preflight; no bytes were "
        "saved. Reopen the ROM and retry");
  }
  Rom disk_rom;
  Rom::LoadOptions load_options;
  load_options.load_resource_labels = false;
  const absl::Status load_status =
      disk_rom.LoadFromFile(rom_path.string(), load_options);
  if (!load_status.ok()) {
    return load_status;
  }
  if (disk_rom.vector() != expected_bytes) {
    return absl::AbortedError(
        "ROM changed on disk after message preflight; no bytes were saved. "
        "Reopen the ROM and retry");
  }
  return absl::OkStatus();
}
 
absl::Status ValidateVanillaMutation(
    const project::YazeProject& yaze_project,
    const std::vector<std::pair<uint32_t, uint32_t>>& changed_ranges,
    std::string* policy_warning) {
  const auto conflicts =
      yaze_project.hack_manifest.AnalyzePcWriteRanges(changed_ranges);
  if (conflicts.empty()) {
    return absl::OkStatus();
  }
 
  const std::string detail = FormatManifestConflict(conflicts.front());
  if (yaze_project.rom_metadata.write_policy ==
      project::RomWritePolicy::kBlock) {
    return absl::PermissionDeniedError(absl::StrFormat(
        "Vanilla message mutation blocked by hack manifest: %s; no message "
        "bytes were written",
        detail));
  }
  if (yaze_project.rom_metadata.write_policy ==
          project::RomWritePolicy::kWarn &&
      policy_warning != nullptr) {
    *policy_warning = absl::StrFormat(
        "Vanilla message write conflicts with hack manifest: %s", detail);
  }
  return absl::OkStatus();
}
 
// The two vanilla text regions in stream order: CreateMessagePointers
// ($0E:D3EB) walks $1C:8000 and moves to $0E:DF40 at the first [BANK] byte.
struct VanillaTextRegion {
  const char* name;
  uint32_t start;
  uint32_t capacity_end;  // exclusive
};
constexpr VanillaTextRegion kVanillaTextRegions[] = {
    {"primary", static_cast<uint32_t>(editor::kTextData),
     static_cast<uint32_t>(editor::kTextDataEnd) + 1},
    {"secondary", static_cast<uint32_t>(editor::kTextData2),
     static_cast<uint32_t>(editor::kTextData2End) + 1},
};
 
struct EditedVanillaMessage {
  int id = 0;
  size_t previous_length = 0;  // bytes before the terminator
  size_t encoded_length = 0;
  bool unchanged = false;  // same text as the ROM; bytes kept as they are
};
 
struct VanillaEditPlan {
  editor::VanillaMessageSavePlan plan;
  editor::VanillaMessageSavePlan current;  // the ROM's stream as it is
  std::vector<std::pair<uint32_t, uint32_t>> changed_ranges;
  size_t expected_count = 0;
  bool secondary_length_pinned = false;
  std::vector<EditedVanillaMessage> edited;
};
 
// Places `edits` (message ID, encoded bytes) into the ROM's vanilla stream and
// checks the result before anything is written:
// - edited messages are re-encoded with the ROM's word dictionary;
// - the stream must hold the manifest's vanilla_count messages;
// - only bytes that change are checked against the manifest, so rewriting a
//   protected byte with its current value is not a conflict;
// - when the manifest declares a region-switch hook (messages.hook_address),
//   the expanded messages are chained after the vanilla stream: Oracle of
//   Secrets hooks the switch at $0E:D436, and its build turns the byte after
//   the last vanilla message into a second [BANK]. The secondary region then
//   keeps its length. A shorter stream would end the game's pointer walk
//   before the expanded messages; a longer one would run into that byte.
absl::StatusOr<VanillaEditPlan> PlanVanillaEdits(
    const project::YazeProject& yaze_project, const Rom& rom,
    const std::vector<std::pair<int, std::vector<uint8_t>>>& edits,
    std::string* policy_warning) {
  const auto& layout = yaze_project.hack_manifest.message_layout();
  if (layout.vanilla_count <= 0) {
    return absl::FailedPreconditionError(
        "Hack manifest must declare a positive messages.vanilla_count "
        "before applying vanilla messages");
  }
  if (rom.size() > static_cast<size_t>(std::numeric_limits<int>::max())) {
    return absl::OutOfRangeError(
        "ROM is too large for bounded vanilla-message parsing");
  }
  const size_t expected_count = static_cast<size_t>(layout.vanilla_count);
  auto messages =
      editor::ReadAllTextData(const_cast<uint8_t*>(rom.data()),
                              editor::kTextData, static_cast<int>(rom.size()));
  auto current_or =
      editor::BuildVanillaMessageSavePlan(messages, expected_count);
  if (!current_or.ok()) {
    return current_or.status();
  }
 
  const auto dictionary =
      editor::ReadDictionaryEntryBytes(rom.data(), rom.size());
  if (dictionary.empty()) {
    return absl::FailedPreconditionError(absl::StrFormat(
        "Word dictionary table at PC 0x%06X is outside the ROM or malformed; "
        "no message bytes were written",
        editor::kPointersDictionaries));
  }
  std::vector<EditedVanillaMessage> edited;
  for (const auto& [id, bytes] : edits) {
    if (id < 0 || id >= static_cast<int>(messages.size())) {
      return absl::InvalidArgumentError(
          absl::StrFormat("Vanilla message ID 0x%03X is outside 0x000-0x%03X",
                          id, static_cast<int>(messages.size()) - 1));
    }
    editor::MessageData& message = messages[id];
    std::vector<uint8_t> encoded = bytes;
    // ReadAllTextData attaches the region switch to the first message of the
    // secondary region. It is stream layout, not text; keep it when the new
    // text leaves it out.
    if (!message.Data.empty() &&
        message.Data.front() == editor::kBankSwitchCommand &&
        (encoded.empty() || encoded.front() != editor::kBankSwitchCommand)) {
      encoded.insert(encoded.begin(), editor::kBankSwitchCommand);
    }
    const size_t previous_length = message.Data.size();
    // A message whose text did not change keeps its bytes. Re-encoding it
    // would still shrink text stored without the dictionary (the editor's
    // save and older imports), which trips the region-2 length pin when a
    // whole exported bundle is imported back.
    if (editor::ExpandMessageDictionary(encoded, dictionary) ==
        editor::ExpandMessageDictionary(message.Data, dictionary)) {
      edited.push_back({id, previous_length, previous_length, true});
      continue;
    }
    message.Data = editor::CompressMessageWithDictionary(encoded, dictionary);
    message.DataParsed = message.Data;
    edited.push_back({id, previous_length, message.Data.size(), false});
  }
 
  auto plan_or = editor::BuildVanillaMessageSavePlan(messages, expected_count);
  if (!plan_or.ok()) {
    return plan_or.status();
  }
  VanillaEditPlan edit{std::move(plan_or.value()),
                       std::move(current_or.value()),
                       {},
                       expected_count,
                       layout.hook_address != 0,
                       std::move(edited)};
  edit.changed_ranges = edit.plan.ChangedRanges(rom.data(), rom.size());
 
  const auto& new_writes = edit.plan.writes();
  const auto& old_writes = edit.current.writes();
  if (edit.secondary_length_pinned && new_writes.size() > 1 &&
      old_writes.size() > 1 && new_writes[1].end() != old_writes[1].end()) {
    return absl::FailedPreconditionError(absl::StrFormat(
        "Vanilla text region 2 (PC 0x%06X) must stay %zu bytes because the "
        "manifest chains expanded messages from its end (the byte at PC "
        "0x%06X becomes the switch into the expanded bank); this edit makes "
        "it %zu bytes. Keep messages in region 2 the same total length. No "
        "message bytes were written",
        editor::kTextData2, old_writes[1].bytes().size() - 1,
        old_writes[1].end() - 1, new_writes[1].bytes().size() - 1));
  }
 
  RETURN_IF_ERROR(ValidateVanillaMutation(yaze_project, edit.changed_ranges,
                                          policy_warning));
  return edit;
}
 
// Per-region usage of the planned stream (and of the ROM as it is), plus the
// byte ranges a save would change.
void AddVanillaPlanReport(resources::OutputFormatter& formatter,
                          const VanillaEditPlan& edit) {
  formatter.BeginArray("vanilla_regions");
  const auto& new_writes = edit.plan.writes();
  const auto& old_writes = edit.current.writes();
  for (size_t index = 0; index < std::size(kVanillaTextRegions); ++index) {
    const VanillaTextRegion& region = kVanillaTextRegions[index];
    const uint64_t capacity = region.capacity_end - region.start;
    const uint64_t used =
        index < new_writes.size() ? new_writes[index].bytes().size() : 0;
    const uint64_t current_used =
        index < old_writes.size() ? old_writes[index].bytes().size() : 0;
    formatter.BeginObject();
    formatter.AddField("region", region.name);
    formatter.AddHexField("start", region.start, 6);
    formatter.AddHexField("capacity_end", region.capacity_end, 6);
    formatter.AddField("capacity", capacity);
    formatter.AddField("current_used", current_used);
    formatter.AddField("used", used);
    // A pinned region cannot grow, so it has no free bytes to offer.
    const bool pinned = index == 1 && edit.secondary_length_pinned;
    formatter.AddField(
        "free", pinned || used > capacity ? uint64_t{0} : capacity - used);
    if (pinned) {
      formatter.AddField("length_pinned", true);
    }
    formatter.EndObject();
  }
  formatter.EndArray();
 
  uint64_t changed_bytes = 0;
  formatter.BeginArray("changed_ranges");
  for (const auto& [start, end] : edit.changed_ranges) {
    changed_bytes += end - start;
    formatter.AddArrayItem(absl::StrFormat("0x%06X-0x%06X", start, end));
  }
  formatter.EndArray();
  formatter.AddField("changed_bytes", changed_bytes);
 
  formatter.BeginArray("encoded_messages");
  for (const EditedVanillaMessage& message : edit.edited) {
    formatter.BeginObject();
    formatter.AddHexField("id", static_cast<uint64_t>(message.id), 3);
    formatter.AddField("previous_length",
                       static_cast<uint64_t>(message.previous_length));
    formatter.AddField("encoded_length",
                       static_cast<uint64_t>(message.encoded_length));
    if (message.unchanged) {
      formatter.AddField("unchanged", true);
    }
    formatter.EndObject();
  }
  formatter.EndArray();
}
 
// Dry run of a vanilla apply: with a ROM (--rom) and a project, builds the
// plan and reports it without writing. Reports why it was skipped otherwise.
void AddVanillaApplyPreflight(
    const resources::ArgumentParser& parser, Rom* rom,
    const std::vector<std::pair<int, std::vector<uint8_t>>>& edits,
    resources::OutputFormatter& formatter) {
  Rom owned_rom;
  Rom* active_rom = rom;
  if (active_rom == nullptr || !active_rom->is_loaded()) {
    auto rom_path = parser.GetString("rom");
    if (!rom_path.has_value() || rom_path->empty()) {
      const std::string global_rom_path = absl::GetFlag(FLAGS_rom);
      if (!global_rom_path.empty()) {
        rom_path = global_rom_path;
      }
    }
    if (!rom_path.has_value() || rom_path->empty()) {
      formatter.AddField("apply_preflight", "skipped: no --rom");
      return;
    }
    Rom::LoadOptions load_options;
    load_options.load_resource_labels = false;
    const absl::Status load_status =
        owned_rom.LoadFromFile(*rom_path, load_options);
    if (!load_status.ok()) {
      formatter.AddField("apply_preflight",
                         absl::StrCat("error: ", load_status.message()));
      return;
    }
    active_rom = &owned_rom;
  }
  auto project_context_or = LoadProjectMutationContext(
      parser, *active_rom, "Message bundle preflight");
  if (!project_context_or.ok()) {
    formatter.AddField(
        "apply_preflight",
        absl::StrCat("skipped: ", project_context_or.status().message()));
    return;
  }
  std::string policy_warning;
  auto edit_or = PlanVanillaEdits(project_context_or->project, *active_rom,
                                  edits, &policy_warning);
  if (!edit_or.ok()) {
    formatter.AddField("apply_preflight",
                       absl::StrCat("blocked: ", edit_or.status().message()));
    return;
  }
  formatter.AddField("apply_preflight", "ok");
  if (!policy_warning.empty()) {
    formatter.AddField("write_policy_warning", policy_warning);
  }
  AddVanillaPlanReport(formatter, *edit_or);
}
 
absl::Status VerifySavedRom(
    const Rom& active_rom, const std::filesystem::path& saved_rom_path,
    const std::optional<editor::VanillaMessageSavePlan>& vanilla_plan,
    std::optional<size_t> expected_vanilla_count) {
  Rom reopened_rom;
  Rom::LoadOptions load_options;
  load_options.load_resource_labels = false;
  const absl::Status reopen_status =
      reopened_rom.LoadFromFile(saved_rom_path.string(), load_options);
  if (!reopen_status.ok()) {
    return absl::DataLossError(absl::StrFormat(
        "ROM was saved but could not be reopened for verification: %s. "
        "Restore the required backup before retrying",
        reopen_status.message()));
  }
  if (reopened_rom.vector() != active_rom.vector()) {
    return absl::DataLossError(
        "ROM was saved but external readback differs from the planned bytes. "
        "Restore the required backup before retrying");
  }
 
  if (vanilla_plan.has_value()) {
    if (reopened_rom.size() >
        static_cast<size_t>(std::numeric_limits<int>::max())) {
      return absl::DataLossError(
          "ROM was saved but is too large for bounded vanilla-message "
          "readback. Restore the required backup before retrying");
    }
    const auto reopened_messages =
        editor::ReadAllTextData(reopened_rom.mutable_data(), editor::kTextData,
                                static_cast<int>(reopened_rom.size()));
    auto readback_plan_or = editor::BuildVanillaMessageSavePlan(
        reopened_messages, expected_vanilla_count);
    if (!readback_plan_or.ok() ||
        readback_plan_or.value() != vanilla_plan.value()) {
      const std::string detail =
          readback_plan_or.ok()
              ? "serialized message bytes differ from the save plan"
              : std::string(readback_plan_or.status().message());
      return absl::DataLossError(absl::StrFormat(
          "ROM was saved but vanilla-message readback failed: %s. Restore the "
          "required backup before retrying",
          detail));
    }
  }
 
  return absl::OkStatus();
}
 
absl::Status ValidateExpandedMessageId(int id,
                                       const ExpandedMutationContext& context) {
  if (id < 0) {
    return absl::InvalidArgumentError(
        absl::StrFormat("Invalid expanded message ID: %d", id));
  }
  if (context.message_limit >= 0 && id >= context.message_limit) {
    return absl::OutOfRangeError(absl::StrFormat(
        "Expanded message ID %d is outside the manifest range (count=%d)", id,
        context.message_limit));
  }
  return absl::OkStatus();
}
 
absl::Status ValidateExpandedMessageBankSize(
    size_t message_count, const ExpandedMutationContext& context) {
  if (context.message_limit >= 0 &&
      message_count > static_cast<size_t>(context.message_limit)) {
    return absl::FailedPreconditionError(absl::StrFormat(
        "Expanded message bank contains %zu messages, exceeding the manifest "
        "limit of %d; no changes were applied",
        message_count, context.message_limit));
  }
  return absl::OkStatus();
}
}  // namespace
 
// ===========================================================================
// Existing Commands
// ===========================================================================
 
absl::Status MessageListCommandHandler::Execute(
    Rom* rom, const resources::ArgumentParser& parser,
    resources::OutputFormatter& formatter) {
  auto limit = parser.GetInt("limit").value_or(50);
  if (limit < 0) {
    limit = 0;
  }
 
  auto messages = editor::ReadAllTextData(const_cast<uint8_t*>(rom->data()),
                                          editor::kTextData);
  if (limit > static_cast<int>(messages.size())) {
    limit = static_cast<int>(messages.size());
  }
 
  formatter.BeginObject("Message List");
  formatter.AddField("limit", limit);
  formatter.AddField("total_messages", static_cast<int>(messages.size()));
  formatter.AddField("status", "success");
 
  formatter.BeginArray("messages");
  for (int i = 0; i < limit; ++i) {
    const auto& msg = messages[i];
    formatter.BeginObject();
    formatter.AddField("id", msg.ID);
    formatter.AddHexField("address", msg.Address, 6);
    formatter.AddField("text", msg.ContentsParsed);
    formatter.AddField("length", static_cast<int>(msg.Data.size()));
    formatter.EndObject();
  }
  formatter.EndArray();
  formatter.EndObject();
 
  return absl::OkStatus();
}
 
absl::Status MessageReadCommandHandler::Execute(
    Rom* rom, const resources::ArgumentParser& parser,
    resources::OutputFormatter& formatter) {
  auto message_id_or = parser.GetInt("id");
  if (!message_id_or.ok()) {
    return message_id_or.status();
  }
  int message_id = message_id_or.value();
 
  auto messages = editor::ReadAllTextData(const_cast<uint8_t*>(rom->data()),
                                          editor::kTextData);
  if (message_id < 0 || message_id >= static_cast<int>(messages.size())) {
    return absl::NotFoundError(
        absl::StrFormat("Message ID %d not found (max: %d)", message_id,
                        static_cast<int>(messages.size()) - 1));
  }
 
  const auto& msg = messages[message_id];
 
  formatter.BeginObject("Message");
  formatter.AddField("id", msg.ID);
  formatter.AddHexField("address", msg.Address, 6);
  formatter.AddField("text", msg.ContentsParsed);
  formatter.AddField("length", static_cast<int>(msg.Data.size()));
  formatter.EndObject();
 
  return absl::OkStatus();
}
 
absl::Status MessageSearchCommandHandler::Execute(
    Rom* rom, const resources::ArgumentParser& parser,
    resources::OutputFormatter& formatter) {
  auto query = parser.GetString("query").value();
  auto limit = parser.GetInt("limit").value_or(10);
  if (limit < 0) {
    limit = 0;
  }
 
  auto messages = editor::ReadAllTextData(const_cast<uint8_t*>(rom->data()),
                                          editor::kTextData);
 
  formatter.BeginObject("Message Search Results");
  formatter.AddField("query", query);
  formatter.AddField("limit", limit);
  formatter.AddField("status", "success");
 
  std::string lowered_query = absl::AsciiStrToLower(query);
  std::vector<const editor::MessageData*> matches;
  for (const auto& msg : messages) {
    std::string lowered_text = absl::AsciiStrToLower(msg.ContentsParsed);
    if (lowered_text.find(lowered_query) == std::string::npos) {
      continue;
    }
    matches.push_back(&msg);
  }
 
  formatter.AddField("matches_found", static_cast<int>(matches.size()));
  formatter.BeginArray("matches");
  int match_count = 0;
  for (const auto* msg : matches) {
    if (limit > 0 && match_count >= limit) {
      break;
    }
    formatter.BeginObject();
    formatter.AddField("id", msg->ID);
    formatter.AddHexField("address", msg->Address, 6);
    formatter.AddField("text", msg->ContentsParsed);
    formatter.EndObject();
    match_count++;
  }
  formatter.EndArray();
  formatter.EndObject();
 
  return absl::OkStatus();
}
 
// ===========================================================================
// New: Encode Command
// ===========================================================================
 
absl::Status MessageEncodeCommandHandler::Execute(
    Rom* rom, const resources::ArgumentParser& parser,
    resources::OutputFormatter& formatter) {
  auto text = parser.GetString("text").value();
 
  auto parse_result = editor::ParseMessageToDataWithDiagnostics(text);
  auto bytes = parse_result.bytes;
 
  // Build hex string
  std::string hex_str;
  for (size_t i = 0; i < bytes.size(); ++i) {
    if (i > 0)
      hex_str += " ";
    hex_str += absl::StrFormat("%02X", bytes[i]);
  }
 
  formatter.BeginObject("Encoded Message");
  formatter.AddField("input", text);
  formatter.AddField("hex", hex_str);
  formatter.AddField("length", static_cast<int>(bytes.size()));
 
  // Also output as byte array for JSON consumers
  formatter.BeginArray("bytes");
  for (uint8_t byte : bytes) {
    formatter.AddArrayItem(absl::StrFormat("0x%02X", byte));
  }
  formatter.EndArray();
 
  // Run line width validation
  auto warnings = editor::ValidateMessageLineWidths(text);
  if (!warnings.empty()) {
    formatter.BeginArray("line_width_warnings");
    for (const auto& warning : warnings) {
      formatter.AddArrayItem(warning);
    }
    formatter.EndArray();
  }
  if (!parse_result.warnings.empty()) {
    formatter.BeginArray("warnings");
    for (const auto& warning : parse_result.warnings) {
      formatter.AddArrayItem(warning);
    }
    formatter.EndArray();
  }
  if (!parse_result.errors.empty()) {
    formatter.BeginArray("errors");
    for (const auto& error : parse_result.errors) {
      formatter.AddArrayItem(error);
    }
    formatter.EndArray();
  }
 
  formatter.EndObject();
 
  return absl::OkStatus();
}
 
// ===========================================================================
// New: Decode Command
// ===========================================================================
 
absl::Status MessageDecodeCommandHandler::Execute(
    Rom* rom, const resources::ArgumentParser& parser,
    resources::OutputFormatter& formatter) {
  auto hex_input = parser.GetString("hex").value();
 
  // Parse hex string to bytes
  std::vector<uint8_t> bytes;
  std::istringstream hex_stream(hex_input);
  std::string hex_byte;
  while (hex_stream >> hex_byte) {
    try {
      bytes.push_back(static_cast<uint8_t>(std::stoi(hex_byte, nullptr, 16)));
    } catch (const std::exception&) {
      return absl::InvalidArgumentError(
          absl::StrFormat("Invalid hex byte: '%s'", hex_byte));
    }
  }
 
  // Decode bytes to text, handling commands with arguments
  std::string decoded;
  for (size_t i = 0; i < bytes.size(); ++i) {
    uint8_t byte = bytes[i];
 
    // Check for command (may consume next byte as argument)
    auto cmd = editor::FindMatchingCommand(byte);
    if (cmd.has_value()) {
      if (cmd->HasArgument && i + 1 < bytes.size()) {
        decoded += cmd->GetParamToken(bytes[++i]);
      } else {
        decoded += cmd->GetParamToken();
      }
      continue;
    }
 
    // Single-byte lookup for chars, specials, dictionary
    decoded += editor::ParseTextDataByte(byte);
  }
 
  formatter.BeginObject("Decoded Message");
  formatter.AddField("hex", hex_input);
  formatter.AddField("text", decoded);
  formatter.AddField("length", static_cast<int>(bytes.size()));
  formatter.EndObject();
 
  return absl::OkStatus();
}
 
// ===========================================================================
// New: Import Org Command
// ===========================================================================
 
absl::Status MessageImportOrgCommandHandler::Execute(
    Rom* rom, const resources::ArgumentParser& parser,
    resources::OutputFormatter& formatter) {
  auto file_path = parser.GetString("file").value();
 
  // Read the .org file
  std::ifstream file(file_path);
  if (!file.is_open()) {
    return absl::NotFoundError(
        absl::StrFormat("Cannot open file: %s", file_path));
  }
 
  std::string content((std::istreambuf_iterator<char>(file)),
                      std::istreambuf_iterator<char>());
  file.close();
 
  auto messages = editor::ParseOrgContent(content);
 
  formatter.BeginObject("Org Import Results");
  formatter.AddField("file", file_path);
  formatter.AddField("messages_parsed", static_cast<int>(messages.size()));
 
  formatter.BeginArray("messages");
  for (const auto& [msg_id, body] : messages) {
    // Encode the body text to bytes with diagnostics
    auto parse_result = editor::ParseMessageToDataWithDiagnostics(body);
    auto bytes = parse_result.bytes;
    auto warnings = editor::ValidateMessageLineWidths(body);
 
    std::string hex_str;
    for (size_t i = 0; i < bytes.size(); ++i) {
      if (i > 0)
        hex_str += " ";
      hex_str += absl::StrFormat("%02X", bytes[i]);
    }
 
    formatter.BeginObject();
    formatter.AddHexField("id", msg_id, 2);
    formatter.AddField("text", body);
    formatter.AddField("hex", hex_str);
    formatter.AddField("encoded_length", static_cast<int>(bytes.size()));
    if (!warnings.empty()) {
      formatter.BeginArray("warnings");
      for (const auto& warning : warnings) {
        formatter.AddArrayItem(warning);
      }
      formatter.EndArray();
    }
    if (!parse_result.warnings.empty()) {
      formatter.BeginArray("parse_warnings");
      for (const auto& warning : parse_result.warnings) {
        formatter.AddArrayItem(warning);
      }
      formatter.EndArray();
    }
    if (!parse_result.errors.empty()) {
      formatter.BeginArray("errors");
      for (const auto& error : parse_result.errors) {
        formatter.AddArrayItem(error);
      }
      formatter.EndArray();
    }
    formatter.EndObject();
  }
  formatter.EndArray();
  formatter.EndObject();
 
  return absl::OkStatus();
}
 
// ===========================================================================
// New: Export Org Command
// ===========================================================================
 
absl::Status MessageExportOrgCommandHandler::Execute(
    Rom* rom, const resources::ArgumentParser& parser,
    resources::OutputFormatter& formatter) {
  auto output_path = parser.GetString("output").value();
 
  auto messages = editor::ReadAllTextData(const_cast<uint8_t*>(rom->data()),
                                          editor::kTextData);
 
  // Build message pairs and labels
  std::vector<std::pair<int, std::string>> msg_pairs;
  std::vector<std::string> labels;
  for (const auto& msg : messages) {
    msg_pairs.push_back({msg.ID, msg.RawString});
    labels.push_back(absl::StrFormat("Message %02X", msg.ID));
  }
 
  std::string org_content = editor::ExportToOrgFormat(msg_pairs, labels);
 
  // Write to file
  std::ofstream file(output_path);
  if (!file.is_open()) {
    return absl::InternalError(
        absl::StrFormat("Cannot write to file: %s", output_path));
  }
  file << org_content;
  file.close();
 
  formatter.BeginObject("Org Export Results");
  formatter.AddField("output", output_path);
  formatter.AddField("messages_exported", static_cast<int>(messages.size()));
  formatter.AddField("status", "success");
  formatter.EndObject();
 
  return absl::OkStatus();
}
 
// ===========================================================================
// New: Export Bundle Command
// ===========================================================================
 
absl::Status MessageExportBundleCommandHandler::Execute(
    Rom* rom, const resources::ArgumentParser& parser,
    resources::OutputFormatter& formatter) {
  auto output_path = parser.GetString("output").value();
  auto range = NormalizeRange(parser.GetString("range").value_or("all"));
  if (!IncludeVanilla(range) && !IncludeExpanded(range)) {
    return absl::InvalidArgumentError(
        absl::StrFormat("Invalid range: %s", range));
  }
 
  std::vector<editor::MessageData> vanilla;
  std::vector<editor::MessageData> expanded;
 
  if (IncludeVanilla(range)) {
    vanilla = editor::ReadAllTextData(const_cast<uint8_t*>(rom->data()),
                                      editor::kTextData);
  }
 
  if (IncludeExpanded(range)) {
    expanded = ReadExpandedMessages(*rom);
  }
 
  auto status =
      editor::ExportMessageBundleToJson(output_path, vanilla, expanded);
  if (!status.ok()) {
    return status;
  }
 
  formatter.BeginObject("Message Bundle Export");
  formatter.AddField("output", output_path);
  formatter.AddField("range", range);
  formatter.AddField("vanilla_count", static_cast<int>(vanilla.size()));
  formatter.AddField("expanded_count", static_cast<int>(expanded.size()));
  formatter.AddField("status", "success");
  formatter.EndObject();
 
  return absl::OkStatus();
}
 
// ===========================================================================
// New: Import Bundle Command
// ===========================================================================
 
absl::Status MessageImportBundleCommandHandler::Execute(
    Rom* rom, const resources::ArgumentParser& parser,
    resources::OutputFormatter& formatter) {
  auto file_path = parser.GetString("file").value();
  const bool apply = parser.HasFlag("apply");
  const bool strict = parser.HasFlag("strict");
#ifdef __EMSCRIPTEN__
  if (apply) {
    return absl::FailedPreconditionError(
        "message-import-bundle --apply is unavailable in WebAssembly because "
        "the browser filesystem cannot provide durable backup and readback "
        "guarantees");
  }
#endif
  auto range = NormalizeRange(parser.GetString("range").value_or("all"));
  if (!IncludeVanilla(range) && !IncludeExpanded(range)) {
    return absl::InvalidArgumentError(
        absl::StrFormat("Invalid range: %s", range));
  }
 
  auto entries_or = editor::LoadMessageBundleFromJson(file_path);
  if (!entries_or.ok()) {
    return entries_or.status();
  }
  auto entries = entries_or.value();
 
  formatter.BeginObject("Message Bundle Import");
  formatter.AddField("file", file_path);
  formatter.AddField("range", range);
  formatter.AddField("apply", apply);
  formatter.AddField("strict", strict);
  formatter.AddField("entries", static_cast<int>(entries.size()));
 
  bool has_errors = false;
  int parse_error_count = 0;
  int error_count = 0;
  int applied_updates = 0;
  bool has_vanilla_entries = false;
  bool has_expanded_entries = false;
 
  struct ParsedEntry {
    editor::MessageBundleEntry entry;
    editor::MessageParseResult parse;
    std::vector<std::string> line_warnings;
  };
  std::vector<ParsedEntry> parsed_entries;
  parsed_entries.reserve(entries.size());
 
  for (const auto& entry : entries) {
    if ((entry.bank == editor::MessageBank::kVanilla &&
         !IncludeVanilla(range)) ||
        (entry.bank == editor::MessageBank::kExpanded &&
         !IncludeExpanded(range))) {
      continue;
    }
 
    ParsedEntry parsed{entry,
                       editor::ParseMessageToDataWithDiagnostics(entry.text),
                       editor::ValidateMessageLineWidths(entry.text)};
    if (!parsed.parse.ok()) {
      has_errors = true;
      parse_error_count += static_cast<int>(parsed.parse.errors.size());
      error_count += static_cast<int>(parsed.parse.errors.size());
    }
    if (entry.bank == editor::MessageBank::kVanilla) {
      has_vanilla_entries = true;
    } else {
      has_expanded_entries = true;
    }
    parsed_entries.push_back(std::move(parsed));
  }
 
  formatter.BeginArray("messages");
  for (const auto& parsed : parsed_entries) {
    formatter.BeginObject();
    formatter.AddField("id", parsed.entry.id);
    formatter.AddField("bank", BankLabel(parsed.entry.bank));
    formatter.AddField("text", parsed.entry.text);
    formatter.AddField("encoded_length",
                       static_cast<int>(parsed.parse.bytes.size()));
    if (!parsed.line_warnings.empty()) {
      formatter.BeginArray("line_width_warnings");
      for (const auto& warning : parsed.line_warnings) {
        formatter.AddArrayItem(warning);
      }
      formatter.EndArray();
    }
    if (!parsed.parse.warnings.empty()) {
      formatter.BeginArray("warnings");
      for (const auto& warning : parsed.parse.warnings) {
        formatter.AddArrayItem(warning);
      }
      formatter.EndArray();
    }
    if (!parsed.parse.errors.empty()) {
      formatter.BeginArray("errors");
      for (const auto& error : parsed.parse.errors) {
        formatter.AddArrayItem(error);
      }
      formatter.EndArray();
    }
    formatter.EndObject();
  }
  formatter.EndArray();
 
  Rom owned_rom;
  Rom* active_rom = rom;
 
  if (apply) {
    if (active_rom == nullptr || !active_rom->is_loaded()) {
      auto rom_path = parser.GetString("rom");
      if (!rom_path.has_value() || rom_path->empty()) {
        std::string global_rom_path = absl::GetFlag(FLAGS_rom);
        if (!global_rom_path.empty()) {
          rom_path = global_rom_path;
        }
      }
      if (!rom_path.has_value() || rom_path->empty()) {
        error_count++;
        formatter.AddField("status", "error");
        formatter.AddField("error",
                           "ROM not loaded; provide --rom when using --apply");
        formatter.AddField("parse_error_count", parse_error_count);
        formatter.AddField("error_count", error_count);
        formatter.EndObject();
        return absl::OkStatus();
      }
      auto load_status = owned_rom.LoadFromFile(*rom_path);
      if (!load_status.ok()) {
        error_count++;
        formatter.AddField("status", "error");
        formatter.AddField("error", std::string(load_status.message()));
        formatter.AddField("parse_error_count", parse_error_count);
        formatter.AddField("error_count", error_count);
        formatter.EndObject();
        return absl::OkStatus();
      }
      active_rom = &owned_rom;
    }
 
    if (has_errors) {
      formatter.AddField("status", "error");
      formatter.AddField("error", "Parse errors present; no changes applied");
      formatter.AddField("parse_error_count", parse_error_count);
      formatter.AddField("error_count", error_count);
      formatter.EndObject();
      if (strict && parse_error_count > 0) {
        formatter.EndObject();
        formatter.Print();
        return absl::FailedPreconditionError(
            "Strict validation failed due to parse errors");
      }
      return absl::OkStatus();
    }
 
    std::optional<ProjectMutationContext> project_context;
    std::vector<uint8_t> disk_baseline;
    if (has_vanilla_entries || has_expanded_entries) {
      const absl::Status snapshot_status =
          VerifyCleanDiskSnapshot(*active_rom, &disk_baseline);
      if (!snapshot_status.ok()) {
        error_count++;
        formatter.AddField("status", "error");
        formatter.AddField("error", std::string(snapshot_status.message()));
        formatter.AddField("parse_error_count", parse_error_count);
        formatter.AddField("error_count", error_count);
        formatter.EndObject();
        return snapshot_status;
      }
 
      auto project_context_or = LoadProjectMutationContext(
          parser, *active_rom, "Message bundle apply");
      if (!project_context_or.ok()) {
        error_count++;
        formatter.AddField("status", "error");
        formatter.AddField("error",
                           std::string(project_context_or.status().message()));
        formatter.AddField("parse_error_count", parse_error_count);
        formatter.AddField("error_count", error_count);
        formatter.EndObject();
        return project_context_or.status();
      }
      project_context.emplace(std::move(project_context_or.value()));
    }
 
    std::optional<ExpandedMutationContext> expanded_context;
    if (IncludeExpanded(range) && has_expanded_entries) {
      auto context_or =
          PreflightExpandedMutation(project_context->project, *active_rom);
      if (!context_or.ok()) {
        error_count++;
        formatter.AddField("status", "error");
        formatter.AddField("error", std::string(context_or.status().message()));
        formatter.AddField("parse_error_count", parse_error_count);
        formatter.AddField("error_count", error_count);
        formatter.EndObject();
        return context_or.status();
      }
      expanded_context.emplace(std::move(context_or.value()));
    }
 
    // Build both replacement banks and validate every selected ID before the
    // first ROM write. This keeps a bad expanded ID from landing after a
    // successful vanilla mutation in a mixed bundle.
    std::vector<editor::MessageData> vanilla_messages;
    std::vector<std::pair<int, std::vector<uint8_t>>> vanilla_edits;
    if (IncludeVanilla(range) && has_vanilla_entries) {
      if (active_rom->size() >
          static_cast<size_t>(std::numeric_limits<int>::max())) {
        formatter.EndObject();
        return absl::OutOfRangeError(
            "ROM is too large for bounded vanilla-message parsing");
      }
      vanilla_messages = editor::ReadAllTextData(
          const_cast<uint8_t*>(active_rom->data()), editor::kTextData,
          static_cast<int>(active_rom->size()));
    }
 
    std::vector<std::string> expanded_texts;
    if (expanded_context.has_value()) {
      const auto expanded_messages = ReadExpandedMessages(
          *active_rom, expanded_context->start, expanded_context->end);
      auto bank_size_status = ValidateExpandedMessageBankSize(
          expanded_messages.size(), *expanded_context);
      if (!bank_size_status.ok()) {
        formatter.AddField("status", "error");
        formatter.AddField("error", std::string(bank_size_status.message()));
        formatter.EndObject();
        return bank_size_status;
      }
      expanded_texts.reserve(expanded_messages.size());
      for (const auto& message : expanded_messages) {
        expanded_texts.push_back(message.RawString);
      }
    }
 
    for (const auto& parsed : parsed_entries) {
      if (parsed.entry.bank == editor::MessageBank::kVanilla) {
        if (parsed.entry.id < 0 ||
            parsed.entry.id >= static_cast<int>(vanilla_messages.size())) {
          has_errors = true;
          error_count++;
          continue;
        }
        vanilla_edits.emplace_back(parsed.entry.id, parsed.parse.bytes);
      } else {
        if (!expanded_context.has_value()) {
          continue;
        }
        const auto id_status =
            ValidateExpandedMessageId(parsed.entry.id, *expanded_context);
        if (!id_status.ok()) {
          has_errors = true;
          error_count++;
          continue;
        }
        if (parsed.entry.id >= static_cast<int>(expanded_texts.size())) {
          expanded_texts.resize(parsed.entry.id + 1);
        }
        expanded_texts[parsed.entry.id] = parsed.entry.text;
      }
      applied_updates++;
    }
 
    std::optional<editor::VanillaMessageSavePlan> vanilla_plan;
    std::optional<size_t> expected_vanilla_count;
    std::string write_policy_warning;
    if (!has_errors && IncludeVanilla(range) && has_vanilla_entries) {
      auto edit_or = PlanVanillaEdits(project_context->project, *active_rom,
                                      vanilla_edits, &write_policy_warning);
      if (!edit_or.ok()) {
        formatter.AddField("status", "error");
        formatter.AddField("error", std::string(edit_or.status().message()));
        formatter.EndObject();
        return edit_or.status();
      }
      AddVanillaPlanReport(formatter, *edit_or);
      expected_vanilla_count = edit_or->expected_count;
      vanilla_plan.emplace(std::move(edit_or->plan));
    }
 
    if (expanded_context.has_value() &&
        !expanded_context->policy_warning.empty()) {
      if (!write_policy_warning.empty()) {
        absl::StrAppend(&write_policy_warning, "; ");
      }
      absl::StrAppend(&write_policy_warning, expanded_context->policy_warning);
    }
    if (!write_policy_warning.empty()) {
      formatter.AddField("write_policy_warning", write_policy_warning);
    }
 
    if (has_errors) {
      formatter.AddField("status", "error");
      formatter.AddField("error", "Invalid message IDs; no changes applied");
    } else {
      ScopedRomTransaction transaction(*active_rom);
      if (vanilla_plan.has_value()) {
        auto status =
            editor::ApplyVanillaMessageSavePlan(active_rom, *vanilla_plan);
        if (!status.ok()) {
          formatter.AddField("status", "error");
          formatter.AddField("error", std::string(status.message()));
          formatter.EndObject();
          return status;
        }
      }
 
      if (expanded_context.has_value()) {
        auto status = editor::WriteExpandedTextData(
            active_rom, expanded_context->start, expanded_context->end,
            expanded_texts);
        if (!status.ok()) {
          formatter.AddField("status", "error");
          formatter.AddField("error", std::string(status.message()));
          formatter.EndObject();
          return status;
        }
      }
 
      if (active_rom->dirty() && project_context.has_value()) {
        const absl::Status unchanged_status = VerifyDiskSnapshotUnchanged(
            project_context->canonical_rom_path, disk_baseline);
        if (!unchanged_status.ok()) {
          formatter.AddField("status", "error");
          formatter.AddField("error", std::string(unchanged_status.message()));
          formatter.EndObject();
          return unchanged_status;
        }
        Rom::SaveSettings save_settings;
        save_settings.save_new = false;
        save_settings.require_backup = true;
        save_settings.filename = project_context->canonical_rom_path.string();
        auto save_status = active_rom->SaveToFile(save_settings);
        if (!save_status.ok()) {
          formatter.AddField("status", "error");
          formatter.AddField("error", std::string(save_status.message()));
          formatter.EndObject();
          return save_status;
        }
      }
      transaction.Commit();
 
      if (project_context.has_value()) {
        const absl::Status readback_status =
            VerifySavedRom(*active_rom, project_context->canonical_rom_path,
                           vanilla_plan, expected_vanilla_count);
        if (!readback_status.ok()) {
          formatter.AddField("status", "error");
          formatter.AddField("error", std::string(readback_status.message()));
          formatter.EndObject();
          return readback_status;
        }
      }
      formatter.AddField("status", "success");
      formatter.AddField("applied_messages", applied_updates);
      if (project_context.has_value()) {
        formatter.AddField("readback_verified", true);
      }
    }
  } else {
    if (!has_errors && IncludeVanilla(range) && has_vanilla_entries) {
      std::vector<std::pair<int, std::vector<uint8_t>>> vanilla_edits;
      for (const auto& parsed : parsed_entries) {
        if (parsed.entry.bank == editor::MessageBank::kVanilla) {
          vanilla_edits.emplace_back(parsed.entry.id, parsed.parse.bytes);
        }
      }
      AddVanillaApplyPreflight(parser, rom, vanilla_edits, formatter);
    }
    formatter.AddField("status", has_errors ? "error" : "success");
  }
 
  formatter.AddField("error_count", error_count);
  formatter.AddField("parse_error_count", parse_error_count);
  formatter.EndObject();
  if (strict && parse_error_count > 0) {
    formatter.EndObject();
    formatter.Print();
    return absl::FailedPreconditionError("Strict validation failed");
  }
  return absl::OkStatus();
}
 
// ===========================================================================
// New: Message Write Command
// ===========================================================================
 
namespace {
 
// message-write --range vanilla: replaces one vanilla message through the
// same checks as message-import-bundle --apply (clean disk snapshot, project
// and manifest policy, dictionary encoding, backup, readback).
absl::Status WriteVanillaMessage(Rom* rom,
                                 const resources::ArgumentParser& parser,
                                 resources::OutputFormatter& formatter, int id,
                                 const std::string& text) {
#ifdef __EMSCRIPTEN__
  return absl::FailedPreconditionError(
      "message-write --range vanilla is unavailable in WebAssembly because "
      "the browser filesystem cannot provide durable backup and readback "
      "guarantees");
#endif
  if (rom == nullptr || !rom->is_loaded()) {
    return absl::FailedPreconditionError("ROM not loaded; provide --rom");
  }
  const editor::MessageParseResult parse =
      editor::ParseMessageToDataWithDiagnostics(text);
  if (!parse.ok()) {
    return absl::InvalidArgumentError(absl::StrCat(
        "Message text does not encode: ", absl::StrJoin(parse.errors, "; ")));
  }
 
  std::vector<uint8_t> disk_baseline;
  RETURN_IF_ERROR(VerifyCleanDiskSnapshot(*rom, &disk_baseline));
  ASSIGN_OR_RETURN(
      ProjectMutationContext project_context,
      LoadProjectMutationContext(parser, *rom, "Vanilla message write"));
  std::vector<std::pair<int, std::vector<uint8_t>>> edits;
  edits.emplace_back(id, parse.bytes);
  std::string policy_warning;
  ASSIGN_OR_RETURN(
      VanillaEditPlan edit,
      PlanVanillaEdits(project_context.project, *rom, edits, &policy_warning));
 
  formatter.BeginObject("Message Write Result");
  formatter.AddHexField("id", static_cast<uint64_t>(id), 3);
  formatter.AddField("range", "vanilla");
  formatter.AddField("text", text);
  AddVanillaPlanReport(formatter, edit);
  if (!policy_warning.empty()) {
    formatter.AddField("write_policy_warning", policy_warning);
  }
  const auto line_warnings = editor::ValidateMessageLineWidths(text);
  if (!line_warnings.empty()) {
    formatter.BeginArray("line_width_warnings");
    for (const auto& warning : line_warnings) {
      formatter.AddArrayItem(warning);
    }
    formatter.EndArray();
  }
 
  // Close the result object on every exit, so a failure still prints valid
  // JSON with its error (a DataLoss error names the backup to restore).
  auto finish = [&formatter](absl::Status status) {
    if (status.ok()) {
      formatter.AddField("status", "success");
      formatter.AddField("readback_verified", true);
    } else {
      formatter.AddField("status", "error");
      formatter.AddField("error", std::string(status.message()));
    }
    formatter.EndObject();
    return status;
  };
 
  ScopedRomTransaction transaction(*rom);
  absl::Status status = editor::ApplyVanillaMessageSavePlan(rom, edit.plan);
  if (status.ok() && rom->dirty()) {
    status = VerifyDiskSnapshotUnchanged(project_context.canonical_rom_path,
                                         disk_baseline);
    if (status.ok()) {
      Rom::SaveSettings save_settings;
      save_settings.save_new = false;
      save_settings.require_backup = true;
      save_settings.filename = project_context.canonical_rom_path.string();
      status = rom->SaveToFile(save_settings);
    }
  }
  if (!status.ok()) {
    return finish(status);  // the transaction rolls the ROM back
  }
  transaction.Commit();
  return finish(VerifySavedRom(*rom, project_context.canonical_rom_path,
                               edit.plan, edit.expected_count));
}
 
// message-write --range expanded: replaces one expanded message and saves the
// bound project ROM with the same clean-snapshot, backup and readback checks
// as the vanilla range. Success is reported only after the bytes are on disk.
absl::Status WriteExpandedMessage(Rom* rom,
                                  const resources::ArgumentParser& parser,
                                  resources::OutputFormatter& formatter, int id,
                                  const std::string& text) {
#ifdef __EMSCRIPTEN__
  return absl::FailedPreconditionError(
      "message-write --range expanded is unavailable in WebAssembly because "
      "the browser filesystem cannot provide durable backup and readback "
      "guarantees");
#endif
  if (rom == nullptr || !rom->is_loaded()) {
    return absl::FailedPreconditionError("ROM not loaded; provide --rom");
  }
  const auto warnings = editor::ValidateMessageLineWidths(text);
  const auto bytes = editor::ParseMessageToData(text);
  if (bytes.empty() && !text.empty()) {
    return absl::InvalidArgumentError("Encoding produced no bytes");
  }
 
  ASSIGN_OR_RETURN(
      ProjectMutationContext project_context,
      LoadProjectMutationContext(parser, *rom, "Expanded message mutation"));
  ASSIGN_OR_RETURN(ExpandedMutationContext context,
                   PreflightExpandedMutation(project_context.project, *rom));
  RETURN_IF_ERROR(ValidateExpandedMessageId(id, context));
  std::vector<uint8_t> disk_baseline;
  RETURN_IF_ERROR(VerifyCleanDiskSnapshot(*rom, &disk_baseline));
 
  const auto expanded = ReadExpandedMessages(*rom, context.start, context.end);
  RETURN_IF_ERROR(ValidateExpandedMessageBankSize(expanded.size(), context));
  std::vector<std::string> all_texts;
  all_texts.reserve(expanded.size());
  for (const auto& msg : expanded) {
    all_texts.push_back(msg.RawString);
  }
  if (id >= static_cast<int>(all_texts.size())) {
    all_texts.resize(id + 1);
  }
  all_texts[id] = text;
 
  formatter.BeginObject("Message Write Result");
  formatter.AddField("id", id);
  formatter.AddField("range", "expanded");
  formatter.AddField("text", text);
  formatter.AddField("encoded_length", static_cast<int>(bytes.size()));
  if (!context.policy_warning.empty()) {
    formatter.AddField("write_policy_warning", context.policy_warning);
  }
  if (!warnings.empty()) {
    formatter.BeginArray("line_width_warnings");
    for (const auto& warning : warnings) {
      formatter.AddArrayItem(warning);
    }
    formatter.EndArray();
  }
 
  // Close the result object on every exit, so a failure still prints valid
  // JSON with its error (a DataLoss error names the backup to restore).
  auto finish = [&formatter](absl::Status status) {
    if (status.ok()) {
      formatter.AddField("status", "success");
      formatter.AddField("readback_verified", true);
    } else {
      formatter.AddField("status", "error");
      formatter.AddField("error", std::string(status.message()));
    }
    formatter.EndObject();
    return status;
  };
 
  ScopedRomTransaction transaction(*rom);
  absl::Status status =
      editor::WriteExpandedTextData(rom, context.start, context.end, all_texts);
  if (status.ok() && rom->dirty()) {
    status = VerifyDiskSnapshotUnchanged(project_context.canonical_rom_path,
                                         disk_baseline);
    if (status.ok()) {
      Rom::SaveSettings save_settings;
      save_settings.save_new = false;
      save_settings.require_backup = true;
      save_settings.filename = project_context.canonical_rom_path.string();
      status = rom->SaveToFile(save_settings);
    }
  }
  if (!status.ok()) {
    return finish(status);  // the transaction rolls the ROM back
  }
  transaction.Commit();
  return finish(VerifySavedRom(*rom, project_context.canonical_rom_path,
                               std::nullopt, std::nullopt));
}
 
}  // namespace
 
absl::Status MessageWriteCommandHandler::Execute(
    Rom* rom, const resources::ArgumentParser& parser,
    resources::OutputFormatter& formatter) {
  auto id_or = parser.GetInt("id");
  if (!id_or.ok())
    return id_or.status();
  int msg_id = id_or.value();
 
  auto text = parser.GetString("text").value();
 
  const std::string range =
      NormalizeRange(parser.GetString("range").value_or("expanded"));
  if (range == "vanilla") {
    return WriteVanillaMessage(rom, parser, formatter, msg_id, text);
  }
  if (range != "expanded") {
    return absl::InvalidArgumentError(absl::StrFormat(
        "message-write --range must be vanilla or expanded, got %s", range));
  }
  return WriteExpandedMessage(rom, parser, formatter, msg_id, text);
}
 
// ===========================================================================
// New: Export BIN Command
// ===========================================================================
 
absl::Status MessageExportBinCommandHandler::Execute(
    Rom* rom, const resources::ArgumentParser& parser,
    resources::OutputFormatter& formatter) {
  auto output_path = parser.GetString("output").value();
  auto range = parser.GetString("range").value_or("expanded");
 
  int start, end_addr;
  if (range == "expanded") {
    start = editor::GetExpandedTextDataStart();
    end_addr = editor::GetExpandedTextDataEnd();
  } else {
    start = editor::kTextData;
    end_addr = editor::kTextDataEnd;
  }
 
  // Find the actual end of data (scan for 0xFF terminator)
  const uint8_t* data = rom->data();
  int data_end = start;
  while (data_end <= end_addr && data[data_end] != 0xFF) {
    data_end++;
  }
  if (data_end <= end_addr) {
    data_end++;  // Include the 0xFF terminator
  }
 
  int size = data_end - start;
 
  std::ofstream file(output_path, std::ios::binary);
  if (!file.is_open()) {
    return absl::InternalError(
        absl::StrFormat("Cannot write to file: %s", output_path));
  }
  file.write(reinterpret_cast<const char*>(data + start), size);
  file.close();
 
  formatter.BeginObject("BIN Export Result");
  formatter.AddField("output", output_path);
  formatter.AddField("range", range);
  formatter.AddHexField("start_address", start, 6);
  formatter.AddHexField("end_address", data_end - 1, 6);
  formatter.AddField("size_bytes", size);
  formatter.AddField("status", "success");
  formatter.EndObject();
 
  return absl::OkStatus();
}
 
// ===========================================================================
// New: Export ASM Command
// ===========================================================================
 
absl::Status MessageExportAsmCommandHandler::Execute(
    Rom* rom, const resources::ArgumentParser& parser,
    resources::OutputFormatter& formatter) {
  auto output_path = parser.GetString("output").value();
  auto range = parser.GetString("range").value_or("expanded");
 
  int start;
  uint32_t snes_addr;
  if (range == "expanded") {
    start = editor::GetExpandedTextDataStart();
    snes_addr = 0x2F8000;
  } else {
    start = editor::kTextData;
    snes_addr = 0x1C0000;
  }
 
  // Read messages from the specified region
  auto messages =
      editor::ReadAllTextData(const_cast<uint8_t*>(rom->data()), start);
 
  std::ofstream file(output_path);
  if (!file.is_open()) {
    return absl::InternalError(
        absl::StrFormat("Cannot write to file: %s", output_path));
  }
 
  // Write ASM header
  file << "; Auto-generated message data\n";
  file << absl::StrFormat("; Source: %s region\n", range);
  file << absl::StrFormat("; Messages: %d\n\n", messages.size());
  file << absl::StrFormat("org $%06X\n\n", snes_addr);
 
  // Write each message as db directives
  for (const auto& msg : messages) {
    file << absl::StrFormat("; Message $%02X: %s\n", msg.ID,
                            msg.ContentsParsed.substr(0, 60));
    file << "db ";
    for (size_t i = 0; i < msg.Data.size(); ++i) {
      if (i > 0)
        file << ", ";
      file << absl::StrFormat("$%02X", msg.Data[i]);
    }
    file << ", $7F  ; terminator\n\n";
  }
 
  // End-of-region marker
  file << "db $FF  ; end of message data\n";
  file.close();
 
  formatter.BeginObject("ASM Export Result");
  formatter.AddField("output", output_path);
  formatter.AddField("range", range);
  formatter.AddField("messages_exported", static_cast<int>(messages.size()));
  formatter.AddField("status", "success");
  formatter.EndObject();
 
  return absl::OkStatus();
}
 
absl::Status MessageSourceSyncCommandHandler::Execute(
    Rom* rom, const resources::ArgumentParser& parser,
    resources::OutputFormatter& formatter) {
  const std::string project_path = parser.GetString("project").value();
  const std::string incoming_path = parser.GetString("file").value();
  const bool write = parser.HasFlag("write");
 
  project::YazeProject source_project;
  auto& resource_labels = zelda3::GetResourceLabels();
  absl::Status open_status;
  {
    ScopedHackManifestBindingRestore restore_manifest(resource_labels);
    try {
      open_status = source_project.Open(project_path);
    } catch (const std::exception& error) {
      return absl::InvalidArgumentError(absl::StrFormat(
          "Cannot load project '%s': %s", project_path, error.what()));
    } catch (...) {
      return absl::InvalidArgumentError(absl::StrFormat(
          "Cannot load project '%s': unknown project parse error",
          project_path));
    }
  }
  if (!open_status.ok()) {
    return absl::Status(open_status.code(),
                        absl::StrFormat("Cannot load project '%s': %s",
                                        project_path, open_status.message()));
  }
  if (absl::Status manifest_status =
          EnsureConfiguredHackManifestLoaded(&source_project, project_path);
      !manifest_status.ok()) {
    return manifest_status;
  }
 
  editor::MessageSourceSyncOptions options{
      .write = write,
      .expected_source_sha256 =
          parser.GetString("expected-source-sha256").value_or(""),
  };
  auto result_or =
      editor::SyncMessageSource(source_project, incoming_path, options);
  if (!result_or.ok()) {
    return result_or.status();
  }
  const auto& result = *result_or;
 
  formatter.BeginObject("Message Source Sync");
  formatter.AddField("status", "success");
  formatter.AddField("mode", write ? "write" : "dry-run");
  formatter.AddField("changed", result.changed);
  formatter.AddField("wrote", result.wrote);
  formatter.AddField("canonical_bundle", result.canonical_bundle_path.string());
  formatter.AddField("generated_asm_include",
                     result.generated_asm_include_path.string());
  formatter.AddHexField("first_expanded_id", result.first_expanded_id, 3);
  formatter.AddHexField("last_expanded_id", result.last_expanded_id, 3);
  formatter.AddField("expanded_count", result.expanded_count);
  formatter.AddField("incoming_updates", result.incoming_updates);
  formatter.AddField("encoded_size", static_cast<int>(result.encoded_size));
  formatter.AddField("capacity", static_cast<int>(result.capacity));
  formatter.AddField("source_sha256_before", result.source_sha256_before);
  formatter.AddField("proposed_source_sha256", result.proposed_source_sha256);
  formatter.EndObject();
  return absl::OkStatus();
}
 
}  // namespace handlers
}  // namespace cli
}  // namespace yaze