esp-modkit 0.1.0

data/lib/esp/operations.rb

@@ -0,0 +1,285 @@
+require 'fileutils'
+require 'json'
+require 'time'
+
+module Esp
+  # Transport-agnostic service layer — the engine-agnostic shell half. One
+  # method per operation, each taking a string-keyed params hash and
+  # returning a plain Ruby hash. The HTTP API (`esp serve`) and the MCP
+  # server (`esp mcp serve`) are thin shells over these methods plus the
+  # active plugin's ops, so both frontends emit byte-identical payloads.
+  #
+  # What's here vs. in the plugin (Esp::Mw::Operations): the ops that have
+  # no Morrowind-specific concept — version/health/commands, the LLM
+  # provider seam, project/workspace/preferences state, recents, the
+  # git-diff review surface (the document under review is opaque to the
+  # shell). The plugin owns build/lint/unpack/scaffold/i18n/refs/dialogue
+  # and anything that decodes records.
+  #
+  # Errors that are the caller's fault (missing field, no index, validation)
+  # raise InputError; frontends map that to a 400 / tool-error. Lower
+  # layers raise their own typed errors which both frontends also treat as
+  # caller errors via the ERROR_CODES table below.
+  module Operations
+    class InputError < StandardError; end
+
+    # Stable error codes both frontends surface — one source of truth so MCP
+    # tool errors and HTTP 400s agree. The shell registers the classes it
+    # raises directly; plugin modules append their own via `register_error`
+    # at load time (no plugin error class can collide with a shell class —
+    # caller_errors derives from this hash and can't drift).
+    ERROR_CODES = {
+      InputError => 'invalid_input',
+      Esp::Vcs::GitError => 'git_error',
+      Esp::Providers::UnknownProvider => 'unknown_provider',
+      ArgumentError => 'invalid_argument'
+    }
+
+    class << self
+      # Register a typed exception → stable code so frontends can rescue it
+      # without knowing the plugin's class hierarchy. Idempotent (re-binding
+      # is a no-op in practice — the same class always maps to the same
+      # code) so plugins can re-load in tests.
+      def register_error(klass, code)
+        ERROR_CODES[klass] = code
+      end
+
+      # The classes both frontends rescue. Derived live from ERROR_CODES so
+      # `register_error` extends both at once.
+      def caller_errors
+        ERROR_CODES.keys
+      end
+
+      # Map a raised error to its stable code, falling back to 'error'. Order
+      # within ERROR_CODES doesn't matter because no shell/plugin error
+      # inherits from another listed class.
+      def error_code(exception)
+        ERROR_CODES.each { |klass, code| return code if exception.is_a?(klass) }
+        'error'
+      end
+
+      # Route an op symbol to whichever module owns it. Shell ops (this
+      # module) win first because some are game-independent and a project
+      # may not yet be open. Otherwise Esp::Plugins.active_for(input)
+      # picks the plugin matching the input's `game:` (if any), then the
+      # active project's game, then the default plugin — its Operations
+      # module answers. Frontends call this so they don't have to know
+      # which side of the seam each tool name lives on.
+      def dispatch(op, input = {})
+        return public_send(op, input) if respond_to?(op)
+
+        plugin = Esp::Plugins.active_for(input)
+        return plugin.operations.public_send(op, input) if plugin.operations.respond_to?(op)
+
+        raise NoMethodError, "unknown operation #{op} (no shell or #{plugin.id}-plugin handler)"
+      end
+
+      def version(_params = {})
+        { version: Esp::VERSION }
+      end
+
+      # Liveness probe for the GUI/clients: are we up, and which version.
+      def health(_params = {})
+        { status: 'ok', version: Esp::VERSION }
+      end
+
+      def commands(_params = {})
+        Esp::Introspection.command_tree
+      end
+
+      # The LLM providers a client can pick from (id, default model, whether a
+      # key is configured) plus the default. Backs the GUI's provider selector.
+      def providers(_params = {})
+        { providers: Esp::Providers.available, default: Esp::Providers.default_id }
+      end
+
+      # Installed Ollama models, for the model-input autocomplete in ESPresso
+      # (step 22 slice 3). Returns [] on any failure — Ollama down, network
+      # blip, etc. — so the UI degrades to free-text entry.
+      def ollama_models(_params = {})
+        { models: Esp::Providers::Ollama.list_models }
+      end
+
+      # Set the active project (step 23). Validates the path is a directory;
+      # path-not-found and path-not-a-dir are caller errors. Subsequent
+      # vcs_root lookups default to this root unless the request passes an
+      # explicit `root:` (which still wins — diff/approve/reject keep that
+      # affordance).
+      #
+      # Step 22.5 slice 2: reads the project marker's `game:` to pick the
+      # plugin that owns this project's ops. Missing marker / missing field
+      # falls back to the default plugin (`mw`) so pre-rename projects open
+      # transparently. An unknown game id is a caller error — surfaces when
+      # someone opens an Esp::Ob project on a build that only loads Mw.
+      def open_project(params)
+        path = params['root']
+        raise InputError, Esp.t('errors.operations.missing_field', field: 'root') if blank?(path)
+
+        resolved = File.expand_path(path)
+        unless File.directory?(resolved)
+          raise InputError, Esp.t('errors.operations.not_a_directory', path: resolved)
+        end
+
+        game = project_game(resolved)
+        unless Esp::Plugins.known?(game)
+          raise InputError, Esp.t('errors.plugins.unknown_game',
+                                  game: game, known: Esp::Plugins.ids.join(', '))
+        end
+
+        Esp::ActiveProject.set(resolved, game: game)
+        Esp::Recents.add(resolved)
+        { root: resolved, game: game }
+      end
+
+      # The currently-open project's root + game (or both nil if no project
+      # is open). Read-only counterpart to open_project for the GUI to query
+      # on boot — the GUI uses `game` to label the workspace.
+      def active_project(_params = {})
+        { root: Esp::ActiveProject.root, game: Esp::ActiveProject.game }
+      end
+
+      # The user's recently-opened projects, newest-first. Persisted by the
+      # backend at ESP_DATA_DIR/recents.json (slice 3 of step 23). Landing
+      # page renders this.
+      def projects_recent(_params = {})
+        { projects: Esp::Recents.list }
+      end
+
+      # Read-only snapshot of persisted preferences merged over defaults.
+      # Backs the ESPresso Settings panel (step 23 slice 4).
+      def preferences(_params = {})
+        Esp::Preferences.read
+      end
+
+      # Update preferences with a whitelisted partial. Returns the resolved
+      # post-merge state so the GUI can settle without a separate read.
+      def preferences_update(params)
+        Esp::Preferences.update(params)
+      end
+
+      # Scaffold a brand-new project (step 23 slice 5). One call covers:
+      #   1. Create <mods-home>/<project>/.
+      #   2. git init.
+      #   3. Write .esp/project.json marker (with `game:`).
+      #   4. Scaffold the first mod via the active plugin's Scaffolder.
+      #   5. Mark the project active and add it to recents.
+      # Returns the project root + the scaffolded mod's source path so the
+      # GUI can show the first mod in the diff panel without re-fetching.
+      #
+      # `game` defaults to the default plugin (mw today). When ESPresso grows
+      # a game picker, it'll pass the chosen id; the picker validates against
+      # Esp::Plugins.ids. Scaffolder still comes from Esp::Mw::* because that
+      # is the only plugin loaded today — future plugins will register their
+      # own Scaffolder and this op will look it up on the Esp::Plugins entry.
+      def projects_new(params)
+        project = params['project'].to_s.strip
+        first_mod = params['mod'].to_s.strip
+        game = (params['game'] || Esp::Plugins.default_id).to_s
+        raise InputError, Esp.t('errors.operations.missing_field', field: 'project') if project.empty?
+        raise InputError, Esp.t('errors.operations.missing_field', field: 'mod')     if first_mod.empty?
+        unless Esp::Plugins.known?(game)
+          raise InputError, Esp.t('errors.plugins.unknown_game',
+                                  game: game, known: Esp::Plugins.ids.join(', '))
+        end
+        unless project.match?(Esp::Mw::Scaffolder::MOD_NAME_RE)
+          raise InputError, Esp.t('errors.scaffolder.bad_name', mod: project.inspect)
+        end
+
+        root = File.join(Esp::Preferences.read['mods_home'], project)
+        raise InputError, Esp.t('errors.operations.project_exists', path: root) if File.exist?(root)
+
+        FileUtils.mkdir_p(root)
+        Esp::Vcs.run_git_init(root)
+        Esp::ProjectMarker.write(root, name: project, game: game)
+        result = Esp::Mw::Scaffolder.create(
+          first_mod,
+          format: params['format'] || Esp::Mw::Scaffolder::DEFAULT_FORMAT,
+          author: params['author'],
+          description: params['description'],
+          root: root
+        )
+        Esp::ActiveProject.set(root, game: game)
+        Esp::Recents.add(root)
+        { root: root, game: game, mod: result.mod, source: result.source.sub("#{root}/", '') }
+      end
+
+      # The review surface (step 20): working-tree changes under the project's
+      # mods/ (or `scope`), each with its unified diff. `root` overrides the
+      # git working tree (defaults to the active project, then the toolchain
+      # repo). The document under review is opaque to the shell, which is
+      # why diff/approve/reject live here rather than in the plugin.
+      def diff(params = {})
+        root = vcs_root(params)
+        scope = params['scope'] || 'mods'
+        changes = Esp::Vcs.changes(root: root, scope: scope).map do |change|
+          { path: change.path, status: change.status, staged: change.staged,
+            diff: Esp::Vcs.file_diff(root: root, path: change.path) }
+        end
+        { root: root, scope: scope, changes: changes }
+      end
+
+      # Approve edits: stage the given paths (`git add`). The change stays in
+      # the working tree to build from; the human commits when ready.
+      def approve(params)
+        paths = require_paths(params)
+        Esp::Vcs.stage(root: vcs_root(params), paths: paths)
+        { staged: paths }
+      end
+
+      # Reject edits: discard the given paths — restore tracked files to HEAD,
+      # delete agent-created untracked files. Destructive; the GUI confirms.
+      def reject(params)
+        root = vcs_root(params)
+        paths = require_paths(params)
+        paths.each { |path| Esp::Vcs.discard(root: root, path: path) }
+        { discarded: paths }
+      end
+
+      # Relative-to-project-root path. Strips the active project root (or
+      # the explicit `root:` override) so payloads carry "dist/MyMod.esp"
+      # rather than "/Users/me/projects/MyMod/dist/MyMod.esp". Falls back to
+      # Esp::ROOT when no project is active, preserving pre-slice-1 output.
+      # Public so plugin ops can reuse it without duplicating the prefix.
+      def relative(path, root: nil)
+        prefix = root || Esp::ActiveProject.resolve({})
+        path.sub("#{prefix}/", '')
+      end
+
+      private
+
+      def blank?(value)
+        value.nil? || value.to_s.empty?
+      end
+
+      # A non-empty array of non-empty string paths, or a caller error.
+      def require_paths(params)
+        paths = params['paths']
+        valid = paths.is_a?(Array) && !paths.empty? && paths.all? { |p| p.is_a?(String) && !p.empty? }
+        raise InputError, Esp.t('errors.operations.paths_required') unless valid
+
+        paths
+      end
+
+      # Read the project marker (`.esp/project.json`, with legacy
+      # `.espresso/project.json` accepted as one-release back-compat), return
+      # its `game:`. Missing file / missing field / malformed JSON all
+      # collapse to the default plugin id so pre-22.5 projects still open
+      # (every one was Morrowind).
+      def project_game(root)
+        marker = Esp::ProjectMarker.read(root)
+        return Esp::Plugins.default_id unless marker
+
+        marker['game'] || Esp::Plugins.default_id
+      end
+
+      # The git working tree to operate on. Precedence: explicit `root:` param
+      # (lets the diff panel target an arbitrary tree even with a project
+      # open) → active project (step 23) → the toolchain repo. Same
+      # precedence as every other root-needing op (step 23.5 slice 1) so
+      # the diff panel and the build target the same tree by default.
+      def vcs_root(params)
+        Esp::ActiveProject.resolve(params)
+      end
+    end
+  end
+end

data/lib/esp/plugins.rb

@@ -0,0 +1,75 @@
+module Esp
+  # The game-plugin registry. Each plugin (Esp::Mw today; future Esp::Ob,
+  # Esp::Sr) registers itself here at load time with a short `id` (the value
+  # that lands in a project's `.espresso/project.json` `game:` field) and the
+  # modules the frontends need to reach into — its Operations façade today.
+  #
+  # The shell composes its routes/tools against this registry, so the only
+  # thing tying the shell to a specific game is the project the user opens.
+  # Add a plugin: drop `lib/esp/<id>/`, call `Esp::Plugins.register` from its
+  # entry file, and add it to the load manifest.
+  #
+  # Lookups are by id string; `default_id` names the plugin used when no
+  # project is open (today: the first registered, which is `mw` because the
+  # load manifest loads it first). Slice 2 wires Esp::Operations.dispatch
+  # through `Esp::Plugins.active_for(input)` so an op like `build` reaches
+  # the plugin matching the active project's `game:` field rather than
+  # always Esp::Mw::Operations.
+  module Plugins
+    Entry = Struct.new(:id, :label, :operations, keyword_init: true)
+
+    @mutex = Mutex.new
+
+    class << self
+      # The id → Entry map, lazily initialized and populated by plugins at
+      # load time. Mutable hash (like Esp::Providers.registry) because the
+      # plugin set isn't known until every require finishes.
+      def registry
+        @registry ||= {}
+      end
+
+      # A plugin announces itself. `operations` is its Esp::*::Operations
+      # module (the game half of the service layer); `label` is the
+      # human-friendly name shown in error messages. Idempotent — a re-load
+      # in tests just rebinds the same entry.
+      def register(id, label:, operations:)
+        @mutex.synchronize do
+          registry[id.to_s] = Entry.new(id: id.to_s, label: label, operations: operations)
+        end
+      end
+
+      # The plugin handling the current request. Order of precedence:
+      #   1. explicit `game:` in the input hash (lets the diff panel etc.
+      #      target a specific plugin even when a project is open),
+      #   2. the active project's game (Esp::ActiveProject.game),
+      #   3. the default plugin (the only one for now; the fallback for
+      #      ops invoked before any project is open — version, providers).
+      # Unknown id raises so frontends surface a clear error.
+      def active_for(input = {})
+        id = (input.is_a?(Hash) && input['game']) || Esp::ActiveProject.game || default_id
+        fetch(id)
+      end
+
+      def fetch(id)
+        registry.fetch(id.to_s) do
+          raise Esp::Operations::InputError,
+                Esp.t('errors.plugins.unknown_game', game: id, known: ids.join(', '))
+        end
+      end
+
+      def ids
+        registry.keys
+      end
+
+      def default_id
+        registry.keys.first
+      end
+
+      # True when `id` names a registered plugin. Cheap predicate for
+      # open_project to validate before storing on ActiveProject.
+      def known?(id)
+        registry.key?(id.to_s)
+      end
+    end
+  end
+end

data/lib/esp/preferences.rb

@@ -0,0 +1,63 @@
+require 'json'
+require 'fileutils'
+
+module Esp
+  # Per-user preferences persisted as JSON alongside the recents file at
+  # ESP_DATA_DIR/preferences.json. Today: just `mods_home` (the directory the
+  # Open Project picker starts in / New Project scaffolds into). More keys to
+  # come; the merge-with-defaults read keeps backward compatibility as the
+  # schema grows. Same single-writer / mutex story as Recents.
+  module Preferences
+    DEFAULTS = {
+      'mods_home' => File.expand_path('~/Documents/ESPresso')
+    }.freeze
+
+    @mutex = Mutex.new
+
+    class << self
+      def path
+        File.join(Esp::Recents.data_dir, 'preferences.json')
+      end
+
+      def read
+        @mutex.synchronize { read_unsafe }
+      end
+
+      # Whitelist-merge an update. Unknown keys are ignored; nil/empty values
+      # also fall through (so a UI accidentally clearing a field doesn't blow
+      # away the default). Returns the resolved (post-merge) state.
+      def update(updates)
+        @mutex.synchronize do
+          stored = read_unsafe
+          accepted = updates.to_h
+                            .slice(*DEFAULTS.keys)
+                            .reject { |_, v| v.nil? || v.to_s.empty? }
+          merged = stored.merge(accepted)
+          write_unsafe(merged)
+          merged
+        end
+      end
+
+      def clear!
+        @mutex.synchronize { write_unsafe({}) }
+      end
+
+      private
+
+      # Defaults merged underneath whatever's on disk, so new keys always
+      # have a value and a hand-edited file with a missing key stays usable.
+      def read_unsafe
+        on_disk = File.exist?(path) ? JSON.parse(File.read(path)) : {}
+        on_disk = {} unless on_disk.is_a?(Hash)
+        DEFAULTS.merge(on_disk)
+      rescue StandardError
+        DEFAULTS.dup
+      end
+
+      def write_unsafe(state)
+        FileUtils.mkdir_p(File.dirname(path))
+        File.write(path, "#{JSON.pretty_generate(state)}\n")
+      end
+    end
+  end
+end

data/lib/esp/project_marker.rb

@@ -0,0 +1,99 @@
+require 'fileutils'
+require 'json'
+require 'time'
+
+module Esp
+  # Reads, writes, and discovers the `.esp/project.json` marker that
+  # identifies a directory as an esp project. Used by:
+  #
+  # - `esp init` and `Esp::Operations.projects_new` to write the marker.
+  # - `Esp::Operations.open_project` to read the marker's `game:` field so
+  #   the plugin registry knows which Operations module owns this project.
+  # - The CLI cwd walk-up so `esp build` works from anywhere inside a
+  #   project tree without `--root`.
+  #
+  # Marker filename rename (step 23.5 slice 3): the canonical location is
+  # now `.esp/project.json`. Projects scaffolded by an earlier ESPresso
+  # release wrote `.espresso/project.json`; readers accept both, writers
+  # only emit the new name. The back-compat lookup goes away when the
+  # release that drops it ships (no auto-migration — we don't silently
+  # rewrite a user's project files).
+  module ProjectMarker
+    FILENAME          = 'project.json'.freeze
+    DIRECTORY         = '.esp'.freeze
+    LEGACY_DIRECTORY  = '.espresso'.freeze
+
+    # Cap the cwd walk-up depth to defend against symlink loops and
+    # pathological filesystem layouts. 32 levels is deeper than any sane
+    # project tree (and matches git's own MAX_DEPTH for similar reasons).
+    WALK_DEPTH_CAP = 32
+
+    SCHEMA_VERSION = 1
+
+    class << self
+      # The canonical write path for a project rooted at `root`.
+      def path_in(root)
+        File.join(root, DIRECTORY, FILENAME)
+      end
+
+      # The marker path under `root`, preferring the new `.esp/` location
+      # but accepting a legacy `.espresso/` marker. Returns nil if neither
+      # exists.
+      def find_in(root)
+        new_path = path_in(root)
+        return new_path if File.exist?(new_path)
+
+        legacy = File.join(root, LEGACY_DIRECTORY, FILENAME)
+        return legacy if File.exist?(legacy)
+
+        nil
+      end
+
+      # Read + parse the marker at `root`. Returns nil if no marker exists
+      # or the JSON is malformed — callers default to the registry's
+      # default plugin (every pre-22.5 project is Morrowind) rather than
+      # surface a sharp edge.
+      def read(root)
+        path = find_in(root)
+        return nil unless path
+
+        JSON.parse(File.read(path))
+      rescue JSON::ParserError
+        nil
+      end
+
+      # Write the canonical marker. Always emits the new `.esp/` location;
+      # never touches a legacy `.espresso/` marker the project might
+      # already carry. Returns the path written.
+      def write(root, name:, game:)
+        path = path_in(root)
+        FileUtils.mkdir_p(File.dirname(path))
+        payload = {
+          'name' => name,
+          'schema' => SCHEMA_VERSION,
+          'game' => game,
+          'created_at' => Time.now.utc.iso8601
+        }
+        File.write(path, "#{JSON.pretty_generate(payload)}\n")
+        path
+      end
+
+      # Walk up from `start_dir` looking for a project marker. Returns the
+      # project root (the directory *containing* the marker dir), not the
+      # marker path. Nil if no marker is found before the filesystem root.
+      # Bounded by WALK_DEPTH_CAP so a symlink loop can't hang us.
+      def find_walking_up(start_dir)
+        current = File.expand_path(start_dir)
+        WALK_DEPTH_CAP.times do
+          return current if find_in(current)
+
+          parent = File.dirname(current)
+          return nil if parent == current # reached filesystem root
+
+          current = parent
+        end
+        nil
+      end
+    end
+  end
+end

data/lib/esp/providers/anthropic.rb

@@ -0,0 +1,74 @@
+module Esp
+  module Providers
+    # The Anthropic Messages API implementation of the provider contract. It
+    # translates the neutral transcript to Messages-API shape, prompt-caches the
+    # stable tools+system preamble, and normalizes the response back. The client
+    # is injected for tests; the real one is built lazily so no key is needed
+    # until a live run.
+    class Anthropic
+      DEFAULT_MODEL = 'claude-sonnet-4-6'.freeze
+      MAX_TOKENS = 16_000
+      ENV_KEY = 'ANTHROPIC_API_KEY'.freeze
+
+      # "Configured" = the SDK has a key to authenticate with.
+      def self.configured?
+        !ENV.fetch(ENV_KEY, '').to_s.empty?
+      end
+
+      def initialize(client: nil, model: DEFAULT_MODEL, max_tokens: MAX_TOKENS)
+        @client = client
+        @model = model
+        @max_tokens = max_tokens
+      end
+
+      def complete(system:, tools:, messages:)
+        response = client.messages.create(
+          model: @model,
+          max_tokens: @max_tokens,
+          thinking: { type: 'adaptive' },
+          # tools render before system, so caching the system block caches the
+          # whole (stable) tools + system preamble.
+          system_: [{ type: 'text', text: system, cache_control: { type: 'ephemeral' } }],
+          # `tools` already arrives in the {name, description, input_schema}
+          # shape the Messages API wants.
+          tools: tools,
+          messages: messages.map { |message| native_message(message) }
+        )
+        blocks = response.content
+        text = blocks.select { |b| b.type == :text }.map(&:text).join("\n")
+        tool_calls = blocks.select { |b| b.type == :tool_use }
+                           .map { |b| { id: b.id, name: b.name.to_s, input: b.input || {} } }
+        Completion.new(text: text, tool_calls: tool_calls, raw: { role: 'assistant', content: blocks })
+      end
+
+      private
+
+      def native_message(msg)
+        case msg[:role]
+        when :user      then { role: 'user', content: msg[:text] }
+        # Replay the stored native message verbatim — preserves thinking-block
+        # signatures the API requires on later turns with tool use.
+        when :assistant then msg[:raw]
+        # All tool results for one assistant turn go in one user message.
+        when :tool      then { role: 'user', content: msg[:results].map { |r| tool_result_block(r) } }
+        end
+      end
+
+      def tool_result_block(result)
+        { type: 'tool_result', tool_use_id: result[:id],
+          content: result[:content], is_error: result[:is_error] }
+      end
+
+      def client
+        @client ||= build_default_client
+      end
+
+      def build_default_client
+        require 'anthropic'
+        ::Anthropic::Client.new
+      end
+    end
+
+    register('anthropic', Anthropic, default_model: Anthropic::DEFAULT_MODEL, env_key: Anthropic::ENV_KEY)
+  end
+end