v0.4.0 — Plugin system (custom checks + rules)

Third minor release. beacon doctor and beacon lint are now extensible — third-party plugins can add custom checks and rules without forking Beacon.

This is the last major deferred feature before v1.0.

✨ Plugin system

Configure plugins in docs/_meta/beacon.config.json:

{
  "plugins": [
    "beacon-plugin-compliance",          // npm package
    "./scripts/internal-checks.mjs"      // relative path
  ]
}

A plugin is a JS module exporting a BeaconPlugin object:

export default {
  name: "my-plugin",                  // required, unique
  version: "0.1.0",                   // optional
  checks: [/* doctor Check[] */],     // contribute doctor checks
  rules:  [/* lint Rule[]  */],       // contribute lint rules
  explain: {                          // optional --explain entries
    "my-check": { summary: "...", why: "...", fix: "..." },
  },
};

Plugin-contributed checks/rules fire alongside built-ins. Both default and named plugin exports are accepted.

🛡️ Error handling

Plugin load failures never crash doctor or lint. They surface as stderr warnings while built-ins continue running:

⚠ Plugin "./scripts/internal-checks.mjs" failed to load: Cannot find module './scripts/internal-checks.mjs'
◉ Activity (0)
...

🔍 --explain and beacon about integration

• beacon doctor --explain <check> and beacon lint --explain <rule> now look up plugin-contributed names. Typo correction spans both built-in and plugin sets.
• beacon about lists loaded plugins with versions and contributed counts:

Plugins
  ✔ beacon-plugin-example@0.1.0 (1 check, 1 rule)
     source: ./examples/plugin-example/index.mjs

📦 Working reference plugin

examples/plugin-example/ ships in the repo with a working tiny-evals check + no-inline-todo rule, full --explain entries, and end-to-end integration tests. Use it as a starting template.

📖 Authoring guide

• docs/reference/writing-a-plugin.pattern.md — full contract walkthrough with copy-paste examples
• ADR-011 — design rationale, alternatives considered, scope decisions

Publishing convention:

{
  "name": "beacon-plugin-<scope>",
  "type": "module",
  "main": "./index.mjs",
  "peerDependencies": { "beacon-docs": "^0.4.0" },
  "keywords": ["beacon", "beacon-plugin"]
}

🧰 Scope decisions (deferred to v0.5+)

• Custom categories (declare new folder + suffix + archival policy)
• Custom AI agents (declare new generated file format)

Both deferred pending real plugin authoring experience — easier to design with data than preemptively.

Tests

+31 new tests (271 → 302 passing across 48 files):

• 14 loader unit tests (path resolution, contract validation, error accumulation)
• 7 explain unit tests
• 2 beacon about plugin tests
• 4 plugin integration tests (doctor + lint, error surfacing)
• 4 example-plugin end-to-end tests (the shipped reference plugin)

Install / upgrade

npm install -g beacon-docs@0.4.0
# then in your project:
beacon about                   # see installed plugins

Full changelog: https://github.com/Juliocbm/beacon-docs/blob/main/CHANGELOG.md