Add plugin.json manifest support alongside box.json

[bpamiri]

Summary

Add declarative plugin.json manifest support for plugins, inspired by LuCLI's module.json format. This enables future features (service registration, middleware, semver deps) without breaking existing plugins.

Proposed Manifest Format

{
  "name": "authenticateThis",
  "version": "2.1.0",
  "description": "Authentication plugin for Wheels",
  "author": "Plugin Author",
  "wheelsVersion": ">=3.0.0 <4.0.0",
  "mixin": "controller",
  "dependencies": {
    "someOtherPlugin": ">=1.0.0"
  },
  "services": {
    "auth": {
      "class": "AuthService",
      "scope": "singleton"
    }
  },
  "middleware": ["AuthMiddleware"]
}

Changes

• Extend $pluginMetaData() to look for plugin.json in the plugin directory
• Parse manifest and populate plugin metadata from it
• Fall back to existing CFC metadata / box.json if plugin.json not present
• Existing plugins with no manifest continue to work unchanged

Files

• vendor/wheels/Plugins.cfc:184-196 — extend $pluginMetaData()

Phase

Phase 1 — Cleanup & Foundation (3.x, no breaking changes)

Reference

• LuCLI manifest: cli/lucli/module.json
• Enables issues New master - Microsoft Access Adapter #5–adding better description for hasManyCheckBox #8 (lifecycle hooks, DI integration, middleware, semver deps)

[bpamiri]

Analysis

Synopsis

Add optional plugin.json manifest support to plugin metadata discovery, enabling plugins to declaratively specify version, dependencies, mixin targets, services, and middleware — without breaking existing plugins that use CFC metadata or box.json.

Merit Assessment

Recommendation: Proceed with modifications

• Strong foundation for Phase 2+ features (DI integration, middleware registration, semver dependency checking) without requiring any of those features to exist yet.
• Backward-compatible by design — $pluginMetaData() (line 184-196) already falls back gracefully, and plugin.json would simply take priority over box.json.
• The services and middleware keys should be parsed and stored but not acted upon in this issue — those behaviors belong to later issues. This issue is manifest parsing only.
• Consider validating the manifest with a minimal schema (required: name, version) and logging warnings for unrecognized keys, to catch typos early.

Implementation Plan

1. Extend $pluginMetaData() in vendor/wheels/Plugins.cfc:184-196:

   • Before checking box.json, look for plugin.json in the plugin directory.
   • If found, DeserializeJSON(FileRead(...)) and store the full manifest in pluginMeta[plugin]["manifest"].
   • Populate pluginMeta[plugin]["version"] from the manifest's version field.
   • If plugin.json exists, still read box.json but let plugin.json values take precedence.

2. Store new metadata fields in $class.pluginMeta:

   • Add keys: manifest (raw struct), mixin (string, for $processMixins to optionally use later), dependencies (struct), services (struct), middleware (array).
   • These are stored but not consumed by any logic in this issue.

3. Add tests in vendor/wheels/tests/specs/pluginsSpec.cfc:

   • Create a new test plugin asset directory (e.g., tests/_assets/plugins/manifest/) with a plugin that has a plugin.json.
   • Verify getPluginMeta() returns the manifest data.
   • Verify fallback still works when plugin.json is absent.

4. Estimated complexity: Low-medium — ~30-40 lines of new code in $pluginMetaData(), plus test fixtures.

Dependencies & Risks

• No prerequisites — this is purely additive metadata.
• Enables Plugin namespace isolation — detect and warn on method collisions #1977 (collision detection can read manifest for explicit override declarations), Support directory-based plugins without zip files #1978 (directory-based plugins can use plugin.json as their validity marker).
• Future issues for DI integration and middleware registration will consume the services and middleware manifest keys.
• Risk: minimal — existing plugins without plugin.json are completely unaffected.

---

Automated analysis by @claude — review and adjust as needed.

[bpamiri]

Implemented in develop. Full plugin.json manifest support with graceful fallback.

• d08733f feat: add plugin.json manifest schema, parser, and validation (wh-mkd.1)
• b83474d feat: integrate plugin.json manifest into plugin loading pipeline (wh-mkd.2)
• 7602208 feat: graceful fallback when plugin has no plugin.json manifest (wh-mkd.3)