@omniterm/shiplight-debugger-plugin

@omniterm/shiplight-debugger-plugin

The Shiplight YAML test debugger as a plugin for omniterm, the open-source browser-based development host. It adapts shiplightai's debugger engine onto omniterm's runtime plugin contract: right-click a *.test.yaml in the file panel and open it in a debugger tab.

npm install -g @omniterm/host @omniterm/shiplight-debugger-plugin
omniterm --plugin @omniterm/shiplight-debugger-plugin
# Open http://localhost:17717

Both packages have to be installed: --plugin takes a module the host imports, and a bare package name only resolves if the package is actually on disk. Installing them together puts the plugin beside the host in the same global node_modules, which is where the host looks.

The host is not in this repository. It is developed in the open at engianx/omniterm and published as @omniterm/host; this repo is only the plugin — which is the point. A plugin lives in its own repository, depends on nothing but the published contract, and is added or removed without touching the host.

How it depends on the host

Only through @omniterm/plugin-types, a published type-only package: TabTypePlugin, HostContext, PluginInstance, and the workspace shapes reachable through HostContext.

Every one of those imports is erased at build time, so the plugin has no runtime dependency on omniterm at all — it is a plain Express router plus a manifest entry. It does not import @omniterm/core, and core is not installable outside the host's own repo, by design.

Develop

pnpm install
pnpm typecheck
pnpm test
pnpm build

Run the plugin against a real host — install the host from npm, then point it at the built entry file:

npm install -g @omniterm/host
pnpm build
omniterm --plugin ./dist/index.js
# Open http://localhost:17717, right-click a *.test.yaml → "Open in debugger"

--plugin also accepts a published package name (omniterm --plugin @omniterm/shiplight-debugger-plugin); the path form is for iterating locally. A path must point at the built entry file — a bare directory is not a resolvable ES module.

Release

@omniterm/shiplight-debugger-plugin publishes via .github/workflows/publish-debugger-plugin.yml (manual dispatch). The host and @omniterm/plugin-types release from the public repo on their own schedules — this repo neither gates them nor is gated by them.

Repository layout

• src/ — the plugin source; dist/index.js is the built entry (gitignored).
• specs/, quality-evidence/ — spec and evidence for the plugin feature.
• tests/agent/ — agent-driven end-to-end verification of the plugin running inside a real host.