esp-modkit 0.1.0

data/docs/reference/api/mw-scaffolder.md

@@ -0,0 +1,13 @@
+<!-- esp:auto — regenerated by `esp docs build`; edits here are overwritten -->
+
+# Esp::Mw::Scaffolder
+
+**Source:** `lib/esp/mw/scaffolder.rb`
+
+Scaffolds a fresh mod folder under `mods/<Mod>/`. One TES3 Header
+record (pre-filled with sensible defaults), one README, and that's
+it — no script / i18n / design subdirectories until the author
+actually wants them. Picks the source format from `--format`;
+subprocess formats get a `#!` line and exec bit.
+
+<!-- /esp:auto — write durable docs below this line; they survive rebuilds -->

data/docs/reference/api/mw-script-blob.md

@@ -0,0 +1,31 @@
+<!-- esp:auto — regenerated by `esp docs build`; edits here are overwritten -->
+
+# Esp::Mw::ScriptBlob
+
+**Source:** `lib/esp/mw/script_blob.rb`
+
+Synthesizes the ZSTD-framed blobs that tes3conv expects for a Script
+record's SCVR (variable list) and SCDT (bytecode) subrecords.
+
+Vanilla blobs use ZSTD frames whose blocks may be raw (small/empty
+scripts) or compressed-with-LZ77 matches (large scripts). tes3conv
+accepts either, so we always emit raw blocks — simpler, smaller code,
+and only marginally larger output. Decoding always goes through
+libzstd via zstd-ruby so we can extract names from any vanilla blob.
+
+Raw frame layout:
+  4 bytes  ZSTD magic                (28 b5 2f fd)
+  1 byte   Frame Header Descriptor   (0x00)
+  1 byte   Window Descriptor         (0x58)
+  3 bytes  Block header              ((size << 3) | type<<1 | last_block)
+  N bytes  Raw payload
+
+Payload layout (both SCVR and SCDT placeholder):
+  4 bytes  LE uint32 — byte length of names section (0 if none)
+  N bytes  Null-terminated variable names, concatenated
+
+Empty vars and the bytecode placeholder both use a 4-byte zero payload
+(length prefix = 0). A truly zero-byte payload is rejected by tes3conv
+for SCDT and isn't what vanilla emits anywhere.
+
+<!-- /esp:auto — write durable docs below this line; they survive rebuilds -->

data/docs/reference/api/mw-script-extractor.md

@@ -0,0 +1,17 @@
+<!-- esp:auto — regenerated by `esp docs build`; edits here are overwritten -->
+
+# Esp::Mw::ScriptExtractor
+
+**Source:** `lib/esp/mw/script_extractor.rb`
+
+Inverse of preflight's text_source resolution. Given a JSON-format mod
+source whose Script records carry inline `text`, hoist each script
+body out to `scripts/<id>.mwscript` and replace the inline fields
+(`text`, `bytecode`, `variables`, `header`) with a single
+`text_source` pointer. Preflight regenerates everything on build, so
+the resulting source round-trips losslessly through `esp build`.
+
+Skips records that already have `text_source` set — re-running is a
+no-op. .rb sources are out of scope; their author owns the layout.
+
+<!-- /esp:auto — write durable docs below this line; they survive rebuilds -->

data/docs/reference/api/operations.md

@@ -0,0 +1,25 @@
+<!-- esp:auto — regenerated by `esp docs build`; edits here are overwritten -->
+
+# Esp::Operations
+
+**Source:** `lib/esp/operations.rb`
+
+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.
+
+<!-- /esp:auto — write durable docs below this line; they survive rebuilds -->

data/docs/reference/api/plugins.md

@@ -0,0 +1,24 @@
+<!-- esp:auto — regenerated by `esp docs build`; edits here are overwritten -->
+
+# Esp::Plugins
+
+**Source:** `lib/esp/plugins.rb`
+
+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.
+
+<!-- /esp:auto — write durable docs below this line; they survive rebuilds -->

data/docs/reference/api/preferences.md

@@ -0,0 +1,13 @@
+<!-- esp:auto — regenerated by `esp docs build`; edits here are overwritten -->
+
+# Esp::Preferences
+
+**Source:** `lib/esp/preferences.rb`
+
+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.
+
+<!-- /esp:auto — write durable docs below this line; they survive rebuilds -->

data/docs/reference/api/project-marker.md

@@ -0,0 +1,23 @@
+<!-- esp:auto — regenerated by `esp docs build`; edits here are overwritten -->
+
+# Esp::ProjectMarker
+
+**Source:** `lib/esp/project_marker.rb`
+
+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).
+
+<!-- /esp:auto — write durable docs below this line; they survive rebuilds -->

data/docs/reference/api/providers.md

@@ -0,0 +1,22 @@
+<!-- esp:auto — regenerated by `esp docs build`; edits here are overwritten -->
+
+# Esp::Providers
+
+**Source:** `lib/esp/providers.rb`
+
+The LLM-provider seam behind Esp::Agent. Each provider translates the
+agent's neutral transcript to its API's native wire shape and normalizes
+the response back to a Completion. Providers self-register here, so adding
+one is a new file under providers/ plus a require in the load manifest.
+
+Provider contract:
+  #complete(system:, tools:, messages:) -> Completion(text:, tool_calls:, raw:)
+    system   — String system prompt
+    tools    — Array<{name:, description:, input_schema:}> (JSON-Schema)
+    messages — the neutral transcript (see Esp::Agent)
+    raw      — the provider-native assistant *message* for this turn, stored
+               on the assistant entry and replayed verbatim next call so
+               provider-side state (Anthropic thinking signatures, OpenAI
+               tool_calls) survives multi-turn tool use.
+
+<!-- /esp:auto — write durable docs below this line; they survive rebuilds -->

data/docs/reference/api/recents.md

@@ -0,0 +1,17 @@
+<!-- esp:auto — regenerated by `esp docs build`; edits here are overwritten -->
+
+# Esp::Recents
+
+**Source:** `lib/esp/recents.rb`
+
+Per-user "recently opened projects" list, persisted as JSON in the data
+directory the Tauri shell injects via ESP_DATA_DIR (macOS:
+~/Library/Application Support/com.coreyellis.espresso/). Falls back to
+~/.config/esp/ for CLI / unit-test use. The MW_DATA_DIR env var still
+works as a one-release deprecation alias so existing dev shells keep
+finding the same on-disk state; remove after step 24 ships.
+Single-writer per process — the mutex serialises threaded WEBrick
+handlers; cross-process collisions are accepted in v1 (one ESPresso ↔
+one backend).
+
+<!-- /esp:auto — write durable docs below this line; they survive rebuilds -->

data/docs/reference/api/ui.md

@@ -0,0 +1,21 @@
+<!-- esp:auto — regenerated by `esp docs build`; edits here are overwritten -->
+
+# Esp::Ui
+
+**Source:** `lib/esp/ui.rb`
+
+Internal i18n for the *tool's own* user-facing strings — CLI output and
+error messages. Distinct from Esp::Mw::I18n, which localizes mod *content*;
+this localizes mw itself so the distributed tool can ship in other
+languages.
+
+Catalogues live at locales/<locale>.yml, resolved relative to this file
+(they ship with the tool, independent of Esp::ROOT — which points at the
+user's mod project). Lookup is dot-pathed with %{named} interpolation,
+falling back to en, then to the key itself.
+
+Active locale: ESP_UI_LOCALE (with MW_UI_LOCALE honoured as a one-release
+deprecation alias), then LANG/LC_ALL (stripped to the language subtag,
+e.g. "fr_FR.UTF-8" -> "fr"), then en. Tests pin it to en.
+
+<!-- /esp:auto — write durable docs below this line; they survive rebuilds -->

data/docs/reference/api/vcs.md

@@ -0,0 +1,17 @@
+<!-- esp:auto — regenerated by `esp docs build`; edits here are overwritten -->
+
+# Esp::Vcs
+
+**Source:** `lib/esp/vcs.rb`
+
+A thin wrapper over the `git` CLI, scoped to a working-tree `root`. Backs
+the diff-review loop (step 20): list working-tree changes, show one file's
+diff, stage approved files, discard rejected ones. We shell out rather than
+bind libgit2 (nothing extra to ship) — the project is already a git repo.
+
+Every method takes an explicit `root` so it operates on the *user's* mod
+project, never the toolchain repo, and so it's testable against a scratch
+repo. Git failures raise GitError; the Operations layer maps that to a
+caller-facing error.
+
+<!-- /esp:auto — write durable docs below this line; they survive rebuilds -->

data/docs/reference/api/watcher.md

@@ -0,0 +1,11 @@
+<!-- esp:auto — regenerated by `esp docs build`; edits here are overwritten -->
+
+# Esp::Watcher
+
+**Source:** `lib/esp/watcher.rb`
+
+File-watch-driven rebuild. Watches a mod's source directory (and
+its scripts/, i18n/, etc. subtrees) and re-invokes Esp::Mw::Builder on
+any matching change. Blocks until SIGINT.
+
+<!-- /esp:auto — write durable docs below this line; they survive rebuilds -->

data/docs/reference/commands.md

@@ -0,0 +1,271 @@
+<!-- esp:auto — regenerated by `esp docs build`; edits here are overwritten -->
+
+# Command reference
+
+Every command accepts `--json` for structured output to stdout.
+Errors print as `{"error": "..."}` to stderr with a non-zero exit.
+
+## Top-level commands
+
+### `esp version`
+
+Print esp version
+
+Usage: `esp version`
+
+Options:
+- `--json` — Output structured JSON instead of human text
+- `--root STRING` — Project root (defaults to the active project or the toolchain repo)
+
+### `esp doctor`
+
+Check install prerequisites (Ruby, tes3conv, references index)
+
+Usage: `esp doctor`
+
+Options:
+- `--json` — Output structured JSON instead of human text
+- `--root STRING` — Project root (defaults to the active project or the toolchain repo)
+
+### `esp init`
+
+Bootstrap an esp project here (or in NAME subdir) — writes .esp/project.json + git init
+
+Usage: `esp init [NAME]`
+
+Options:
+- `--game STRING` — Game plugin (default: mw; pass --game ob etc. once those plugins exist)
+- `--force` — Re-initialise even if .esp/project.json already exists
+- `--json` — Output structured JSON instead of human text
+- `--root STRING` — Project root (defaults to the active project or the toolchain repo)
+
+### `esp setup`
+
+Configure git diff driver + tracked pre-commit hooks
+
+Usage: `esp setup`
+
+Options:
+- `--json` — Output structured JSON instead of human text
+- `--root STRING` — Project root (defaults to the active project or the toolchain repo)
+
+### `esp new`
+
+Scaffold a new mod folder under mods/<MOD>/
+
+Usage: `esp new MOD`
+
+Options:
+- `--format STRING` — Source format: json | rb | py | js | mjs | ts
+- `--author STRING` — Author name (default: git config user.name)
+- `--description STRING` — Plugin description
+- `--force` — Overwrite an existing mod folder
+- `--json` — Output structured JSON instead of human text
+- `--root STRING` — Project root (defaults to the active project or the toolchain repo)
+
+### `esp unpack`
+
+Import a plugin (a path, or an installed plugin NAME) to mods/<name>/
+
+Usage: `esp unpack PLUGIN [NAME]`
+
+Options:
+- `--config STRING` — openmw.cfg to resolve a bare plugin NAME against
+- `--json` — Output structured JSON instead of human text
+- `--root STRING` — Project root (defaults to the active project or the toolchain repo)
+
+### `esp build`
+
+Build mods/<MOD>/<MOD>.{json,rb,py,js,mjs,ts} -> dist/<MOD>[.locale].esp
+
+Usage: `esp build [MOD]`
+
+Options:
+- `--all` — Build every mod in mods/
+- `--install` — After building, register the mod(s) with openmw.cfg
+- `--config STRING` — openmw.cfg to register with (implies --install target)
+- `--locale STRING` — Build with this locale (suffixes the output: dist/<MOD>.<locale>.esp)
+- `--json` — Output structured JSON instead of human text
+- `--root STRING` — Project root (defaults to the active project or the toolchain repo)
+
+### `esp install`
+
+Register dist/<MOD>.esp with OpenMW's openmw.cfg (and/or copy to Data Files)
+
+Usage: `esp install MOD`
+
+Options:
+- `--copy_to STRING` — Also copy the built .esp into PATH (original-engine users: Morrowind/Data Files/)
+- `--to_data_files` — Also copy to the auto-detected Morrowind Data Files dir (MORROWIND_DATA env override)
+- `--register_openmw` — Register with openmw.cfg (default: true; --no-register-openmw skips)
+- `--json` — Output structured JSON instead of human text
+- `--root STRING` — Project root (defaults to the active project or the toolchain repo)
+
+### `esp lint`
+
+Find dangling refs and missing-master issues using the reference index
+
+Usage: `esp lint MOD`
+
+Options:
+- `--json` — Output structured JSON instead of human text
+- `--root STRING` — Project root (defaults to the active project or the toolchain repo)
+
+### `esp watch`
+
+Rebuild MOD on any change under mods/<MOD>/. Blocks until Ctrl-C.
+
+Usage: `esp watch MOD`
+
+Options:
+- `--locale STRING` — Build with this locale on each change
+- `--json` — Output structured JSON instead of human text
+- `--root STRING` — Project root (defaults to the active project or the toolchain repo)
+
+### `esp serve`
+
+Start the HTTP API on localhost (mirrors the CLI; same payload shapes)
+
+Usage: `esp serve`
+
+Options:
+- `--port NUMERIC` — TCP port to bind on localhost
+- `--json` — Output structured JSON instead of human text
+- `--root STRING` — Project root (defaults to the active project or the toolchain repo)
+
+### `esp extract-scripts`
+
+Move every Script record's inline text into mods/<MOD>/scripts/<id>.mwscript
+
+Usage: `esp extract-scripts MOD`
+
+Options:
+- `--json` — Output structured JSON instead of human text
+- `--root STRING` — Project root (defaults to the active project or the toolchain repo)
+
+## `esp plugins` subcommand group
+
+Inspect installed OpenMW plugins
+
+### `esp plugins list`
+
+List plugins installed in OpenMW (active flag + load order)
+
+Usage: `esp list`
+
+Options:
+- `--config STRING` — Path to openmw.cfg (default: per-OS user config)
+- `--json` — Output structured JSON instead of human text
+
+## `esp refs` subcommand group
+
+Manage vanilla ESM references
+
+### `esp refs unpack`
+
+Convert vanilla ESMs to JSON under the per-user references directory
+
+Usage: `esp unpack`
+
+Options:
+- `--data STRING` — Data Files directory (default: $MORROWIND_DATA or the detected install)
+- `--json` — Output structured JSON instead of human text
+- `--references_dir STRING` — Override the references directory (default: $ESP_REFERENCES_DIR or $ESP_DATA_DIR/references)
+
+### `esp refs index`
+
+Build/refresh the SQLite index over the per-user references directory
+
+Usage: `esp index`
+
+Options:
+- `--json` — Output structured JSON instead of human text
+- `--references_dir STRING` — Override the references directory (default: $ESP_REFERENCES_DIR or $ESP_DATA_DIR/references)
+
+### `esp refs find`
+
+Find vanilla records — substring match on id + name by default
+
+Usage: `esp find [QUERY]`
+
+Options:
+- `--type STRING` — Filter by record type (e.g. Npc, Cell, Script)
+- `--like STRING` — SQL LIKE pattern on id (e.g. 'Fargoth%')
+- `--exact` — Match QUERY as an exact id instead of a substring
+- `--show` — Print full JSON of each match
+- `--limit NUMERIC` — Max rows to print
+- `--json` — Output structured JSON instead of human text
+- `--references_dir STRING` — Override the references directory (default: $ESP_REFERENCES_DIR or $ESP_DATA_DIR/references)
+
+## `esp i18n` subcommand group
+
+Translation catalogue tools
+
+### `esp i18n check`
+
+Report missing/orphan i18n keys per locale (vs. en)
+
+Usage: `esp check MOD`
+
+Options:
+- `--json` — Output structured JSON instead of human text
+- `--root STRING` — Project root (defaults to the active project or the toolchain repo)
+
+### `esp i18n audit`
+
+Audit tool-UI locales: undefined/unused/orphan keys + missing translations
+
+Usage: `esp audit`
+
+Options:
+- `--json` — Output structured JSON instead of human text
+- `--root STRING` — Project root (defaults to the active project or the toolchain repo)
+
+## `esp docs` subcommand group
+
+Generate / introspect reference documentation
+
+### `esp docs build`
+
+Regenerate docs/reference/ from the CLI tree and module headers
+
+Usage: `esp build`
+
+Options:
+- `--out STRING` — Output directory (relative to repo root)
+- `--json` — Output structured JSON instead of human text
+
+### `esp docs introspect`
+
+Dump the CLI command tree + module surface as JSON (always JSON)
+
+Usage: `esp introspect`
+
+Options:
+- `--json` — Output structured JSON instead of human text
+
+## `esp mcp` subcommand group
+
+Model Context Protocol server for AI tools
+
+### `esp mcp serve`
+
+Run the MCP server over stdio (JSON-RPC 2.0) for AI clients
+
+Usage: `esp serve`
+
+Options:
+- `--json` — Output structured JSON instead of human text
+
+### `esp mcp install`
+
+Register `esp mcp serve` with an AI client (Claude Code / Desktop)
+
+Usage: `esp install`
+
+Options:
+- `--client STRING` — Which MCP client to configure
+- `--name STRING` — Name to register the server under in mcpServers
+- `--json` — Output structured JSON instead of human text
+
+<!-- /esp:auto — write durable docs below this line; they survive rebuilds -->