esp-modkit 0.1.0

data/lib/esp.rb

@@ -0,0 +1,85 @@
+module Esp
+  ROOT = File.expand_path('..', __dir__)
+end
+
+# Single load manifest for the toolchain. Components no longer require each
+# other; they're loaded here once, in dependency order (a file that
+# references another Esp constant at load time — e.g. Operations::ERROR_CODES
+# naming Loader/Tes3conv errors — must come after it). Add new files here.
+#
+# Layout (step 22.5): top-level `lib/esp/` is the engine-agnostic shell;
+# `lib/esp/mw/` is the Morrowind plugin. Future plugins (Oblivion, …) get
+# their own subdirectory and parallel load section below.
+
+require_relative 'esp/version'
+require_relative 'esp/ui'
+
+# Engine-agnostic core (shell). Order: leaf modules first, then anything
+# that names them in constants/registry at load time.
+require_relative 'esp/introspection'
+require_relative 'esp/docs_generator'
+require_relative 'esp/vcs'
+require_relative 'esp/active_project'
+require_relative 'esp/recents'
+require_relative 'esp/preferences'
+require_relative 'esp/project_marker'
+
+# Game-plugin seam. Registry loaded before plugin modules self-register
+# (in the plugin section below) and before Operations.dispatch reads it.
+# Empty at this point; populated when each plugin's Operations file requires
+# back into it.
+require_relative 'esp/plugins'
+
+# LLM provider seam (agnostic — providers are language-model backends, not
+# game-specific). Registry loaded before the self-registering providers,
+# both before Operations/Agent which reference Esp::Providers.
+require_relative 'esp/providers'
+require_relative 'esp/providers/anthropic'
+require_relative 'esp/providers/openai'
+require_relative 'esp/providers/ollama'
+
+# Engine-agnostic Operations façade (shell ops: open_project, providers,
+# preferences, recents, diff/approve/reject, ollama_models, version/health).
+require_relative 'esp/operations'
+
+# Engine-agnostic agent loop. Composed before the frontends but after the
+# Operations façade it dispatches into.
+require_relative 'esp/agent'
+
+# —————————————————————————————————————————————————————————————————————————
+# Plugin: Morrowind (TES3). Loaded under Esp::Mw::*; depends on shell above.
+# —————————————————————————————————————————————————————————————————————————
+
+# Mw plugin core / leaf modules.
+require_relative 'esp/mw/script_blob'
+require_relative 'esp/mw/openmw_config'
+require_relative 'esp/mw/i18n'
+require_relative 'esp/mw/tes3conv'
+require_relative 'esp/mw/data_files'
+require_relative 'esp/mw/dialogue_dsl'
+require_relative 'esp/mw/reference_index'
+require_relative 'esp/mw/preflight'
+require_relative 'esp/mw/loader'
+
+# Mw plugin service layer.
+require_relative 'esp/mw/scaffolder'
+require_relative 'esp/mw/script_extractor'
+require_relative 'esp/mw/builder'
+require_relative 'esp/mw/linter'
+require_relative 'esp/mw/operations'
+require_relative 'esp/watcher' # uses Esp::Mw::Builder
+
+# Frontends — last, because they compose ROUTES/TOOLS from both shell ops
+# (Esp::Operations) and plugin ops (Esp::Mw::Operations).
+require_relative 'esp/http_server'
+require_relative 'esp/mcp_server'
+require_relative 'esp/mcp_installer'
+
+# CLI: the Support mixin and every subcommand before the root that mounts them.
+require_relative 'esp/cli/support'
+require_relative 'esp/cli/docs'
+require_relative 'esp/cli/refs'
+require_relative 'esp/cli/i18n'
+require_relative 'esp/cli/plugins'
+require_relative 'esp/cli/mcp'
+require_relative 'esp/cli'

data/locales/en.yml

@@ -0,0 +1,164 @@
+# Tool-UI strings for mw itself (not mod content — that's mods/<Mod>/i18n/).
+# Dot-pathed keys, %{named} interpolation. en is the default + fallback;
+# add locales/<lang>.yml to translate. See lib/mw/ui.rb.
+cli:
+  no_project_context: "warning: no project context (no --root, ESP_PROJECT_ROOT, or .esp/project.json found by walking up) — using toolchain repo at %{root}. Run `esp init` to make this directory a project."
+  init:
+    created: "initialised esp project at %{path} (game: %{game})"
+    next: "next: `esp new MyMod` to scaffold a mod, then `esp build MyMod`"
+    already_initialised: ".esp/project.json already present at %{path} — pass --force to overwrite"
+  setup:
+    diff_driver: "Configured git diff driver 'tes3' for .esp/.esm/.omwaddon"
+    hooks_path: "Configured core.hooksPath -> .githooks (pre-commit runs rubocop + tests)"
+  new:
+    created: "created: %{path}"
+    next: "next: esp build %{mod}"
+  unpack:
+    done: "unpack: %{plugin} -> %{output}"
+  build:
+    usage: "usage: esp build <MOD> | --all"
+    done: "build: %{mod} -> %{output}"
+  install:
+    # The build_first / no_cfg validation moved into Esp::Mw::Operations
+    # at step 23.5 slice 1; CLI install dispatches through the op and gets
+    # those messages from errors.operations.* instead. Kept here only:
+    added: "added: %{line}"
+    present: "already present: %{line}"
+    copied: "copied to: %{path}"
+    done: "Done. Launch OpenMW and verify load order in the launcher."
+  lint:
+    ok: "ok"
+    summary: "%{errors} error(s), %{warnings} warning(s)"
+  serve:
+    listening: "esp serve listening on http://localhost:%{port}"
+    routes: "routes: GET /version /commands /refs/find   POST /build /lint /scaffold /extract-scripts"
+  extract_scripts:
+    extracted: "extracted: scripts/%{id}.mwscript"
+    skipped: "skipped (already external): %{id}"
+    done: "done: %{extracted} extracted, %{skipped} skipped"
+  doctor:
+    header: "esp doctor — checking install prerequisites"
+    ruby_ok: "ruby %{version} (>= %{required} required)"
+    ruby_old: "ruby %{version} is below the required %{required} — upgrade Ruby"
+    esp: "esp-modkit %{version}"
+    tes3conv_found: "tes3conv: found at %{path}"
+    tes3conv_missing: "tes3conv: NOT found — install a release from https://github.com/Greatness7/tes3conv/releases, `cargo install --git https://github.com/Greatness7/tes3conv`, or via the esp Homebrew tap"
+    refs_present: "references index: present at %{path}"
+    refs_missing: "references index: not built — run `esp refs unpack && esp refs index` (lint/refs need it; build does not)"
+    ok: "all prerequisites satisfied"
+    problems: "%{count} blocking issue(s) above — esp build will not work until resolved"
+
+# Errors raised in the library layer (and the shared no_index message).
+errors:
+  no_index: "no index at %{db} — run `esp refs unpack && esp refs index` first"
+  reference_index:
+    no_sources: "no *.esm.json under %{dir} — run `esp refs unpack` first"
+  operations:
+    missing_field: "missing '%{field}' field"
+    missing_object: "missing '%{field}' object"
+    plugin_not_found: "plugin not found: %{plugin}"
+    build_first: "build first: %{esp} missing"
+    no_cfg: "openmw.cfg not found at %{path}"
+    record_needs_type: "record needs a 'type'"
+    record_needs_id: "non-Header records need an 'id' to upsert by"
+    json_only: "record_write supports only .json sources (%{file} is %{ext}); edit the source program directly"
+    paths_required: "'paths' must be a non-empty array of file paths"
+    not_a_directory: "not a directory: %{path}"
+    project_exists: "a project already exists at %{path}"
+    no_data_files: "Morrowind Data Files directory not found at %{path} (pass --copy-to PATH explicitly, or set $MORROWIND_DATA)"
+  providers:
+    unknown: "unknown provider: %{id}"
+  plugins:
+    unknown_game: "unknown game plugin: %{game} (known: %{known})"
+  loader:
+    no_source: "no source for mod %{mod} (expected one of: %{exts})"
+    multiple_sources: "multiple sources for mod %{mod}: %{names}"
+    not_found: "source not found: %{path}"
+    not_array: "%{path}: expected an Array of record hashes, got %{klass}"
+    unsupported_ext: "unsupported source extension: %{ext} (%{path})"
+    invalid_json: "%{file}: invalid JSON: %{message}"
+    subprocess_failed: "%{file} exited %{code}: %{stderr}"
+    subprocess_bad_json: "%{file} stdout was not valid JSON: %{message}"
+    interpreter_missing: "interpreter %{interpreter} not found on PATH (required for %{file})"
+  tes3conv:
+    not_found: "%{bin} not found on PATH (download a release from https://github.com/Greatness7/tes3conv/releases or `cargo install --git https://github.com/Greatness7/tes3conv`)"
+    failed: "tes3conv failed (no diagnostic on stderr)"
+    flags_hint: "hint: every record needs \"flags\": \"\" — tes3conv requires it even when empty"
+  scaffolder:
+    already_exists: "mod folder already exists: mods/%{mod} (pass --force to overwrite)"
+    bad_name: "mod name %{mod} must start with a letter/digit and contain only letters, digits, _ or -"
+    bad_format: "unknown format %{format} (one of: %{formats})"
+  preflight:
+    text_source_missing: "text_source path not found: %{path}"
+    non_ascii: "%{label}: non-ASCII character %{char} (U+%{hex}) at line %{line}, col %{col}"
+    var_too_long: "%{label}: variable name %{name} is %{length} chars; MWScript truncates around %{limit}-23, keep <= %{limit}"
+    master_ref_needs_mast_index: "%{cell}: reference %{id} is a master-record reference but missing `mast_index` (set 0 for plugin-local refs, or the master's index — 1 for the first listed master)"
+  script_extractor:
+    json_only: "extract-scripts only supports .json sources (got %{file})"
+    missing_id: "Script record missing id"
+    unsafe_id: "Script id %{id} contains characters unsafe for a filename"
+    no_text: "Script %{id} has no text to extract"
+  mcp_installer:
+    unknown_client: "unknown client: %{client} (known: %{clients})"
+    not_json_object: "%{path} is not a JSON object"
+    invalid_json: "%{path} contains invalid JSON: %{message}"
+  http:
+    invalid_body: "invalid JSON body: %{message}"
+  dialogue:
+    needs_block: "dialogue { ... } requires a block"
+    needs_topics: "dialogue spec needs a 'topics' array"
+    speaker_needs_block: "speaker requires a block"
+    bad_topic_type: "topic must be one of %{types}"
+    topic_needs_block: "topic requires a block"
+    nested_topics: "nested topics are not allowed"
+    info_outside_topic: "info must be inside a topic block"
+    topic_needs_name: "each topic needs a 'name'"
+    bad_sex: "sex must be one of %{values}"
+    result_script_source: "result_script_source is not supported yet; pass result_script with inline text"
+
+refs:
+  unpack:
+    done: "unpack: %{name}.esm -> %{output}"
+    skip: "skip: %{source} (%{reason})"
+  index:
+    indexing: "indexing %{dir}/*.esm.json -> %{db}"
+    indexed: "indexed %{count} records"
+  find:
+    usage: "usage: esp refs find QUERY | --type TYPE | --like PATTERN"
+    no_matches: "no matches"
+    total_one: "1 match"
+    total: "%{total} matches"
+    truncated: "showing %{shown} of %{total} — narrow with --type or raise --limit"
+
+i18n:
+  none: "no non-default-locale catalogues found"
+  locale: "%{locale}:"
+  missing: "  missing: %{key}"
+  orphan: "  orphan:  %{key}"
+  ok: "  ok"
+  audit:
+    clean: "locale catalogues clean"
+    undefined: "undefined keys (referenced by t() but not in en):"
+    unused: "unused keys (in en, never referenced):"
+    orphans: "%{locale}: orphan keys (not in en):"
+    missing: "%{locale}: %{count} missing translation(s) (fall back to en)"
+    item: "  %{key}"
+
+docs:
+  wrote: "wrote: %{path}"
+
+plugins:
+  list:
+    config: "openmw.cfg: %{path}"
+    missing: "openmw.cfg not found at %{path}"
+    none: "no plugins found in the configured data directories"
+    active: "%{order}  %{name}"
+    inactive: "--  %{name}"
+
+mcp:
+  serve:
+    listening: "esp mcp serve: speaking MCP over stdio (Ctrl-D / EOF to stop)"
+  install:
+    result: "%{action} server '%{name}' in %{label}"
+    config: "  config: %{path}"
+    restart: "  restart Claude Desktop to pick up the change"

data/locales/fr.yml

@@ -0,0 +1,10 @@
+# Partial French catalogue — proves the locale path end to end. Anything not
+# translated here falls back to en (see lib/esp/ui.rb). Translate more keys to
+# extend coverage; en.yml is the canonical key set.
+cli:
+  build:
+    done: "compilation : %{mod} -> %{output}"
+  lint:
+    ok: "aucun problème"
+errors:
+  no_index: "pas d'index à %{db} — lancez `esp refs unpack && esp refs index` d'abord"

metadata

@@ -0,0 +1,241 @@
+--- !ruby/object:Gem::Specification
+name: esp-modkit
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Corey Ellis
+bindir: exe
+cert_chain: []
+date: 2026-05-31 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: anthropic
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: base64
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.2'
+- !ruby/object:Gem::Dependency
+  name: listen
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.9'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.9'
+- !ruby/object:Gem::Dependency
+  name: openai
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.64'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.64'
+- !ruby/object:Gem::Dependency
+  name: sqlite3
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.1'
+- !ruby/object:Gem::Dependency
+  name: thor
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.3'
+- !ruby/object:Gem::Dependency
+  name: webrick
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.8'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.8'
+- !ruby/object:Gem::Dependency
+  name: zstd-ruby
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.5'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.5'
+description: A Ruby toolchain that compiles Morrowind plugins from source. Author
+  records in JSON, Ruby, Python, JavaScript, or TypeScript; esp builds them to an
+  .esp via tes3conv, manages scripts, translations, and dialogue, and lints against
+  vanilla game data. One pipeline drives the CLI, an HTTP API, an MCP server, and
+  an AI agent.
+executables:
+- esp
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- docs/architecture.md
+- docs/authoring-guide.md
+- docs/getting-started.md
+- docs/reference/api/active-project.md
+- docs/reference/api/agent.md
+- docs/reference/api/docs-generator.md
+- docs/reference/api/http-server.md
+- docs/reference/api/index.md
+- docs/reference/api/introspection.md
+- docs/reference/api/mcp-installer.md
+- docs/reference/api/mcp-server.md
+- docs/reference/api/mw-builder.md
+- docs/reference/api/mw-data-files.md
+- docs/reference/api/mw-dialogue-dsl.md
+- docs/reference/api/mw-i18n.md
+- docs/reference/api/mw-linter.md
+- docs/reference/api/mw-loader.md
+- docs/reference/api/mw-openmw-config.md
+- docs/reference/api/mw-operations.md
+- docs/reference/api/mw-preflight.md
+- docs/reference/api/mw-reference-index.md
+- docs/reference/api/mw-scaffolder.md
+- docs/reference/api/mw-script-blob.md
+- docs/reference/api/mw-script-extractor.md
+- docs/reference/api/operations.md
+- docs/reference/api/plugins.md
+- docs/reference/api/preferences.md
+- docs/reference/api/project-marker.md
+- docs/reference/api/providers.md
+- docs/reference/api/recents.md
+- docs/reference/api/ui.md
+- docs/reference/api/vcs.md
+- docs/reference/api/watcher.md
+- docs/reference/commands.md
+- docs/walkthrough.md
+- exe/esp
+- lib/esp.rb
+- lib/esp/active_project.rb
+- lib/esp/agent.rb
+- lib/esp/cli.rb
+- lib/esp/cli/docs.rb
+- lib/esp/cli/i18n.rb
+- lib/esp/cli/mcp.rb
+- lib/esp/cli/plugins.rb
+- lib/esp/cli/refs.rb
+- lib/esp/cli/support.rb
+- lib/esp/docs_generator.rb
+- lib/esp/http_server.rb
+- lib/esp/introspection.rb
+- lib/esp/mcp_installer.rb
+- lib/esp/mcp_server.rb
+- lib/esp/mw/builder.rb
+- lib/esp/mw/data_files.rb
+- lib/esp/mw/dialogue_dsl.rb
+- lib/esp/mw/i18n.rb
+- lib/esp/mw/linter.rb
+- lib/esp/mw/loader.rb
+- lib/esp/mw/openmw_config.rb
+- lib/esp/mw/operations.rb
+- lib/esp/mw/preflight.rb
+- lib/esp/mw/reference_index.rb
+- lib/esp/mw/scaffolder.rb
+- lib/esp/mw/script_blob.rb
+- lib/esp/mw/script_extractor.rb
+- lib/esp/mw/tes3conv.rb
+- lib/esp/operations.rb
+- lib/esp/plugins.rb
+- lib/esp/preferences.rb
+- lib/esp/project_marker.rb
+- lib/esp/providers.rb
+- lib/esp/providers/anthropic.rb
+- lib/esp/providers/ollama.rb
+- lib/esp/providers/openai.rb
+- lib/esp/recents.rb
+- lib/esp/ui.rb
+- lib/esp/vcs.rb
+- lib/esp/version.rb
+- lib/esp/watcher.rb
+- locales/en.yml
+- locales/fr.yml
+homepage: https://github.com/ninjacazaam/esp-modkit
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/ninjacazaam/esp-modkit
+  changelog_uri: https://github.com/ninjacazaam/esp-modkit/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.3'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.6
+specification_version: 4
+summary: Author Morrowind plugins as source code.
+test_files: []