Add first-class TypeScript authoring for plugins (compile-to-JS, runtime unchanged)

[davidarny]

Problem

Plugin runtime is JS-only (QuickJS eval of manifest entry), but plugin logic is getting complex and currently lacks first-class type-safety and API autocomplete.

Current state:

• Manifest entry is loaded as raw script text and eval’d.
• Runtime expects globalThis.__openusage_plugin.probe.
• No transpile step exists in dev/build plugin pipeline.

This makes plugin authoring more error-prone than needed.

Goal

Allow plugin authors to write plugins in TypeScript while keeping runtime execution model unchanged (compiled JS in QuickJS).

Proposal (MVP)

• Keep runtime contract unchanged: manifest entry still points to JS file executed by QuickJS.
• Add TS authoring convention:
  • plugins/<id>/src/plugin.ts (source)
  • plugins/<id>/plugin.js (generated artifact, committed)
• Add plugin build command to transpile all plugin TS sources to single-file JS suitable for QuickJS.
• Add typed SDK for plugin authors (e.g. ProbeContext, MetricLine, ctx.host.*, ctx.line.*) based on current host API.
• Add CI check to fail if generated plugin.js is stale relative to source.
• Update plugin docs/examples to TS-first authoring with JS runtime output.

Acceptance Criteria

• A plugin can be authored in .ts with full IntelliSense for context/line builders/host APIs.
• Generated plugin.js loads in current runtime without Rust changes.
• Existing plugin behavior remains unchanged.
• CI prevents drift between TS source and generated JS output.
• Docs include TS workflow and migration example.

Non-goals

• Running .ts directly in runtime.
• Introducing npm package resolution inside plugin runtime.
• Replacing QuickJS with Node/V8.

Implementation Notes

• Output should be a self-contained script compatible with current eval/global registration pattern.
• Prefer conservative JS target/format for QuickJS compatibility.
• Ensure generated code still sets globalThis.__openusage_plugin = { id, probe }.

Related

• Add proper OAuth flow to plugin API #71 (plugin API evolution)
• Add Windows support in Tauri + Plugin API #77 (cross-platform/plugin API broader context)

[robinebers]

that sounds great to be honest. one of the reason I chose JS was speed, and uncertainty over API design which still evolves (though has slowed down now).

there are a few big changes left. specifically oauth flow, and probably some refactoring before we lock core and rely on plugins, opening the system.

i fully support this though

[davidarny]

@robinebers totally agree, let’s lock core first.
OAuth flow + the remaining refactors should come before we freeze plugin contracts and open the system.

Once core/API is stable, we can add TS authoring safely (compile to plugin.js, typed SDK, CI freshness checks) without runtime risk.

I’m fully aligned with this order, and I’ll be glad to help when you start that phase. I’m also open to being assigned on any issues where I can support the project.