# Python Plug-in Auto-Registration Sample

This sample demonstrates the v2 `pluginSettings.json` flow for Python plug-ins.

## Deployment Paths

- Windows plug-in script folder:
  `C:/Users/Public/Documents/CLO/Plugins`
- Windows plug-in settings file:
  `C:/Users/Public/Documents/CLO/Plugins/pluginSettings.json`
- macOS plug-in script folder:
  `$HOME/Documents/CLO/Plugins`
- macOS plug-in settings file:
  `$HOME/Documents/CLO/Plugins/pluginSettings.json`

## What v1 Does

- CLO does not auto-execute Python files at startup.
- CLO reads `pluginSettings.json` at startup and on `Refresh Plug-in`.
- A script entry becomes a normal plug-in QAction under the configured menu path.
- A folder entry creates or reuses the parent menu path from `m_BaseMenuTreeByObjectName`, then creates one submenu named from `m_PlugInTitle` or the folder basename and registers every direct child `.py` file in that submenu.
- Clicking the menu item reuses the existing `.py` execution path in `DialogPlugInManager::OnPlugInAction()`.
- `Configuration/API_Plug_in` is legacy and is no longer used for plug-in persistence or discovery.

## Sample Files

- `sample.py`
  sample script for test.
- `pluginSettings.sample.json`
  Example source-of-truth settings file. Copy it to the runtime `pluginSettings.json` path and adjust the script path if needed.

## Example Setup

1. Copy `sample.py` to `C:/Users/Public/Documents/CLO/Plugins/sample.py`.
2. Copy `pluginSettings.sample.json` to `C:/Users/Public/Documents/CLO/Plugins/pluginSettings.json`.
3. Start CLO or use `Refresh Plug-in`.
4. Open the configured menu path and run the registered Python action.

## JSON Schema

Each entry in `plugins[]` stores either:

- a script source
  - `m_SourceType = "script"`
  - `m_SourcePath`
  - `m_PlugInTitle`
  - `m_PlugInFileName`
  - `m_BaseMenuTreeByObjectName`
  - `m_AddingPositionIndex`
- or a folder source
  - `m_SourceType = "folder"`
  - `m_SourcePath`
  - `m_PlugInTitle`
  - `m_BaseMenuTreeByObjectName`
  - `m_AddingPositionIndex`

`m_BaseMenuTreeByObjectName` is now interpreted as a visible menu text path such as `Plugins / Test`.
Both `Plugins/Test` and `Plugins / Test` are accepted and saved back in normalized `Plugins / Test` form.
Missing trailing submenu segments are created automatically under the nearest existing parent menu.
Legacy entries that still contain Qt `objectName` paths are converted at load time and resaved as visible text paths.

`m_AddingPositionIndex` is an absolute insertion index within the target menu.
`0` inserts at the top, and any value greater than the current action count inserts at the bottom.

## Persistence And Discovery

- `pluginSettings.json` under `CLO/Plugins` is the only source of truth for persisted plug-in actions.
- If `pluginSettings.json` is missing, CLO starts with no persisted plug-in actions until the file is created or items are added through the UI.
- If `pluginSettings.json` exists but cannot be parsed, CLO logs the error to `api_plugin_log.txt` and skips persistent plug-in restoration.
- Folder registrations are rescanned on every startup and `Refresh Plug-in`, so newly added or removed direct child `.py` files are reflected automatically.
- DLL discovery still scans the main `CLO/Plugins` folder and any additional folders listed in `CLO/Plugins/defaultPlugInFolders.txt`.
