esp-modkit 0.1.0

data/lib/esp/mw/operations.rb

@@ -0,0 +1,374 @@
+require 'fileutils'
+require 'json'
+
+module Esp
+  module Mw
+    # The Morrowind plugin's half of the service layer. Same contract as
+    # Esp::Operations (string-keyed params hash in, plain Hash out) — these
+    # are the ops that decode TES3 records, drive tes3conv, or otherwise know
+    # what a "mod" is. Frontends never call this module directly; they route
+    # through Esp::Operations.dispatch(op, input).
+    #
+    # Every op resolves the project root from `Esp::ActiveProject.resolve`
+    # (step 23.5 slice 1) so an `open_project` request actually moves where
+    # build/lint/etc. operate — they no longer silently target Esp::ROOT.
+    # Precedence: explicit `root:` in params > active project > Esp::ROOT.
+    #
+    # InputError is aliased from the shell so plugin ops raise the same class
+    # the frontends rescue. Loader / Preflight / Tes3conv error classes are
+    # registered with Esp::Operations::ERROR_CODES at the bottom of this file
+    # — they couldn't be in the shell table because the plugin hadn't loaded
+    # yet when that table was built.
+    module Operations
+      InputError = Esp::Operations::InputError
+
+      PLUGIN_EXT = /\.(esp|esm|omwaddon)\z/i
+
+      class << self
+        def build(params)
+          mod = require_mod(params)
+          build_one(mod, params['locale'], root: project_root(params))
+        end
+
+        # Build every mod under mods/. Returns one entry per mod, same shape
+        # as a single build, so an agent can fan out without N calls.
+        def build_all(params)
+          root = project_root(params)
+          results = Esp::Mw::Builder.discover_mods(root: root).map do |mod|
+            build_one(mod, params['locale'], root: root)
+          end
+          { results: results }
+        end
+
+        # Import an existing plugin into source. `plugin` is either a
+        # filesystem path or, if it's a bare name (no path separator), a
+        # plugin name resolved against the OpenMW config's installed plugins.
+        # `name` defaults to the resolved file's basename. Source mod lands
+        # under the active project's mods/, not the toolchain repo's.
+        def unpack(params)
+          plugin = params['plugin']
+          raise InputError, Esp.t('errors.operations.missing_field', field: 'plugin') if blank?(plugin)
+
+          source = resolve_plugin(plugin, params)
+          raise InputError, Esp.t('errors.operations.plugin_not_found', plugin: plugin) unless source
+
+          root = project_root(params)
+          name = params['name'] || File.basename(source).sub(PLUGIN_EXT, '')
+          dst = File.join(root, 'mods', name, "#{name}.json")
+          FileUtils.mkdir_p(File.dirname(dst))
+          Esp::Mw::Tes3conv.convert(source, dst)
+          { plugin: plugin, source: source, mod: name, output: Esp::Operations.relative(dst, root: root) }
+        end
+
+        # Make a built dist/<mod>.esp available to a game engine. Two
+        # additive install paths (compose freely):
+        #
+        # - **OpenMW** (default): register the project's dist/ + the
+        #   plugin with openmw.cfg via `data=` + `content=`. Idempotent —
+        #   an already-present line reports `added: false`. Skipped when
+        #   `params['register_openmw']` is explicitly false (e.g. an
+        #   original-engine user who only wants the copy).
+        # - **Copy to a Data Files dir** (original engine, step 23.5
+        #   slice 4): pass `params['copy_to']` with a path, or
+        #   `params['to_data_files'] => true` to auto-resolve the user's
+        #   vanilla Morrowind Data Files dir via Esp::Mw::DataFiles. The
+        #   copy is "always overwrite" so a rebuild swaps the live plugin
+        #   without the user touching anything.
+        #
+        # `data=` always points at the active project's dist/, so OpenMW
+        # picks up the build output from wherever the project lives.
+        def install(params)
+          mod = require_mod(params)
+          root = project_root(params)
+          esp = File.join(root, 'dist', "#{mod}.esp")
+          unless File.exist?(esp)
+            raise InputError,
+                  Esp.t('errors.operations.build_first', esp: Esp::Operations.relative(esp, root: root))
+          end
+
+          payload = { mod: mod }
+          payload.merge!(register_openmw(mod, root, params)) unless params['register_openmw'] == false
+
+          if (target = copy_target(params))
+            payload[:copied_to] = copy_built_plugin(esp, mod, target)
+          end
+
+          payload
+        end
+
+        # List plugins installed in the OpenMW config's data directories,
+        # with active flag + load order. `config` overrides the cfg path.
+        def plugins_list(params = {})
+          cfg = openmw_config(params)
+          { openmw_cfg: cfg.path, exists: cfg.exist?, plugins: cfg.installed_plugins }
+        end
+
+        def i18n_check(params)
+          mod = require_mod(params)
+          source = Esp::Mw::Loader.resolve(mod, root: project_root(params))
+          { mod: mod, default_locale: Esp::Mw::I18n::DEFAULT_LOCALE,
+            locales: Esp::Mw::I18n.check(File.dirname(source)) }
+        end
+
+        # Read a mod's records as structured data. Format-agnostic — runs the
+        # source through the loader, so .rb/.py/.js/.ts all read back too.
+        def records_read(params)
+          mod = require_mod(params)
+          root = project_root(params)
+          source = Esp::Mw::Loader.resolve(mod, root: root)
+          records = Esp::Mw::Loader.load(source)
+          { mod: mod, source: Esp::Operations.relative(source, root: root),
+            count: records.size, records: records }
+        end
+
+        # Upsert one record into a mod's .json source, keyed by (type, id).
+        # JSON only: polyglot sources are programs, not editable data, so we
+        # refuse rather than silently no-op. Header is matched by type alone
+        # (one per file); every other record needs an id.
+        def record_write(params)
+          mod = require_mod(params)
+          record = params['record']
+          unless record.is_a?(Hash)
+            raise InputError,
+                  Esp.t('errors.operations.missing_object', field: 'record')
+          end
+
+          type = record['type']
+          raise InputError, Esp.t('errors.operations.record_needs_type') if blank?(type)
+          if type != 'Header' && blank?(record['id'])
+            raise InputError, Esp.t('errors.operations.record_needs_id')
+          end
+
+          root = project_root(params)
+          source = json_source!(mod, root: root)
+          records = JSON.parse(File.read(source))
+          action, index = upsert(records, record)
+          File.write(source, "#{JSON.pretty_generate(records)}\n")
+          { mod: mod, source: Esp::Operations.relative(source, root: root), action: action,
+            type: type, id: record['id'], index: index }
+        end
+
+        # Author dialogue from a JSON spec (the data-driven analog of the Ruby
+        # `dialogue { }` DSL) into a mod's .json source. A topic is written
+        # wholesale: any existing DIAL/INFO records for the same topics are
+        # replaced, so re-authoring never leaves orphan info records.
+        def dialogue_write(params)
+          mod = require_mod(params)
+          spec = params['spec']
+          unless spec.is_a?(Hash) || spec.is_a?(Array)
+            raise InputError, Esp.t('errors.operations.missing_object', field: 'spec')
+          end
+
+          built = Esp::Mw::DialogueDsl.from_spec(spec)
+          topics = built.select { |r| r['type'] == 'Dialogue' }.map { |r| r['id'] }
+          root = project_root(params)
+          source = json_source!(mod, root: root)
+          records = strip_dialogue(JSON.parse(File.read(source)), topics).concat(built)
+          File.write(source, "#{JSON.pretty_generate(records)}\n")
+          { mod: mod, source: Esp::Operations.relative(source, root: root), topics: topics,
+            records_written: built.size, records: built }
+        end
+
+        def lint(params)
+          mod = require_mod(params)
+          index = require_index!
+          records = Esp::Mw::Loader.load(Esp::Mw::Loader.resolve(mod, root: project_root(params)))
+          issues = Esp::Mw::Linter.new(records, index).issues
+          {
+            mod: mod,
+            errors: issues.count { |i| i.severity == :error },
+            warnings: issues.count { |i| i.severity == :warning },
+            issues: issues.map(&:to_h)
+          }
+        end
+
+        def scaffold(params)
+          mod = require_mod(params)
+          root = project_root(params)
+          result = Esp::Mw::Scaffolder.create(
+            mod,
+            format: params['format'] || Esp::Mw::Scaffolder::DEFAULT_FORMAT,
+            author: params['author'],
+            description: params['description'],
+            force: params['force'] || false,
+            root: root
+          )
+          { mod: result.mod, format: result.format,
+            source: Esp::Operations.relative(result.source, root: root),
+            readme: Esp::Operations.relative(result.readme, root: root) }
+        end
+
+        def extract_scripts(params)
+          mod = require_mod(params)
+          result = Esp::Mw::ScriptExtractor.extract!(mod, root: project_root(params))
+          { mod: mod, extracted: result.extracted, skipped: result.skipped }
+        end
+
+        def refs_find(params)
+          index = require_index!
+          criteria = { query: params['q'], type: params['type'],
+                       like: params['like'], exact: params['exact'] }
+          rows = index.find(**criteria, limit: (params['limit'] || 100).to_i)
+          total = index.count_matching(**criteria)
+          if params['show']
+            records = rows.map { |r| index.fetch_record(r['source_esm'], r['record_index']) }
+            { records: records, count: records.size, total: total }
+          else
+            { matches: rows, count: rows.size, total: total }
+          end
+        end
+
+        # Map a batch of reference ids → record type via the SQLite reference
+        # index. Backs the cell-view marker colouring (step 21 slice 3) — one
+        # call resolves all of a cell's references in a single SQL.
+        def refs_resolve(params)
+          index = require_index!
+          ids = Array(params['ids']).map(&:to_s)
+          { types: index.types_for(ids) }
+        end
+
+        private
+
+        # The project root every op resolves against. Same precedence chain
+        # used by diff/approve/reject via Esp::Operations#vcs_root, so build
+        # and diff target the same tree by default.
+        def project_root(params)
+          Esp::ActiveProject.resolve(params)
+        end
+
+        def build_one(mod, locale, root:)
+          result = Esp::Mw::Builder.build(mod, root: root, locale: locale)
+          { mod: mod, output: Esp::Operations.relative(result.output, root: root), logs: result.logs }
+        end
+
+        def blank?(value)
+          value.nil? || value.to_s.empty?
+        end
+
+        # Resolve a mod's source and insist it's JSON.
+        def json_source!(mod, root:)
+          source = Esp::Mw::Loader.resolve(mod, root: root)
+          ext = File.extname(source)
+          return source if ext == '.json'
+
+          raise InputError, Esp.t('errors.operations.json_only', file: File.basename(source), ext: ext)
+        end
+
+        # Replace the matching record in place, else append. Returns
+        # [:updated | :inserted, index].
+        def upsert(records, record)
+          idx = records.index { |r| same_record?(r, record) }
+          if idx
+            records[idx] = record
+            [:updated, idx]
+          else
+            records << record
+            [:inserted, records.size - 1]
+          end
+        end
+
+        def same_record?(existing, record)
+          return false unless existing['type'] == record['type']
+          return true if record['type'] == 'Header'
+
+          existing['id'] == record['id']
+        end
+
+        # Drop the DIAL record for each named topic plus its INFO records
+        # (id "<topic>_<n>"), so a re-authored topic replaces cleanly.
+        def strip_dialogue(records, topics)
+          patterns = topics.map { |n| /\A#{Regexp.escape(n)}_\d+\z/ }
+          records.reject do |r|
+            (r['type'] == 'Dialogue' && topics.include?(r['id'])) ||
+              (r['type'] == 'DialogueInfo' && patterns.any? { |p| p.match?(r['id'].to_s) })
+          end
+        end
+
+        def register_openmw(mod, root, params)
+          cfg = openmw_config(params)
+          raise InputError, Esp.t('errors.operations.no_cfg', path: cfg.path) unless cfg.exist?
+
+          lines = [%(data="#{File.join(root, 'dist')}"), "content=#{mod}.esp"]
+          cfg.backup_once_per_day
+          actions = lines.map { |line| { line: line, added: cfg.append(line) } }
+          { openmw_cfg: cfg.path, actions: actions }
+        end
+
+        # Decide which directory to copy the built plugin into:
+        #   - `copy_to` (explicit path) wins.
+        #   - `to_data_files: true` (or "true" string) auto-resolves the
+        #     vanilla Data Files dir via Esp::Mw::DataFiles.resolve —
+        #     honours $MORROWIND_DATA, then the per-OS Steam/GOG defaults
+        #     (the same detector `refs unpack` already uses).
+        # Returns the resolved path, or nil if neither was requested.
+        # Raises InputError when to_data_files is asked but the auto-
+        # detected path doesn't exist (no Morrowind install on this box).
+        def copy_target(params)
+          explicit = params['copy_to']
+          return File.expand_path(explicit) if explicit && !explicit.to_s.empty?
+
+          truthy = params['to_data_files']
+          return nil unless [true, 'true'].include?(truthy)
+
+          dest = Esp::Mw::DataFiles.resolve
+          raise InputError, Esp.t('errors.operations.no_data_files', path: dest) unless File.directory?(dest)
+
+          dest
+        end
+
+        def copy_built_plugin(esp, mod, target)
+          FileUtils.mkdir_p(target)
+          dst = File.join(target, "#{mod}.esp")
+          FileUtils.cp(esp, dst)
+          dst
+        end
+
+        def openmw_config(params)
+          path = params['config']
+          path.nil? || path.to_s.empty? ? Esp::Mw::OpenmwConfig.new : Esp::Mw::OpenmwConfig.new(path)
+        end
+
+        # A real path wins; otherwise a bare name (no separator) is matched
+        # against installed plugins by filename, with or without extension.
+        def resolve_plugin(plugin, params)
+          return plugin if File.exist?(plugin)
+          return nil if plugin.include?('/') || plugin.include?('\\')
+
+          base = File.basename(plugin)
+          stem = base.sub(PLUGIN_EXT, '')
+          match = openmw_config(params).installed_plugins.find do |p|
+            p[:name].casecmp?(base) || p[:name].sub(PLUGIN_EXT, '').casecmp?(stem)
+          end
+          match && match[:path]
+        end
+
+        def require_mod(params)
+          mod = params['mod']
+          raise InputError, Esp.t('errors.operations.missing_field', field: 'mod') if blank?(mod)
+
+          mod
+        end
+
+        def require_index!
+          index = Esp::Mw::ReferenceIndex.new
+          raise InputError, Esp.t('errors.no_index') unless File.exist?(index.db_path)
+
+          index
+        end
+      end
+    end
+  end
+end
+
+# Plugin error classes — extend the shell's caller-errors table so both
+# frontends rescue them automatically. Done after the module body so the
+# constant references resolve.
+Esp::Operations.register_error(Esp::Mw::Loader::LoadError,           'load_error')
+Esp::Operations.register_error(Esp::Mw::Preflight::ValidationError,  'validation_error')
+Esp::Operations.register_error(Esp::Mw::Tes3conv::ConvertFailed,     'tes3conv_failed')
+Esp::Operations.register_error(Esp::Mw::Tes3conv::NotFound,          'tes3conv_not_found')
+
+# Announce this plugin to the registry. 'mw' is the id that lands in a
+# project's .esp/project.json `game:` field; Esp::Operations.dispatch
+# routes game ops here for projects with that game.
+Esp::Plugins.register('mw', label: 'Morrowind', operations: Esp::Mw::Operations)

data/lib/esp/mw/preflight.rb

@@ -0,0 +1,161 @@
+require 'json'
+
+module Esp
+  module Mw
+    # Resolves text_source into inline text and regenerates Script-record
+    # subrecords (SCHD header + SCVR vars + SCDT bytecode placeholder) into
+    # the form tes3conv expects. Mutates records in place.
+    #
+    # Validation rules:
+    # - Source must be pure ASCII (MWScript's compiler is silent on UTF-8).
+    # - Variable identifiers must be <= 20 chars (MWScript truncates ~20-23).
+    # - Warn (don't fail) when a script's `Begin <name>` doesn't match its
+    #   record id; vanilla often disagrees so this is intentionally soft.
+    module Preflight
+      class ValidationError < StandardError; end
+
+      VAR_DECL_RE = /^\s*(short|long|float)\s+([A-Za-z_]\w*)\b/i
+      BEGIN_RE    = /^\s*begin\s+([A-Za-z_]\w*)\b/i
+      NAME_LIMIT  = 20
+
+      # Walks records and processes Script + Cell entries. Returns a list
+      # of log lines (info + warnings) for the caller to print.
+      def self.process!(records, source_dir:)
+        logs = []
+        plugin_ids = collect_plugin_ids(records)
+        records.each do |record|
+          case record['type']
+          when 'Script' then logs.concat(process_script!(record, source_dir))
+          when 'Cell'   then logs.concat(process_cell!(record, plugin_ids))
+          end
+        end
+        logs
+      end
+
+      # Defaults missing `mast_index` on cell references. tes3conv requires
+      # the field on every reference; the convention is `0` for plugin-local
+      # records and N>0 for master records (1 = first listed master, etc.).
+      # We auto-fill 0 when the referenced id is defined in *this* plugin —
+      # the common case for new content — and emit a clear error otherwise
+      # so the user doesn't see tes3conv's cryptic "missing field" message.
+      def self.process_cell!(record, plugin_ids)
+        cell_label = describe_cell(record)
+        logs = []
+        Array(record['references']).each_with_index do |ref, i|
+          next if ref.key?('mast_index')
+
+          ref_id = ref['id'].to_s
+          if plugin_ids.include?(ref_id.downcase)
+            ref['mast_index'] = 0
+            logs << "#{cell_label}: ref[#{i}] #{ref_id.inspect} — defaulted mast_index to 0 (plugin-local)"
+          else
+            raise ValidationError, Esp.t('errors.preflight.master_ref_needs_mast_index',
+                                         cell: cell_label, id: ref_id)
+          end
+        end
+        logs
+      end
+
+      # Records this plugin defines (anything with a top-level `id`).
+      # Lowercased so the lookup is case-insensitive, matching how the
+      # engine and linter treat TES3 ids.
+      def self.collect_plugin_ids(records)
+        records.filter_map { |r| r['id']&.to_s&.downcase }.to_set
+      end
+
+      def self.describe_cell(record)
+        name = record['name'].to_s
+        grid = record.dig('data', 'grid')
+        return "cell #{name.inspect}" unless name.empty?
+        return "exterior cell #{grid.inspect}" if grid
+
+        'cell <unknown>'
+      end
+
+      def self.process_script!(record, source_dir)
+        sid = record['id'] || '<unknown>'
+        text, label = resolve_text(record, source_dir)
+        return ["#{sid}: empty text, skipping"] if text.empty?
+
+        validate_ascii!(text, label)
+        shorts, longs, floats, begin_name = parse_variables(text, label)
+        logs = []
+        if begin_name && begin_name.downcase != sid.downcase
+          logs << "#{sid}: WARNING — Begin name #{begin_name.inspect} does not match record id"
+        end
+        apply_script_data!(record, text, shorts, longs, floats)
+        logs
+      end
+
+      def self.apply_script_data!(record, text, shorts, longs, floats)
+        vars_blob, vars_length = Esp::Mw::ScriptBlob.variables(shorts + longs + floats)
+        record['header'] = {
+          'num_shorts' => shorts.size,
+          'num_longs' => longs.size,
+          'num_floats' => floats.size,
+          'bytecode_length' => 0,
+          'variables_length' => vars_length
+        }
+        record['variables'] = vars_blob
+        record['bytecode'] = Esp::Mw::ScriptBlob.empty_bytecode
+        record['text'] = text
+        record.delete('text_source')
+      end
+
+      def self.resolve_text(record, source_dir)
+        ts = record['text_source']
+        return [record['text'].to_s, "<inline text for #{record['id'] || '?'}>"] unless ts
+
+        path = File.expand_path(ts, source_dir)
+        unless File.file?(path)
+          raise ValidationError,
+                Esp.t('errors.preflight.text_source_missing', path: path)
+        end
+
+        [File.read(path), path]
+      end
+
+      def self.validate_ascii!(text, label)
+        text.each_char.with_index do |c, i|
+          next if c.ord < 128
+
+          prefix = text[0, i]
+          line = prefix.count("\n") + 1
+          col  = i - (prefix.rindex("\n") || -1)
+          hex  = format('%04X', c.ord)
+          raise ValidationError, Esp.t('errors.preflight.non_ascii',
+                                       label: label, char: c.inspect, hex: hex, line: line, col: col)
+        end
+      end
+
+      def self.parse_variables(text, label)
+        shorts = []
+        longs = []
+        floats = []
+        begin_name = nil
+        text.each_line do |line|
+          stripped = line.lstrip
+          next if stripped.start_with?(';')
+
+          if (m = BEGIN_RE.match(stripped))
+            begin_name = m[1]
+            next
+          end
+          next unless (m = VAR_DECL_RE.match(line))
+
+          kind = m[1].downcase
+          name = m[2]
+          if name.length > NAME_LIMIT
+            raise ValidationError, Esp.t('errors.preflight.var_too_long', label: label,
+                                                                          name: name.inspect,
+                                                                          length: name.length,
+                                                                          limit: NAME_LIMIT)
+          end
+          bucket = { 'short' => shorts, 'long' => longs, 'float' => floats }[kind]
+          bucket << name
+        end
+        [shorts, longs, floats, begin_name]
+      end
+    end
+  end
+end