esp-modkit 0.1.0

data/lib/esp/mw/dialogue_dsl.rb

@@ -0,0 +1,209 @@
+module Esp
+  module Mw
+    # Block-style DSL for emitting Dialogue (DIAL) and DialogueInfo (INFO)
+    # records without the bookkeeping. Used inside Ruby mod sources via the
+    # loader-exposed `dialogue { ... }` helper.
+    #
+    # The contract: a `dialogue` block returns a flat Array of records
+    # that the author splats into their mod's records array. The DSL
+    # handles:
+    #
+    # - One DIAL record per `topic`, with `dialogue_type` carried through.
+    # - INFO records under each topic, chained via prev_id/next_id in
+    #   author order — Morrowind evaluates filters top-down, so author
+    #   order is filter precedence.
+    # - Speaker scoping via `speaker "Name" do ... end`. Nested blocks
+    #   inherit; an explicit `speaker:` on an info wins.
+    # - i18n: a `t("key")` helper is available inside the block when the
+    #   loader passes an Esp::Mw::I18n instance.
+    #
+    # Example:
+    #
+    #   dialogue do
+    #     speaker "Hrisskar Flat-Foot" do
+    #       topic "Flat-Foot" do
+    #         info t("hrisskar.flat_foot.intro")
+    #         info t("hrisskar.flat_foot.legion"), pc_faction: "Imperial Legion"
+    #       end
+    #     end
+    #
+    #     topic "AFSN_Tracker", type: :journal do
+    #       info "Stage 10 text", journal_index: 10
+    #       info "Stage 20 text", journal_index: 20
+    #     end
+    #   end
+    #
+    # Supported info kwargs:
+    #   speaker:           speaker_id filter (overrides surrounding scope)
+    #   race:              speaker_race filter
+    #   class:             speaker_class filter (note the keyword clash —
+    #                      use the string key or the `class_:` alias)
+    #   faction:           speaker_faction filter
+    #   cell:              speaker_cell filter
+    #   sex:               :any | :female | :male
+    #   pc_faction:        player_faction filter
+    #   pc_rank:           player_rank filter
+    #   speaker_rank:      NPC rank filter
+    #   disposition:       minimum disposition
+    #   sound:             sound_path
+    #   result_script:     inline MWScript text to run on activation
+    #   result_script_source: path to .mwscript file (resolved relative to
+    #                         the mod source dir at preflight time)
+    #   journal_index:     for Journal-type topics — maps to data.disposition
+    class DialogueDsl
+      VALID_TYPES = %i[topic journal persuasion greeting voice].freeze
+      VALID_SEX   = %i[any female male].freeze
+
+      def self.build(i18n: nil, &block)
+        raise ArgumentError, Esp.t('errors.dialogue.needs_block') unless block
+
+        dsl = new(i18n: i18n)
+        dsl.instance_eval(&block)
+        dsl.records
+      end
+
+      # Data-driven equivalent of `build`, for callers that can't pass a Ruby
+      # block (MCP/HTTP). Spec is JSON-shaped:
+      #   { "topics" => [ { "name"=>, "type"=>, "speaker"=>,
+      #                     "infos"=>[ { "text"=>, <filter keys>... } ] } ] }
+      # Filter keys mirror the block DSL's info kwargs. `text` carries literal
+      # strings or `@t:` sentinels (resolved at build), so there's no t()
+      # helper and no i18n instance here — unlike the block form.
+      def self.from_spec(spec)
+        topics = spec.is_a?(Hash) ? spec['topics'] : spec
+        raise ArgumentError, Esp.t('errors.dialogue.needs_topics') unless topics.is_a?(Array)
+
+        dsl = new
+        topics.each { |t| dsl.send(:apply_topic_spec, t) }
+        dsl.records
+      end
+
+      attr_reader :records
+
+      def initialize(i18n: nil)
+        @records = []
+        @speaker_stack = []
+        @current_topic = nil
+        return unless i18n
+
+        define_singleton_method(:t) { |key| i18n.t(key) }
+      end
+
+      def speaker(name, &block)
+        raise ArgumentError, Esp.t('errors.dialogue.speaker_needs_block') unless block
+
+        @speaker_stack.push(name)
+        instance_eval(&block)
+        @speaker_stack.pop
+      end
+
+      def topic(name, type: :topic, &block)
+        unless VALID_TYPES.include?(type)
+          raise ArgumentError, Esp.t('errors.dialogue.bad_topic_type', types: VALID_TYPES)
+        end
+        raise ArgumentError, Esp.t('errors.dialogue.topic_needs_block') unless block
+        raise Esp.t('errors.dialogue.nested_topics') if @current_topic
+
+        @records << { 'type' => 'Dialogue', 'flags' => '', 'id' => name,
+                      'dialogue_type' => normalize_type(type) }
+        @current_topic = { name: name, type: type, infos: [] }
+        instance_eval(&block)
+        flush_topic
+      end
+
+      def info(text, **filters)
+        raise Esp.t('errors.dialogue.info_outside_topic') unless @current_topic
+
+        @current_topic[:infos] << { text: text, filters: filters }
+      end
+
+      private
+
+      # Drive speaker/topic/info from one topic spec hash (string-keyed).
+      def apply_topic_spec(tspec)
+        name = tspec['name']
+        raise ArgumentError, Esp.t('errors.dialogue.topic_needs_name') if name.nil? || name.to_s.empty?
+
+        type = (tspec['type'] || 'topic').to_sym
+        infos = tspec['infos'] || []
+        body = proc { infos.each { |i| info(i['text'].to_s, **info_filters(i)) } }
+        speaker_name = tspec['speaker']
+        if speaker_name
+          speaker(speaker_name) { topic(name, type: type, &body) }
+        else
+          topic(name, type: type, &body)
+        end
+      end
+
+      # Every key except text becomes a symbol-keyed filter the DSL understands.
+      def info_filters(ispec)
+        ispec.reject { |k, _| k.to_s == 'text' }.transform_keys(&:to_sym)
+      end
+
+      def normalize_type(type)
+        type.to_s.capitalize
+      end
+
+      def flush_topic
+        topic = @current_topic
+        topic[:infos].each_with_index do |spec, idx|
+          @records << build_info(topic, spec, idx, topic[:infos].size)
+        end
+        @current_topic = nil
+      end
+
+      # Mostly a wide hash literal of optional filter defaults. Readability
+      # is in seeing the record shape; per-field extraction would scatter it.
+      def build_info(topic, spec, idx, total)
+        filters = spec[:filters]
+        {
+          'type' => 'DialogueInfo',
+          'flags' => '',
+          'id' => "#{topic[:name]}_#{idx}",
+          'prev_id' => idx.positive? ? "#{topic[:name]}_#{idx - 1}" : '',
+          'next_id' => idx < total - 1 ? "#{topic[:name]}_#{idx + 1}" : '',
+          'data' => info_data(topic, filters),
+          'speaker_id' => filters[:speaker] || @speaker_stack.last || '',
+          'speaker_race' => filters[:race] || '',
+          'speaker_class' => filters[:class] || filters[:class_] || '',
+          'speaker_faction' => filters[:faction] || '',
+          'speaker_cell' => filters[:cell] || '',
+          'player_faction' => filters[:pc_faction] || '',
+          'sound_path' => filters[:sound] || '',
+          'text' => spec[:text].to_s,
+          'filters' => [],
+          'script_text' => resolve_result_script(filters)
+        }
+      end
+
+      def info_data(topic, filters)
+        {
+          'dialogue_type' => normalize_type(topic[:type]),
+          'disposition' => filters[:journal_index] || filters[:disposition] || 0,
+          'speaker_rank' => filters[:speaker_rank] || -1,
+          'speaker_sex' => normalize_sex(filters[:sex]),
+          'player_rank' => filters[:pc_rank] || -1
+        }
+      end
+
+      def normalize_sex(value)
+        return 'Any' if value.nil?
+
+        sym = value.to_s.downcase.to_sym
+        unless VALID_SEX.include?(sym)
+          raise ArgumentError,
+                Esp.t('errors.dialogue.bad_sex', values: VALID_SEX)
+        end
+
+        sym.to_s.capitalize
+      end
+
+      def resolve_result_script(filters)
+        return filters[:result_script] if filters[:result_script]
+        return '' unless filters[:result_script_source]
+
+        raise NotImplementedError, Esp.t('errors.dialogue.result_script_source')
+      end
+    end
+  end
+end

data/lib/esp/mw/i18n.rb

@@ -0,0 +1,113 @@
+require 'yaml'
+
+module Esp
+  module Mw
+    # Locale-aware string lookup. Two interfaces:
+    #
+    # - `t(key)` returns the resolved string (with default-locale fallback)
+    #   and tracks misses. Used directly from the Ruby DSL.
+    # - `resolve!(value)` walks any data structure and replaces
+    #   `"@t:<key>"` sentinel strings via `t`. Used post-load for JSON or
+    #   subprocess-loader output (Python/JS/TS) where in-process helpers
+    #   can't reach.
+    #
+    # Catalogues are nested-hash YAML files at
+    # `mods/<Mod>/i18n/<locale>.yaml`. Lookup is dot-pathed:
+    # `t("activator.stump")` reads `{activator: {stump: "..."}}`.
+    class I18n
+      DEFAULT_LOCALE  = 'en'.freeze
+      SENTINEL_PREFIX = '@t:'.freeze
+
+      Miss = Struct.new(:key, :locale, keyword_init: true)
+
+      attr_reader :locale, :default_locale
+
+      def initialize(catalogues, locale: DEFAULT_LOCALE, default_locale: DEFAULT_LOCALE)
+        @catalogues = catalogues
+        @locale = locale
+        @default_locale = default_locale
+        @misses = []
+      end
+
+      # Returns the value at `key` in the active locale, falling back to
+      # the default locale, then to the literal key. Records misses for
+      # later reporting.
+      def t(key)
+        value = lookup(@locale, key)
+        return value if value
+
+        @misses << Miss.new(key: key, locale: @locale)
+        lookup(@default_locale, key) || key
+      end
+
+      # Recursively replaces `"@t:<key>"` strings in any structure.
+      # Mutates Hash values and Array elements in place; returns the
+      # result for convenience.
+      def resolve!(value)
+        case value
+        when String
+          value.start_with?(SENTINEL_PREFIX) ? t(value.delete_prefix(SENTINEL_PREFIX)) : value
+        when Array
+          value.map! { |v| resolve!(v) }
+          value
+        when Hash
+          value.each { |k, v| value[k] = resolve!(v) }
+          value
+        else
+          value
+        end
+      end
+
+      def misses
+        @misses.uniq
+      end
+
+      def self.load_catalogues(source_dir)
+        i18n_dir = File.join(source_dir, 'i18n')
+        return {} unless File.directory?(i18n_dir)
+
+        Dir.glob(File.join(i18n_dir, '*.yaml')).each_with_object({}) do |path, out|
+          locale = File.basename(path, '.yaml')
+          out[locale] = YAML.safe_load_file(path) || {}
+        end
+      end
+
+      # Compares each non-default locale catalogue against the default
+      # locale's key set, reporting keys missing from / orphaned in each.
+      # Returns { locale => { missing: [...], orphan: [...] } }; shared by
+      # the `i18n check` CLI command and the Operations surface.
+      def self.check(source_dir)
+        catalogues = load_catalogues(source_dir)
+        default_keys = flatten(catalogues[DEFAULT_LOCALE] || {}).keys
+        catalogues.each_with_object({}) do |(locale, cat), out|
+          next if locale == DEFAULT_LOCALE
+
+          keys = flatten(cat).keys
+          out[locale] = { missing: default_keys - keys, orphan: keys - default_keys }
+        end
+      end
+
+      # Flattens nested catalogue hash to dot-pathed keys:
+      # `{a: {b: "x"}}` -> `{"a.b" => "x"}`.
+      def self.flatten(hash, prefix = '')
+        hash.each_with_object({}) do |(k, v), out|
+          key = prefix.empty? ? k.to_s : "#{prefix}.#{k}"
+          if v.is_a?(Hash)
+            out.merge!(flatten(v, key))
+          else
+            out[key] = v
+          end
+        end
+      end
+
+      private
+
+      def lookup(locale, key)
+        cat = @catalogues[locale]
+        return nil unless cat
+
+        key.split('.').reduce(cat) { |h, k| h.is_a?(Hash) ? h[k] : nil }
+      end
+    end
+  end
+end

data/lib/esp/mw/linter.rb

@@ -0,0 +1,103 @@
+module Esp
+  module Mw
+    # Checks a mod's records for dangling references and missing-master
+    # coverage. Uses Esp::Mw::ReferenceIndex for vanilla lookups and the mod's
+    # own records for self-references.
+    #
+    # Severity model:
+    # - :error   — the ref points at nothing the mod or any indexed ESM defines.
+    # - :warning — the ref resolves in a vanilla ESM that isn't listed in
+    #              the mod's TES3 Header.masters. OpenMW will load the mod
+    #              but log warnings; the mod author probably forgot to add
+    #              the dependency.
+    class Linter
+      Issue = Struct.new(:severity, :record_id, :record_type, :field, :ref_id, :message, keyword_init: true)
+
+      # Record types that carry a `script` field pointing at a Script record.
+      SCRIPTED_TYPES = %w[
+        Activator Alchemy Apparatus Armor Book Clothing Container Creature
+        Door Ingredient Light Lockpick MiscItem Probe RepairItem Weapon
+      ].freeze
+
+      def initialize(records, index)
+        @records = records
+        @index = index
+        @mod_ids = build_mod_index
+        @masters = extract_masters_set
+      end
+
+      def issues
+        @issues ||= collect_issues
+      end
+
+      private
+
+      def collect_issues
+        out = []
+        @records.each do |record|
+          case record['type']
+          when 'Npc'
+            out.concat(check_npc(record))
+          when *SCRIPTED_TYPES
+            issue = check_ref(record, 'script', 'Script')
+            out << issue if issue
+          end
+        end
+        out
+      end
+
+      def check_npc(record)
+        [
+          check_ref(record, 'script',  'Script'),
+          check_ref(record, 'race',    'Race'),
+          check_ref(record, 'class',   'Class'),
+          check_ref(record, 'faction', 'Faction')
+        ].compact
+      end
+
+      def check_ref(record, field, type)
+        id = record[field]
+        return nil if id.nil? || (id.is_a?(String) && id.empty?)
+        return nil if @mod_ids[[id.downcase, type]]
+
+        hits = @index.find(query: id, type: type, limit: 1)
+        return missing_ref_issue(record, field, type, id) if hits.empty?
+
+        # source_esm is the basename minus .json — already includes .esm
+        # (e.g. File.basename('Morrowind.esm.json', '.json') => 'Morrowind.esm').
+        master = hits.first['source_esm']
+        return missing_master_issue(record, field, type, id, master) unless @masters.include?(master.downcase)
+
+        nil
+      end
+
+      def missing_ref_issue(record, field, type, id)
+        Issue.new(severity: :error, record_id: record['id'], record_type: record['type'],
+                  field: field, ref_id: id, message: "unknown #{type}")
+      end
+
+      def missing_master_issue(record, field, type, id, master)
+        Issue.new(severity: :warning, record_id: record['id'], record_type: record['type'],
+                  field: field, ref_id: id, message: "#{type} defined in #{master}; not in masters list")
+      end
+
+      def build_mod_index
+        @records.each_with_object({}) do |r, h|
+          next unless r['id'] && r['type']
+
+          h[[r['id'].downcase, r['type']]] = true
+        end
+      end
+
+      def extract_masters_set
+        header = @records.find { |r| r['type'] == 'Header' }
+        return Set.new unless header
+
+        (header['masters'] || []).each_with_object(Set.new) do |entry, set|
+          name = entry.is_a?(Array) ? entry[0] : entry
+          set << name.downcase if name
+        end
+      end
+    end
+  end
+end

data/lib/esp/mw/loader.rb

@@ -0,0 +1,130 @@
+require 'json'
+require 'open3'
+
+module Esp
+  module Mw
+    # Loads a mod's source records from one of the supported formats.
+    #
+    # The contract: every loader returns an Array of record hashes shaped
+    # for tes3conv. Keys are normalised to strings so downstream code
+    # (preflight, builder) doesn't have to care which format the source
+    # was authored in.
+    #
+    # Supported source files (per mod folder, exactly one):
+    #   mods/<Mod>/<Mod>.json   — straight JSON
+    #   mods/<Mod>/<Mod>.rb     — Ruby file; last expression is the Array
+    #   mods/<Mod>/<Mod>.py     — Python script; prints JSON Array to stdout
+    #   mods/<Mod>/<Mod>.js     — Node script; same contract
+    #   mods/<Mod>/<Mod>.mjs    — Node ES module; same contract
+    #   mods/<Mod>/<Mod>.ts     — Deno TypeScript; same contract
+    #
+    # For subprocess loaders (py/js/mjs/ts) the interpreter runs with cwd
+    # set to the mod's source directory, so relative file reads from the
+    # script just work. The script's own path is passed as the last arg.
+    module Loader
+      class LoadError < StandardError; end
+
+      class << self
+        # Extension -> command vector. Mutable so tests / local config
+        # can poke at it without freeze/unfreeze dances.
+        attr_accessor :interpreters
+
+        def supported_exts
+          %w[.rb .json] + interpreters.keys
+        end
+
+        def resolve(mod, root: Esp::ROOT)
+          candidates = supported_exts
+                       .map { |ext| File.join(root, 'mods', mod, "#{mod}#{ext}") }
+                       .select { |p| File.exist?(p) }
+          if candidates.empty?
+            wanted = supported_exts.map { |e| "#{mod}#{e}" }.join(', ')
+            raise LoadError, Esp.t('errors.loader.no_source', mod: mod.inspect, exts: wanted)
+          end
+          if candidates.size > 1
+            names = candidates.map { |c| File.basename(c) }.join(', ')
+            raise LoadError, Esp.t('errors.loader.multiple_sources', mod: mod.inspect, names: names)
+          end
+
+          candidates.first
+        end
+
+        def load(path, i18n: nil)
+          raise LoadError, Esp.t('errors.loader.not_found', path: path) unless File.exist?(path)
+
+          records = dispatch(path, i18n)
+          unless records.is_a?(Array)
+            raise LoadError, Esp.t('errors.loader.not_array', path: path, klass: records.class)
+          end
+
+          records.map { |r| stringify_keys(r) }
+        end
+
+        private
+
+        def dispatch(path, i18n)
+          ext = File.extname(path)
+          case ext
+          when '.json'                then load_json(path)
+          when '.rb'                  then load_rb(path, i18n)
+          when *interpreters.keys     then load_via_interpreter(path, ext)
+          else raise LoadError, Esp.t('errors.loader.unsupported_ext', ext: ext, path: path)
+          end
+        end
+
+        def load_json(path)
+          JSON.parse(File.read(path))
+        rescue JSON::ParserError => e
+          raise LoadError, Esp.t('errors.loader.invalid_json', file: File.basename(path), message: e.message)
+        end
+
+        def load_rb(path, i18n)
+          anon = Module.new
+          anon.define_singleton_method(:t) { |key| i18n.t(key) } if i18n
+          anon.define_singleton_method(:dialogue) do |&block|
+            Esp::Mw::DialogueDsl.build(i18n: i18n, &block)
+          end
+          anon.module_eval(File.read(path), path)
+        end
+
+        def load_via_interpreter(path, ext)
+          cmd = interpreters.fetch(ext) + [path]
+          stdout, stderr, status = Open3.capture3(*cmd, chdir: File.dirname(path))
+          unless status.success?
+            raise LoadError, Esp.t('errors.loader.subprocess_failed',
+                                   file: File.basename(path), code: status.exitstatus, stderr: stderr.strip)
+          end
+
+          begin
+            JSON.parse(stdout)
+          rescue JSON::ParserError => e
+            raise LoadError, Esp.t('errors.loader.subprocess_bad_json',
+                                   file: File.basename(path), message: e.message)
+          end
+        rescue Errno::ENOENT
+          interpreter = interpreters.fetch(ext).first
+          raise LoadError, Esp.t('errors.loader.interpreter_missing',
+                                 interpreter: interpreter.inspect, file: File.basename(path))
+        end
+
+        def stringify_keys(obj)
+          case obj
+          when Hash
+            obj.each_with_object({}) { |(k, v), h| h[k.to_s] = stringify_keys(v) }
+          when Array
+            obj.map { |v| stringify_keys(v) }
+          else
+            obj
+          end
+        end
+      end
+
+      self.interpreters = {
+        '.py' => %w[python3],
+        '.js' => %w[node],
+        '.mjs' => %w[node],
+        '.ts' => %w[deno run --quiet]
+      }
+    end
+  end
+end

data/lib/esp/mw/openmw_config.rb

@@ -0,0 +1,138 @@
+require 'fileutils'
+require 'rbconfig'
+
+module Esp
+  module Mw
+    # Reads and edits OpenMW's openmw.cfg. Knows the per-OS location of the
+    # *user* config (the one OpenMW's launcher edits) and can parse the
+    # data=/content= lines to enumerate installed plugins.
+    #
+    # v1 targets the single user config; OPENMW_CONFIG (or an explicit path)
+    # overrides it. The full global/local/user hierarchy and ?token? data
+    # paths are not merged/expanded yet — see roadmap/17.
+    class OpenmwConfig
+      class << self
+        def default_path
+          File.join(default_dir, 'openmw.cfg')
+        end
+
+        def default_dir
+          env = ENV['OPENMW_CONFIG'].to_s
+          return env.split(File::PATH_SEPARATOR).first unless env.empty?
+
+          platform_config_dir
+        end
+
+        def host_os
+          case RbConfig::CONFIG['host_os']
+          when /mswin|mingw|cygwin/ then :windows
+          when /darwin/             then :macos
+          else                           :linux
+          end
+        end
+
+        private
+
+        def platform_config_dir
+          case host_os
+          when :windows
+            File.join(ENV.fetch('USERPROFILE', Dir.home), 'Documents', 'My Games', 'OpenMW')
+          when :macos
+            File.expand_path('~/Library/Preferences/openmw')
+          else
+            File.join(ENV['XDG_CONFIG_HOME'] || File.expand_path('~/.config'), 'openmw')
+          end
+        end
+      end
+
+      # Computed at load from the current OS/env. Callers may pass an explicit
+      # path to OpenmwConfig.new instead.
+      DEFAULT_PATH = default_path
+
+      attr_reader :path
+
+      def initialize(path = DEFAULT_PATH)
+        @path = path
+      end
+
+      def exist?
+        File.exist?(@path)
+      end
+
+      def include?(line)
+        exist? && File.readlines(@path, chomp: true).include?(line)
+      end
+
+      def append(line)
+        return false if include?(line)
+
+        File.open(@path, 'a') { |f| f.puts(line) }
+        true
+      end
+
+      def backup_once_per_day(now: Time.now)
+        backup = "#{@path}.bak.#{now.strftime('%Y%m%d')}"
+        FileUtils.cp(@path, backup) unless File.exist?(backup)
+        backup
+      end
+
+      # Absolute data= directories, in file order (relative paths resolve
+      # against the config's directory). Token paths (?userdata? etc.) are
+      # passed through unexpanded and simply won't glob.
+      def data_dirs
+        lines.filter_map do |line|
+          value = match_value(line, 'data')
+          value && resolve_dir(value)
+        end
+      end
+
+      # content= plugin filenames, in file order — this is the load order.
+      def content_entries
+        lines.filter_map { |line| match_value(line, 'content') }
+      end
+
+      # Every plugin file found across the data dirs, annotated with whether
+      # it's active (has a content= line) and its load-order index.
+      def installed_plugins
+        order = content_entries.each_with_index.to_h
+        data_dirs.flat_map { |dir| plugins_in(dir, order) }
+      end
+
+      private
+
+      # Plugins in one data dir. A real install can have dirs we can't read
+      # (permissions, broken symlinks) — skip those rather than crash the
+      # whole listing.
+      def plugins_in(dir, order)
+        Dir.glob(File.join(dir, '*.{esm,esp,omwaddon}')).map do |file|
+          name = File.basename(file)
+          { name: name, path: file, dir: dir, active: order.key?(name), load_order: order[name] }
+        end
+      rescue SystemCallError
+        []
+      end
+
+      def lines
+        exist? ? File.readlines(@path, chomp: true) : []
+      end
+
+      # `key=value`, tolerant of spaces; returns the unquoted value or nil.
+      def match_value(line, key)
+        m = line.match(/\A#{key}\s*=\s*(.*)\z/)
+        return nil unless m
+
+        unquote(m[1].strip)
+      end
+
+      def unquote(value)
+        value.start_with?('"') && value.end_with?('"') ? value[1..-2] : value
+      end
+
+      def resolve_dir(dir)
+        return dir if dir.include?('?') || File.absolute_path?(dir)
+
+        File.expand_path(dir, File.dirname(@path))
+      end
+    end
+  end
+end