Support directory-based plugins without zip files

[bpamiri]

Summary

Currently, plugins must be distributed as .zip files in the plugins/ directory. The $pluginDelete() function actively removes directories that lack a matching zip — which means git-cloned, symlinked, or manually installed plugin directories are deleted on application start.

Current Behavior

1. $pluginsExtract() unzips .zip files from plugins/ to subdirectories
2. $pluginDelete() removes any directory in plugins/ that doesn't have a matching .zip file
3. Directory-only plugins are destroyed on every reload

Proposed Behavior

• Recognize plugin directories that contain a valid plugin CFC (or plugin.json) as first-class plugins
• $pluginDelete() should only remove directories that are orphaned extraction artifacts, not intentionally placed directories
• A directory with a plugin.json or a CFC with init() returning this.version is treated as a valid plugin
• This enables: git clone, git submodule, symlinks, and package-manager-installed plugins

Files

• vendor/wheels/Plugins.cfc:128-144 — modify $pluginDelete() to skip valid plugin directories
• vendor/wheels/Plugins.cfc:146-178 — modify $pluginsProcess() to discover directory-based plugins

Phase

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

[bpamiri]

Analysis

Synopsis

Allow plugins to exist as plain directories (git clone, symlink, manual install) without a matching .zip file. Currently, $pluginDelete() (line 128-144) actively destroys any plugin directory lacking a corresponding zip, and $pluginsProcess() only discovers plugins via $pluginFolders() which itself depends on the zip-extraction workflow.

Merit Assessment

Recommendation: Proceed

• This is a significant developer experience improvement — the current zip-only model forces awkward workflows for plugin development, git submodules, and package manager integration.
• The destructive behavior (DirectoryDelete at line 141) is a real footgun — developers who manually place a plugin directory lose it silently on reload.
• Enables modern workflows: git clone, git submodule, npm/ForgeBox install into plugins/, symlinked local development.
• Fully backward-compatible — zip-based plugins continue working unchanged.

Implementation Plan

1. Modify $pluginDelete() in vendor/wheels/Plugins.cfc:128-144:

   • Before deleting a directory, check if it contains a valid plugin indicator:
     • A plugin.json file (ties into Add plugin.json manifest support alongside box.json #1976), OR
     • A .cfc file matching the directory name with an init() method that returns this.version
   • If either condition is true, skip deletion — the directory is an intentionally-placed plugin.
   • Only delete directories that are true orphans (extracted from a zip that no longer exists, with no validity markers).

2. Modify $pluginFolders() in vendor/wheels/Plugins.cfc:40-89:

   • This method already discovers all subdirectories and their CFCs — it does not filter by zip presence. So directory-based plugins are already discovered by $pluginFolders() and processed by $pluginsProcess().
   • The only gate is $pluginDelete() removing them first. So the primary fix is in step 1.

3. Verify the $pluginsExtract() → $pluginDelete() → $pluginsProcess() sequence (lines 24-30):

   • $pluginsExtract() only operates on zip files — no change needed.
   • $pluginDelete() runs next and currently destroys directory-only plugins — this is the bug to fix.
   • $pluginsProcess() calls $pluginFolders() which already enumerates all directories — no change needed.

4. Add/update tests:

   • Modify the "Tests that removing" describe block in vendor/wheels/tests/specs/pluginsSpec.cfc:133-168.
   • Add a test that places a directory with a valid plugin CFC (no matching zip) and verifies it survives $pluginDelete().
   • Add a test that places a directory with a plugin.json and verifies it survives.
   • Keep the existing test that verifies truly orphaned directories are still cleaned up.

5. Update the deletePluginDirectories setting documentation in vendor/wheels/public/views/info.cfm to reflect the new behavior.

6. Estimated complexity: Low — the main change is ~10-15 lines of guard logic in $pluginDelete(). The discovery path already works.

Dependencies & Risks

• Synergizes with Add plugin.json manifest support alongside box.json #1976 — plugin.json provides the cleanest validity marker for directory-based plugins. Without Add plugin.json manifest support alongside box.json #1976, the fallback (CFC with init() returning this.version) still works but is less explicit.
• The deletePluginDirectories=true default (set in vendor/wheels/events/init/orm.cfm:32) means this destructive behavior affects all users who haven't opted out. Fixing this has broad positive impact.
• Breaking change risk: Technically, users who relied on the cleanup behavior to auto-remove stale directories might see leftover directories if those directories happen to contain a valid CFC. This is an acceptable tradeoff — the old behavior was more harmful (deleting intentional plugins) than the new edge case (keeping stale-but-valid directories).
• Consider adding a directoryPlugin=true marker to pluginMeta so the debug panel can distinguish zip-extracted vs. directory-based plugins.

---

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