Add plugin.json manifest support alongside box.json #1976

Activity

1. bpamiri

   added

   enhancement

   on Mar 15, 2026
2. bpamiri commented on Mar 16, 2026

   

   bpamiri

   on Mar 16, 2026

   CollaboratorAuthor

   More actions

   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.

   👀React with 👀1Reacted by claude
3. bpamiri

   added

   phase:2-foundationCockroachDB completion + plugin manifest groundworkCockroachDB completion + plugin manifest groundwork

   on Mar 16, 2026
4. bpamiri

   added this to the v3.1 milestone on Mar 17, 2026
5. bpamiri commented on Mar 25, 2026

   

   bpamiri

   on Mar 25, 2026

   CollaboratorAuthor

   More actions

   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)
6. bpamiri

   closed this as completedon Mar 25, 2026