Development chronicle — mb606 to mb607 · Offline validation and truthful dry-runs

Plugin v2 has gained a proper workshop.

Until now, writing or checking a sidecar plugin usually meant running Mediabot itself — which also meant a database, an IRC connection, a configured instance and all the surrounding runtime.

That is no longer necessary.

Mediabot now ships an offline development tool that can validate and dry-run v2 sidecars with the same core components used by the bot itself.

---

🧰 mb606 — Validate a plugin without starting Mediabot

The new tool is:

tools/mb_plugin_dev.pl

It supports two main workflows.

Validate a sidecar

tools/mb_plugin_dev.pl validate examples-v2/karma.py

Example output:

OK    sidecar accepted: karma v1.0 (api 2)
      commands: karma, thanks

Dry-run a command

tools/mb_plugin_dev.pl run examples-v2/karma.py   --command thanks   --nick aur   --arg SlaY   --storage /tmp/state.json

Example:

Ran examples-v2/karma.py (python, 0.074s)

Actions the bot would take:
  store   29 bytes (limit 16384)
          {"scores":{"bob":1,"slay":4}}

  reply   #dev: SlaY now has 4 karma.

OK    every action passes the bot's contract.
Nothing was applied.

Dry-run an event

tools/mb_plugin_dev.pl run examples-v2/daily.tcl   --event plugin_cron_observed   --config CHANNEL='#dev'   --config TEXT='Morning!'   --data hour=9   --data minute=0

This makes it possible to develop command-driven and event-driven plugins without bringing up a complete bot instance.

---

🧱 One important design rule: reuse the real implementation

The tool does not maintain a second copy of the plugin rules.

It builds a minimal offline bot and uses the real:

Mediabot::PluginManager
Mediabot::ScriptRunner
Mediabot::ScriptActionRunner

That means the same runtime code performs:

• sidecar validation;
• command validation;
• event allow-list checks;
• config normalization;
• storage validation;
• script execution;
• action validation;
• reply/notice scope checks;
• storage-size checks.

If the contract changes later, the development tool follows the implementation instead of slowly drifting into a second specification.

Even constants such as the store-size limit are read from the real runtime modules rather than duplicated in the tool.

---

🧪 Real execution, dry application

There is an important distinction.

When using:

mb_plugin_dev.pl run

the Perl, Python or Tcl script is really executed.

What remains dry-run is the action layer returned to Mediabot.

So the tool may show:

reply
notice
store

but Mediabot itself will not:

• send the IRC message;
• persist the store action;
• create plugin storage because of the planned action.

This makes the tool suitable for trusted plugin development and CI while avoiding the side effects Mediabot would normally perform.

It is not an operating-system sandbox for hostile scripts.

---

🪄 mb607 — Make the mirror tell the exact truth

The pre-commit review found a few places where the offline tool could present something slightly different from what the real bot would see.

Those differences are now closed.

Event envelopes match the bot

The public event name and the internal event_type are not always identical.

For example:

plugin_cron_observed  → cron
channel_join_observed → join
channel_part_observed → part
channel_nick_observed → nick

The offline tool now builds these envelopes using the same semantics as the live bot.

--show-envelope therefore shows what the script would actually receive.

PluginManager validates before metadata is trusted

The development tool no longer opens the sidecar itself just to discover the plugin name before validation.

The flow is now:

sidecar/script path
        ↓
real PluginManager validation
        ↓
validated plugin identity
        ↓
offline config / storage inputs
        ↓
real dry-run

This keeps path validation, sidecar limits, JSON parsing and identity checks behind the same boundary as production.

Offline storage input is validated too

A developer-provided storage fixture is passed through the real plugin storage validator before it is exposed as:

data.storage

A test fixture can no longer feed a state document that the live bot itself would refuse.

Privileged commands are explicit

The tool can exercise a command declared as Master or another named level, but it does not pretend to reproduce a live authenticated USER_LEVEL session.

The output says so clearly.

Authorization remains a live-bot concern; command behavior can still be tested offline.

---

🧪 Validation

The complete test suite passed:

PASSED : 12079/12079

The dedicated offline-tool tests cover:

• sidecar validation;
• real Perl/Python/Tcl execution paths;
• command dry-runs;
• event dry-runs;
• config injection;
• storage fixtures;
• action planning without application;
• real runtime constants;
• exact cron and channel-event envelopes;
• validated plugin identity;
• malformed storage rejection;
• privileged-command transparency;
• no accidental Mediabot action application.

---

🧙 Why this matters

A plugin author can now work in a much smaller loop:

edit plugin
    ↓
validate
    ↓
dry-run command/event
    ↓
inspect envelope and planned actions
    ↓
run tests
    ↓
load into Mediabot

No IRC server is required for the first four steps.

No database is required.

No production bot needs to be disturbed.

And, crucially, the offline tool is not trying to guess what Mediabot would do.

It asks Mediabot’s own plugin machinery.

---

🏰 Final parchment

The castle now has a proper practice room.

A portrait can be inspected before it is hung on the wall. Its spells can be rehearsed, its event scrolls opened, and every action checked by the same rules used in the Great Hall.

The mirror does not cast the spells for real.

But it now reflects the castle faithfully.