Developer Tools

`shire-plugin` CLI

python tools/shire-plugin/shire_plugin.py <command>

Command	What it does
`init --lang ... --name ... --dir ...`	creates a project from a template and copies the SDK
`validate <dir-or-.shiremod>`	checks the manifest, permissions, safety and entrypoint
`build <dir>`	compiles TypeScript, Rust, C++, or C# projects
`pack <dir> [-o file.shiremod]`	writes a stored ZIP, bundles the Python SDK, prints SHA-256
`test <dir>`	starts the standalone mock Host, launches the plugin, reports success
`dev <dir>`	same as `test` but keeps the mock Host alive for iteration

init supports Python, TypeScript, Node/JavaScript, C++, Rust and C#.

API Mock

shire_mock_host.exe is built from the real plugin_host.cpp and plugin_protocol.cpp with a fake CoreApi. It returns deterministic player, entity and marker data and records teleports. It does not contain game offsets or Shire feature code.

gi7-hack\build\Release\shire_mock_host.exe `
  --manifest tests\plugin\fixtures\contract\manifest.json `
  --seconds 30

It prints:

PIPE=\\.\pipe\shire-mock-…
TOKEN=…
PLUGIN_ID=com.shire.contract
READY=1

The CLI test/dev path starts it and sets the environment for the plugin.

Useful flags:

Flag	Meaning
`--manifest <path>`	manifest used by the ephemeral plugin record
`--seconds <n>`	lifetime
`--pipe <name>`	explicit pipe name
`--token <hex>`	explicit token
`--root <dir>`	plugin root (defaults to a temp directory)
`--no-auto-approve`	leave permissions ungranted (permission-denial tests)
`--install <pkg>`	install a `.shiremod`, print `INSTALL=ok/error=…`, exit
`--remove <id>`	remove an installed plugin, print `REMOVE=ok`, exit

The mock writes a debug trace to %TEMP%\shire_host_debug.log; production builds do not compile this trace.

Contract and documentation

sdk/contract/api.json is the source of truth for methods, permissions, events, UI types and errors. The Host's handshake and api.info are compared to it by the contract tests. Regenerate the API reference with:

python tools/shire-plugin/gen_docs.py

Tests

python tests/plugin/test_contract.py

The suite starts the real mock Host and covers:

handshake, capabilities, permissions, events and UI types against the contract;
player, entities, markers, storage, notifications, UI and teleport;
permission denial with --no-auto-approve;
malformed JSON (-32700) and the rate limit (-32001);
CLI validate/pack, stored ZIP, bundled SDK, install/remove and a real example.

Latest local result: 5 passed.

Logs and diagnostics

Plugin logs: %LOCALAPPDATA%\Shire\plugins\<id>\data\plugin.log, also visible in the Plugin Manager.
Mock Host trace: %TEMP%\shire_host_debug.log (mock target only).
Plugin Manager: state, last error, calls, errors, memory and the pipe name.
Manifest validator: shire-plugin validate and the Host install error.
Permission dashboard: the selected plugin's declared and approved permissions.

CPU sampling, per-call latency graphs and an interactive API playground are roadmap items; the current host reports call/error counts and process memory.