plugin_manager.php

<?php
/**
 * Roundcube Plugin Manager
 */

class plugin_manager extends rcube_plugin
{
    const PLUGIN_VERSION = '1.6.0';
    const PLUGIN_INFO = array(
        'name' => 'plugin_manager',
        'vendor' => 'Gene Hawkins / texxasrulez',
        'version' => self::PLUGIN_VERSION,
        'license' => 'AGPL-3.0',
        'uri' => 'https://github.com/texxasrulez/plugin_manager',
    );

    protected $home;

    private $installed_versions_file;
    private $data_dir;
    private $central_version_file;
    private $maintenance_audit_file;

    private $remote_checks = true;
    public $task = 'settings';

    /** @var rcube */
    private $rc;
    /** @var rcube_config */
    private $config;

    private $cache_file;
    private $cache_ttl;

    private $plugin_root;
    private $timeout;
    private $debug = false;
    private $force_check = '';
    private $diag = false;
    private $last_reason = '';
    private $last_via = '';
    private $last_ts = 0;
    private $gh_token = '';
    private $hidden_plugins = array();
    private $visibility = 'mixed';
    private $last_post_update_advisory = null;
    private $post_update_hooks = array();
    private $maintenance_audit_enabled = true;
    private $maintenance_audit_limit = 100;

    public static function info(): array
    {
        return self::PLUGIN_INFO;
    }

    private function pm_web_path($path = '')
    {
        $base = '';

        if (!empty($this->urlbase) && is_string($this->urlbase)) {
            $base = $this->urlbase;
        } else {
            $base = 'plugins/' . self::PLUGIN_INFO['name'];
        }

        $base = rtrim($base, '/');
        $path = ltrim((string) $path, '/');

        return $path === '' ? $base : ($base . '/' . $path);
    }

    private function pm_inline_script($file)
    {
        $path = __DIR__ . DIRECTORY_SEPARATOR . ltrim($file, DIRECTORY_SEPARATOR);
        if (!is_readable($path) || !$this->rc || !$this->rc->output) {
            return;
        }

        $js = @file_get_contents($path);
        if (!is_string($js) || $js === '') {
            return;
        }

        $this->rc->output->add_header("<script>\n" . $js . "\n</script>");
    }

    private function pm_inline_style($file)
    {
        $path = __DIR__ . DIRECTORY_SEPARATOR . ltrim($file, DIRECTORY_SEPARATOR);
        if (!is_readable($path) || !$this->rc || !$this->rc->output) {
            return;
        }

        $css = @file_get_contents($path);
        if (!is_string($css) || $css === '') {
            return;
        }

        $this->rc->output->add_header("<style>\n" . $css . "\n</style>");
    }

    private function pm_normalize_ace_theme_name($theme)
    {
        $theme = trim((string) $theme);
        if ($theme === '' || $theme === 'auto') {
            return '';
        }

        if (strpos($theme, 'ace/theme/') === 0) {
            $theme = substr($theme, strlen('ace/theme/'));
        }

        return preg_replace('/[^a-zA-Z0-9_]+/', '_', $theme);
    }

    private function pm_inline_ace_assets()
    {
        $themes = array('github', 'dracula');
        $cfg = $this->rc ? $this->rc->config : null;

        if ($cfg) {
            foreach (array(
                $cfg->get('pm_ace_theme', 'auto'),
                $cfg->get('pm_ace_light_theme', 'github'),
                $cfg->get('pm_ace_dark_theme', 'dracula'),
            ) as $theme) {
                $name = $this->pm_normalize_ace_theme_name($theme);
                if ($name !== '') {
                    $themes[] = $name;
                }
            }
        }

        $themes = array_values(array_unique($themes));

        $this->pm_inline_style('assets/pm-ace.css');
        $this->pm_inline_script('assets/ace/ace.js');
        $this->pm_inline_script('assets/ace/mode-php.js');
        $this->pm_inline_script('assets/ace/worker-php.js');
        foreach ($themes as $theme) {
            $file = 'assets/ace/theme-' . $theme . '.js';
            $path = __DIR__ . DIRECTORY_SEPARATOR . str_replace('/', DIRECTORY_SEPARATOR, $file);
            if (is_readable($path)) {
                $this->pm_inline_script($file);
            }
        }
    }

    private function flash_add($message, $type = 'notice')
    {
        $file = $this->cache_file . '.flash';
        $list = array();
        if (is_readable($file)) {
            $j = json_decode(@file_get_contents($file), true);
            if (is_array($j)) $list = $j;
        }
        $list[] = array('m' => (string)$message, 't' => (string)$type);
        @file_put_contents($file, json_encode($list));
    }

    private function flash_flush()
    {
        $file = $this->cache_file . '.flash';
        if (!is_readable($file)) return;
        $j = json_decode(@file_get_contents($file), true);
        @unlink($file);
        if (is_array($j)) {
            foreach ($j as $it) {
                $m = isset($it['m']) ? (string)$it['m'] : '';
                $t = isset($it['t']) ? (string)$it['t'] : 'notice';
                if ($m !== '') $this->rc->output->show_message($m, $t);
            }
        }
    }

    function init()
    {
        $this->rc = rcube::get_instance();
        $this->pm_data_init();

        if (isset($_GET['_pm_versions'])) {
            header('Content-Type: application/json; charset=UTF-8');
            echo @file_get_contents($this->central_version_file);
            exit;
        }

        $this->pm_load_config();
        $this->pm_bootstrap_version_data();
        if ($this->cfg_true('pm_write_central_on_init', true) && method_exists($this, 'pm_write_central_versions')) {
            $this->pm_write_central_versions();
        }

        if ($this->rc && $this->rc->output) {
            $this->rc->output->set_env('pm_plugin_base', $this->pm_web_path());
            $this->rc->output->set_env('pm_asset_base', $this->pm_web_path('assets'));
            if (!isset($this->rc->output->env['pm_ace_base'])) {
                $this->rc->output->set_env('pm_ace_base', $this->pm_web_path('assets/ace'));
            }
            $cfg = $this->rc->config;
            $this->rc->output->set_env('pm_ace_theme',       $cfg->get('pm_ace_theme', 'auto'));
            $this->rc->output->set_env('pm_ace_light_theme', $cfg->get('pm_ace_light_theme', 'github'));
            $this->rc->output->set_env('pm_ace_dark_theme',  $cfg->get('pm_ace_dark_theme', 'dracula'));
        }

        $this->register_action('plugin.plugin_manager', array($this, 'action_list'));
        $this->register_action('plugin_manager.refresh', array($this, 'action_refresh'));
        $this->register_action('plugin.plugin_manager.update', array($this, 'action_update'));
        $this->register_action('plugin.plugin_manager.restore', array($this, 'action_restore'));
        $this->register_action('plugin.plugin_manager.delete_backups', array($this, 'action_delete_backups'));
        $this->register_action('plugin.plugin_manager.run_maintenance', array($this, 'action_run_maintenance'));
        $this->register_action('plugin.plugin_manager.load_config', array($this, 'action_load_config'));
        $this->register_action('plugin.plugin_manager.save_config', array($this, 'action_save_config'));

        $this->add_texts('localization/');
        if ($this->rc->task === 'settings' && $this->rc->action === 'plugin.plugin_manager') {
            $this->pm_inline_ace_assets();
            $this->pm_inline_script('plugin_manager.ui.js');
            $this->register_handler('plugin.body', array($this, 'render_page'));
        }

        if ($this->rc->task === 'settings') {
            $this->include_stylesheet($this->local_skin_path() . '/plugin_manager.css');
        }

        $this->add_hook('settings_actions', array($this, 'settings_actions'));
    }

    private function pm_load_config()
    {
        parent::load_config('config.inc.php.dist');
        parent::load_config('config.inc.php');

        $this->config        = $this->rc->config;
        $tempdir             = $this->config->get('temp_dir', sys_get_temp_dir());
        $this->cache_file    = rtrim($tempdir, DIRECTORY_SEPARATOR) . DIRECTORY_SEPARATOR . 'pm_cache.json';
        $this->cache_ttl     = (int)$this->config->get('pm_cache_ttl', 43200);
        $this->plugin_root   = $this->config->get('pm_plugin_root');
        $this->timeout       = (int)$this->config->get('pm_request_timeout', 7);
        $this->remote_checks = (bool)$this->config->get('pm_remote_checks', true);
        $this->force_check   = isset($_GET['_pm_check']) ? (string)$_GET['_pm_check'] : '';
        $this->debug         = (bool)$this->config->get('pm_debug', false) || isset($_GET['_pm_debug']);
        $this->diag          = isset($_GET['_pm_diag']);
        $this->gh_token      = (string)$this->config->get('pm_github_token', '');
        $this->visibility    = (string)$this->config->get('pm_visibility', 'mixed');
        $hooks = $this->config->get('pm_post_update_hooks', array());
        $this->post_update_hooks = is_array($hooks) ? $hooks : array();
        $this->maintenance_audit_enabled = (bool) $this->config->get('pm_maintenance_audit_enabled', true);
        $this->maintenance_audit_limit = max(1, (int) $this->config->get('pm_maintenance_audit_limit', 100));

        $this->hidden_plugins = array();
        $hp = $this->config->get('pm_hidden_plugins', array());
        if (!is_array($hp)) { $hp = array($hp); }
        foreach ($hp as $h) { if (is_string($h) && $h!=='') { $this->hidden_plugins[] = strtolower($h); } }
        $this->pm_data_init();
        $flag = $this->data_dir . DIRECTORY_SEPARATOR . 'remote.off';
        $req_remote = rcube_utils::get_input_value('_pm_remote', rcube_utils::INPUT_GPC);
        if ($req_remote !== null && $req_remote !== '') {
            if (!$this->is_update_admin() || !$this->request_token_valid()) {
                $this->flash_add($this->gettext('not_authorized'), 'error');
            } else {
                if ((string)$req_remote === '0' || $req_remote === 0) {
                    @file_put_contents($flag, '1');
                } else {
                    if (file_exists($flag)) { @unlink($flag); }
                }
            }
        }
        if (file_exists($flag)) {
            $this->remote_checks = false;
        }
    

        $this->log_debug('pm_load_config done', array(
            'cache_file'    => $this->cache_file,
            'remote_checks' => $this->remote_checks,
            'plugin_root'   => $this->plugin_root
        ));
    }

    private function log_debug($msg, $context = array())
    {
        if (!$this->debug) return;
        $entry = '[' . date('c') . '] ' . $msg;
        if (!empty($context)) $entry .= ' ' . json_encode($context);
        rcube::write_log('plugin.plugin_manager', $entry);
    }

    function settings_actions($args)
    {
        if (!$this->can_view()) return $args;

        $args['actions'][] = array(
            'command' => 'plugin.plugin_manager',
            'action'  => 'plugin.plugin_manager',
            'type'    => 'link',
            'label'   => 'plugin_manager.plugin_manager_title',
            'title'   => 'plugin_manager.plugin_manager_title',
            'class'   => 'plugin_manager',
        );
        return $args;
    }

    function action_refresh()
    {
        @unlink($this->cache_file);
        $this->rc->output->redirect(array('_task'=>'settings','_action'=>'plugin.plugin_manager'));
    }

    function action_list()
    {
        if ($this->cfg_true('pm_enable_update_select', true) && $this->is_update_admin()) {
            $pm_all = rcube_utils::get_input_value('_pm_update_all', rcube_utils::INPUT_GPC);
            $pm_dry = rcube_utils::get_input_value('_pm_dry', rcube_utils::INPUT_GPC) ? true : false;
            $pm_selected = rcube_utils::get_input_value('_pm_selected', rcube_utils::INPUT_GPC);
            $selected = $this->sanitize_selected_plugins($pm_selected);
            $this->log_debug('bulk_handler', array('where'=>'action_list', 'pm_all'=>$pm_all, 'pm_dry'=>$pm_dry, 'selected'=>$selected));
            if ($pm_all) {
                if (!$this->request_token_valid()) {
                    $this->flash_add($this->gettext('not_authorized'), 'error');
                    $this->rc->output->redirect(array('_task'=>'settings','_action'=>'plugin.plugin_manager'));
                    return;
                }
                if ($pm_selected !== null && empty($selected)) {
                    $this->flash_add($this->gettext('no_plugins_selected') ?: 'No plugins selected.', 'warning');
                    $this->rc->output->redirect(array('_task'=>'settings','_action'=>'plugin.plugin_manager'));
                    return;
                }
                $res = $this->update_all_outdated($pm_dry, $selected);
                $summary = $pm_dry
                    ? sprintf(rcube::Q($this->gettext('testing_complete')) . ': %d would update, %d would fail, %d skipped.', (int)$res['ok'], (int)$res['fail'], (int)count($res['skipped']))
                    : sprintf(rcube::Q($this->gettext('bulk_update_complete')) . ': %d updated, %d failed, %d skipped.', (int)$res['ok'], (int)$res['fail'], (int)count($res['skipped']));
                $this->flash_add($summary, $pm_dry ? 'notice' : ($res['fail'] ? 'warning' : 'confirmation'));
                if (!empty($res['skipped'])) {
                    $detail = rcube::Q($this->gettext('details')) . ': ' . $this->format_skip_reasons($res['skipped']);
                    $this->flash_add($detail, 'notice');
                }
                if (!$pm_dry && !empty($res['advisories'])) {
                    foreach ($res['advisories'] as $advisory) {
                        $this->flash_post_update_advisory($advisory);
                    }
                }
                if (!$pm_dry && !empty($res['hooks'])) {
                    foreach ($res['hooks'] as $hook_result) {
                        $this->flash_post_update_hook_result($hook_result, isset($hook_result['plugin']) ? (string) $hook_result['plugin'] : '');
                    }
                }
                $this->rc->output->redirect(array('_task'=>'settings','_action'=>'plugin.plugin_manager'));
                return;
            }
        }

        $this->rc->output->set_pagetitle($this->gettext('plugin_manager_title'));
        $this->rc->output->send('plugin');
    }

    function render_page()
    {
        $this->flash_flush();
        $this->log_debug('render_page start');

        $token = (string)$this->rc->get_request_token();
        $pm_refresh = rcube_utils::get_input_value('_pm_refresh', rcube_utils::INPUT_GPC);
        if ($pm_refresh) {
            if (!$this->is_update_admin() || !$this->request_token_valid()) {
                $this->flash_add($this->gettext('not_authorized'), 'error');
            } else {
                if (!empty($this->cache_file) && file_exists($this->cache_file)) {
                    @unlink($this->cache_file);
                }
                $plugins_for_refresh = $this->discover_plugins();
                foreach ($plugins_for_refresh as $pfr) {
                    $meta_fr    = $this->read_plugin_meta($pfr['dir']);
                    $sources_fr = $this->build_sources($meta_fr);
                    if (!empty($sources_fr['composer_name']) || !empty($sources_fr['github'])) {
                        $this->latest_version_cached($sources_fr, true);
                    }
                }
                $this->last_ts = time();
            }
        }

        $this->include_stylesheet($this->local_skin_path() . '/plugin_manager.css');
        $cw = (array)$this->config->get('pm_column_widths', array('select'=>'3%','plugin'=>'20%','directory'=>'15%','enable_disable'=>'10%','latest'=>'8%','local'=>'8%','status'=>'18%','website'=>'18%'));
        $select_w  = isset($cw['select']) ? $cw['select'] : '3%';
        $plugin_w  = isset($cw['plugin'])  ? $cw['plugin']  : '20%';
        $directory_w  = isset($cw['directory'])  ? $cw['directory']  : '15%';
        $enable_disable_w  = isset($cw['enable_disable'])  ? $cw['enable_disable']  : '10%';
        $local_w  = isset($cw['local'])  ? $cw['local']  : '8%';
        $latest_w = isset($cw['latest']) ? $cw['latest'] : '8%';
        $status_w = isset($cw['status']) ? $cw['status'] : '18%';
        $website_w = isset($cw['website']) ? $cw['website'] : '18%';

        $this->rc->output->add_header('<style>
            #pm-table { table-layout:auto; }
            #pm-table td:nth-child(1), #pm-table th:nth-child(1) { width: ' . rcube::Q($select_w) . '; }
            #pm-table td:nth-child(5), #pm-table th:nth-child(2) { width: ' . rcube::Q($plugin_w) . '; }
            #pm-table td:nth-child(5), #pm-table th:nth-child(3) { width: ' . rcube::Q($directory_w) . '; }
            #pm-table td:nth-child(5), #pm-table th:nth-child(4) { width: ' . rcube::Q($enable_disable_w) . '; }
            #pm-table td:nth-child(5), #pm-table th:nth-child(5) { width: ' . rcube::Q($local_w) . '; }
            #pm-table td:nth-child(6), #pm-table th:nth-child(6) { width: ' . rcube::Q($latest_w) . '; }
            #pm-table td:nth-child(7), #pm-table th:nth-child(7) { width: ' . rcube::Q($status_w) . '; }
            #pm-table td:nth-child(7), #pm-table th:nth-child(8) { width: ' . rcube::Q($website_w) . '; }
            th.pm-sort{cursor:pointer;user-select:none;}
            th.pm-sort.pm-sorted-asc::after{content:" \\25B2";}
            th.pm-sort.pm-sorted-desc::after{content:" \\25BC";}
            .pm-diag-card{margin:10px 0 14px;padding:12px 14px;border:1px solid #d7dce2;border-radius:8px;background:#fbfcfd;text-align:left;}
            .pm-diag-card-head{display:flex;align-items:center;justify-content:space-between;gap:10px;margin-bottom:10px;}
            .pm-diag-card-head h3{margin:0;font-size:14px;line-height:1.2;}
            .pm-diag-pill{display:inline-block;padding:3px 8px;border-radius:999px;background:#eef3f8;color:#425466;font-size:11px;font-weight:600;white-space:nowrap;}
            .pm-diag-grid{display:grid;grid-template-columns:repeat(auto-fit,minmax(280px,1fr));gap:12px;}
            .pm-diag-section{padding:10px 12px;border:1px solid #e5e9ef;border-radius:6px;background:#fff;}
            .pm-diag-section-title{margin:0 0 8px 0;font-size:12px;font-weight:700;color:#5b6773;text-transform:uppercase;letter-spacing:.04em;}
            .pm-diag-item{display:grid;grid-template-columns:140px minmax(0,1fr);gap:10px;padding:3px 0;align-items:start;}
            .pm-diag-label{font-weight:600;color:#44505c;}
            .pm-diag-value{color:#1f2933;word-break:break-word;}
            .pm-diag-probes{display:grid;grid-template-columns:repeat(auto-fit,minmax(280px,1fr));gap:12px;margin-top:12px;}
            .pm-diag-probe-card{padding:10px 12px;border:1px solid #e5e9ef;border-radius:6px;background:#fff;}
            .pm-diag-probe-head{display:flex;align-items:center;justify-content:space-between;gap:10px;margin-bottom:6px;}
            .pm-diag-url,.pm-diag-meta{font-size:12px;line-height:1.4;word-break:break-word;color:#52606d;}
            .pm-diag-ok,.pm-diag-fail{display:inline-block;padding:2px 8px;border-radius:999px;font-size:11px;font-weight:700;}
            .pm-diag-ok{background:#e6f6ec;color:#18794e;}
            .pm-diag-fail{background:#fdecec;color:#b42318;}
            .pm-bulkbar .pm-delete-selected-backups{border-color:#b42318;background:#fef3f2;color:#8a1c12;}
            .pm-bulkbar .pm-delete-selected-backups:hover,
            .pm-bulkbar .pm-delete-selected-backups:focus{background:#fde2e0;color:#75160f;}
            .pm-bulkbar .button[disabled]{opacity:.55;cursor:not-allowed;}
            .pm-maintenance-link{font-weight:600;color:#0b5cad;}
            .pm-maintenance-badge{display:inline-block;margin-left:6px;padding:1px 6px;border-radius:999px;font-size:10px;font-weight:700;vertical-align:middle;}
            .pm-maintenance-none{display:none;}
            .pm-maintenance-advisory{background:#fff7e6;color:#9a6700;}
            .pm-maintenance-available{background:#eef5ff;color:#0b5cad;}
            .pm-maintenance-blocked{background:#fdecec;color:#b42318;}
            .pm-maintenance-ran_recently{background:#e6f6ec;color:#18794e;}
            .pm-maint-activity{margin:12px 0 14px;padding:10px 12px;border:1px solid #d7dce2;border-radius:8px;background:#fbfcfd;}
            .pm-maint-activity h3{margin:0 0 8px 0;font-size:13px;}
            .pm-maint-activity table{width:100%;border-collapse:collapse;font-size:12px;}
            .pm-maint-activity th,.pm-maint-activity td{padding:6px 8px;text-align:left;border-top:1px solid #e5e9ef;vertical-align:top;}
            .pm-maint-activity th{font-weight:700;color:#5b6773;border-top:none;}
            .pm-maint-result{display:inline-block;padding:2px 7px;border-radius:999px;font-size:11px;font-weight:700;text-transform:capitalize;}
            .pm-maint-result-success{background:#e6f6ec;color:#18794e;}
            .pm-maint-result-warning{background:#fff7e6;color:#9a6700;}
            .pm-maint-result-failure,.pm-maint-result-refused{background:#fdecec;color:#b42318;}
            .pm-maint-result-skipped{background:#eef3f8;color:#425466;}
            .pm-maint-activity-toggle{margin:12px 0 8px;display:flex;justify-content:flex-end;}
            .pm-maint-activity-toggle label{display:inline-flex;align-items:center;gap:6px;font-size:12px;color:#425466;}
        </style>');

        $plugins = $this->discover_plugins();
        $enabled = $this->enabled_plugins();

        $rows = array();
        foreach ($plugins as $info) {
            $dir  = $info['dir'];
            $meta = $this->read_plugin_meta($dir);

            $base   = basename($dir);
            $policy = $this->policy_for($base);
            if ($policy['ignored']['ui']) continue;

            $local_version = $this->detect_local_version($dir, $meta);
            $sources       = $this->build_sources($meta);

            $remote     = array('version' => $this->gettext('unknown'), 'status' => $this->gettext('not_checked'), 'reason' => '');
            $checked_ts = 0;

            if (!empty($sources['bundled'])) {
                $remote['version'] = '—';
                $remote['status']  = $this->gettext('bundled');
                $remote['reason']  = 'bundled';
            } elseif ($this->remote_checks && !$policy['ignored']['discover']) {
                $remote_ver = $this->latest_version_cached($sources);
                if ($remote_ver) {
                    $checked_ts        = $this->last_ts ?: 0;
                    $remote['version'] = $remote_ver;
                    $cmp               = $this->compare_versions($local_version, $remote_ver);
                    $remote['status']  = ($cmp >= 0) ? $this->gettext('up_to_date') : $this->gettext('update_available');
                }
            }

            $enabled_bool = in_array(basename($dir), $enabled, true);

            $rows[] = array(
                'name'       => $info['name'],
                'dir'        => basename($dir),
                'enabled'    => $enabled_bool,
                'local'      => $local_version ?: $this->gettext('unknown'),
                'remote'     => $remote['version'],
                'status'     => $remote['status'],
                'reason'     => isset($remote['reason']) ? $remote['reason'] : '',
                'via'        => isset($remote['via']) ? $remote['via'] : '',
                'links'      => $sources,
                'checked_ts' => $checked_ts,
                'policy'     => $policy,
                'policy_reason' => isset($policy['reason']) ? $policy['reason'] : '',
            );
        }

        if (empty($this->last_ts)) {
            $this->last_ts = $this->pm_cache_last_ts();
        }

        $h = array();
        $h[] = '<div class="box">';
        $h[] = '<div class="boxtitle">' . rcube::Q($this->gettext('plugin_manager_title')) . '</div>';
        $h[] = '<div class="boxcontent">';
        $h[] = '<p class="pm-desc" style="text-align:left;">' . rcube::Q($this->gettext('plugin_manager_desc')) . '</p>';
        if ($this->debug) {
            $h[] = '<div class="pm-debug remote-off">'
                . rcube::Q($this->gettext('debug_on')) . '. '
                . rcube::Q($this->gettext('debug_on_text')) . '</div>';
        }
        if ($this->diag) {
            $h[] = $this->pm_render_diagnostics();
        }

        // top controls
        $h[] = '<div style="margin:8px 0;">';
        $rc_info = $this->roundcube_version_info();
        $rc_local_text = rcube::Q($rc_info['local'] ?: $this->gettext('unknown'));
        $rc_remote_text = $rc_info['remote'] ? rcube::Q($rc_info['remote']) : ($this->remote_checks ? rcube::Q($this->gettext('unknown')) : rcube::Q($this->gettext('remote_disabled')));
        $rc_status = '';
        if ($rc_info['remote']) {
            $cmp_rc = $this->compare_versions($rc_info['local'], $rc_info['remote']);
            if ($cmp_rc < 0) {
                $rc_status = '<span class="pm-update">' . rcube::Q($this->gettext('update_available')) . '</span>';
            } else {
                $rc_status = '<span class="pm-ok">' . rcube::Q($this->gettext('up_to_date')) . '</span>';
            }
        }
        $rc_download_url = rcube::Q($rc_info['download']);
        $show_download = true;
        if ($rc_info['remote'] && $rc_info['local'] && $this->compare_versions($rc_info['local'], $rc_info['remote']) >= 0) {
            $show_download = false;
        }
        $download_html = $show_download
            ? ' &middot; <a class="pm-rc-download" target="_blank" rel="noreferrer" href="' . $rc_download_url . '">' . rcube::Q($this->gettext('dnload_update') ?: 'Download Roundcube') . '</a>'
            : '';
        $h[] = '<div class="pm-rcinfo" style="float:right;text-align:right;margin-right:10px;margin-top:-30px;">'
            . '<span class="pm-rc-label">Roundcube: <strong>' . $rc_local_text . '</strong></span>'
            . ' &middot; '
            . '<span class="pm-rc-remote">' . ($rc_info['remote'] ? rcube::Q($this->gettext('version_remote')) . ': ' . $rc_remote_text : rcube::Q($this->gettext('remote_disabled'))) . '</span>'
            . ($rc_status ? ' &middot; ' . $rc_status : '')
            . $download_html
            . '</div>';
        $h[] = '<a class="button pm-reload" href="' . $this->rc->url(array('_task'=>'settings','_action'=>'plugin.plugin_manager')) . '">' . rcube::Q($this->gettext('reload_page')) . '</a> ';
        $h[] = '<a class="button pm-diagnostics" href="' . $this->rc->url(array('_task'=>'settings','_action'=>'plugin.plugin_manager','_pm_diag'=>1,'_token'=>$token)) . '">' . rcube::Q($this->gettext('diagnostics')) . '</a> ';
        $toggle_label = $this->remote_checks ? $this->gettext('disable_remote') : $this->gettext('enable_remote');
        $h[] = '<a class="button pm-toggle-remote" href="' . $this->rc->url(array('_task'=>'settings','_action'=>'plugin.plugin_manager','_pm_remote'=>($this->remote_checks?0:1),'_token'=>$token)) . '">' . rcube::Q($toggle_label) . '</a>';
        $h[] = ' <a class="button pm-refresh" href="' . $this->rc->url(array('_task'=>'settings','_action'=>'plugin.plugin_manager','_pm_refresh'=>1,'_token'=>$token)) . '">' . rcube::Q($this->gettext('refresh_versions')) . '</a>';
        $h[] = '&nbsp;&nbsp;<span class="pm-lastupdate" style="margin:6px 0 4px 0;">' . rcube::Q($this->gettext('last_checked')) . ':&nbsp;' . ( $this->last_ts ? '<span class="pm-checked">' . rcube::Q($this->pm_time_ago($this->last_ts)) . '</span>' : '<span class="pm-checked">'. rcube::Q($this->gettext('never')) .'</span>' ) . '</span>';
        $h[] = '</div>';

        // bulk toolbar
        if ($this->cfg_true('pm_enable_update_select', true) && $this->is_update_admin()) {
            $h[] = '<div class="pm-bulkbar" style="margin:10px 0; display:flex; gap:8px; align-items:center; flex-wrap:wrap;">';
            $h[] = '<button class="button pm-update-selected" data-token="' . rcube::Q($token) . '" type="button" disabled>' . rcube::Q($this->gettext('update_selected') ?: 'Update Selected') . '</button>';
            $h[] = '<button class="button pm-delete-selected-backups" data-token="' . rcube::Q($token) . '" type="button" disabled>' . rcube::Q($this->gettext('delete_selected_backups') ?: 'Delete selected backups') . '</button>';
            $h[] = '<label><input type="checkbox" class="pm-only-outdated" /> ' . rcube::Q($this->gettext('only_outdated') ?: 'Only outdated') . '</label>';
            $h[] = '<label><input type="checkbox" class="pm-only-enabled" /> ' . rcube::Q($this->gettext('only_enabled') ?: 'Only enabled') . '</label>';
            $h[] = '<label><input type="checkbox" class="pm-only-errors" /> ' . rcube::Q($this->gettext('only_errors') ?: 'Only errors') . '</label>';
            $h[] = '</div>';
        }

        $audit_html = '';
        if ($this->is_update_admin()) {
            $audit_html = $this->render_maintenance_activity_panel();
        }

        // table
        $h[] = '<div class="pm-scroll">';
        $h[] = '<table class="records-table" id="pm-table">';
        $h[] = '<thead><tr>'
             . '<th class="pm-sort" data-type="text" style="text-align:left;">' . rcube::Q($this->gettext('select')) . '</th>'
             . '<th class="pm-sort" data-type="text" style="text-align:left;">' . rcube::Q($this->gettext('plugin')) . '</th>'
             . '<th class="pm-sort" data-type="text" style="text-align:left;">' . rcube::Q($this->gettext('directory')) . '</th>'
             . '<th class="pm-sort" data-type="bool" style="text-align:left;">' . rcube::Q($this->gettext('enabled')) . ' / ' . rcube::Q($this->gettext('disabled')) .'</th>'
             . '<th class="pm-sort" data-type="semver" style="text-align:left;">' . rcube::Q($this->gettext('version_local')) . '</th>'
             . '<th class="pm-sort" data-type="text" style="text-align:left;">' . rcube::Q($this->gettext('version_remote')) . '</th>'
             . '<th class="pm-sort" data-type="status" style="text-align:left;">' . rcube::Q($this->gettext('status')) . '</th>'
             . '<th class="pm-sort" data-type="text" style="text-align:left;">' . rcube::Q($this->gettext('websites')) . '</th>'
             . '</tr></thead><tbody>';

        foreach ($rows as $r) {
            $dir_name = basename($r['dir']);
            $st       = (string)$r['status'];
            $st_raw   = strtolower($st);
            $st_html  = rcube::Q($st);
            $st_map = array(
                strtolower($this->gettext('update_available')) => 0,
                strtolower($this->gettext('up_to_date'))      => 1,
                strtolower($this->gettext('bundled'))         => 2,
                strtolower($this->gettext('unknown'))         => 3,
            );
            $st_sort = isset($st_map[$st_raw]) ? $st_map[$st_raw] : 9;
            $plugins_root = $this->plugins_root_dir();
            if ($plugins_root) {
                $plugdir = $plugins_root . DIRECTORY_SEPARATOR . $dir_name;
                $baks = $this->find_plugin_backup_dirs($dir_name);
                if (!empty($baks)) {
                    usort($baks, function($a,$b){ return filemtime($b) <=> filemtime($a); });
                    $latest_bak = basename($baks[0]);
                    $restore_url = $this->rc->url(array('_task'=>'settings','_action'=>'plugin.plugin_manager.restore','_pm'=>$dir_name,'_bak'=>$latest_bak,'_token'=>$token));
                    $st_html .= ' <a class="pm-restore-link" href="' . rcube::Q($restore_url) . '">[' . rcube::Q($this->gettext('restore')) . ']</a>';
                }
            }

            $is_outdated = ($st === $this->gettext('update_available') || strpos($st_raw, 'update') !== false);
            $is_up_to_date = ($st === $this->gettext('up_to_date') || strpos($st_raw, 'up to date') !== false);
            $is_bundled = ($st === $this->gettext('bundled') || $st_raw === strtolower($this->gettext('bundled')));
            $has_error = !$is_outdated && !$is_up_to_date && !$is_bundled;

            if ($is_outdated) {
                if ($this->is_update_admin()) {
                    $u    = $this->rc->url(array('_task'=>'settings','_action'=>'plugin.plugin_manager.update','_pm'=>$dir_name,'_token'=>$token));
                    $st_html .= ' <a class="pm-update-link" href="' . rcube::Q($u) . '" data-busy="Updating ...">[' . rcube::Q($this->gettext('update')) . ']</a>';
                }
                if (!empty($r['policy']['pinned'])) {
                    $st_html .= ' <span class="pm-policy-badge pm-badge-pinned">[Pinned ' . rcube::Q($r['policy']['pinned']) . ']</span>';
                }
                $ignored_for = array();
                foreach (array('bulk','notify') as $sc) {
                    if (!empty($r['policy']['ignored'][$sc])) $ignored_for[] = $sc;
                }
                if (!empty($ignored_for)) {
                    $st_html .= ' <span class="pm-policy-badge pm-badge-ignored">[Ignored: ' . rcube::Q(implode(',', $ignored_for)) . ']</span>';
                }
                $st_html = '<strong class="pm-update">' . $st_html . '</strong>';
            } elseif ($is_up_to_date) {
                $st_html = '<strong class="pm-ok">' . $st_html . '&nbsp;&nbsp;&#10003;</strong>';
            }

			$reason = isset($r['reason']) ? (string)$r['reason'] : '';
			$via    = isset($r['via']) ? (string)$r['via'] : '';

			$reason_lc  = strtolower($reason);
			$bundled_lc = strtolower($this->gettext('bundled'));

			// hide redundant "(bundled)" next to "Bundled"
			$show_reason = ($reason !== '') && ($reason_lc !== 'bundled') && ($reason_lc !== $bundled_lc);

			if ($show_reason || $via !== '') {
				$hint = ($show_reason ? $reason : '');
				if ($via !== '') {
					$hint .= ($hint !== '' ? ', ' : '');
					$hint .= ( $this->gettext('via') ?: 'via' ) . ' ' . $via;
				}
				$st_html .= ' <span class="hint">(' . rcube::Q($hint) . ')</span>';
			}

            $links_html = array();
            if (!empty($r['links']['packagist'])) {
                $links_html[] = '<a target="_blank" rel="noreferrer" href="'.rcube::Q($r['links']['packagist']).'">' . rcube::Q($this->gettext('packagist')) . '</a>';
            }
            if (!empty($r['links']['github'])) {
                $links_html[] = '<a target="_blank" rel="noreferrer" href="'.rcube::Q($r['links']['github']).'">' . rcube::Q($this->gettext('github')) . '</a>';
            }

            $maintenance_link = '';
            $badge = $this->get_plugin_maintenance_badge_data($dir_name);
            $maintenance_badge = $badge['state'] !== 'none'
                ? '<span class="pm-maintenance-badge pm-maintenance-' . rcube::Q($badge['state']) . '" title="' . rcube::Q($badge['title']) . '">' . rcube::Q($badge['label']) . '</span>'
                : '';
            if ($this->is_update_admin() && $this->should_show_manual_maintenance_link($dir_name)) {
                $maintenance_url = $this->rc->url(array(
                    '_task' => 'settings',
                    '_action' => 'plugin.plugin_manager.run_maintenance',
                    '_pm' => $dir_name,
                    '_token' => $token,
                ));
                $hook_cfg = $this->get_post_update_hook_config($dir_name);
                $maintenance_label = $this->get_manual_maintenance_label($dir_name, is_array($hook_cfg) ? $hook_cfg : array());
                $maintenance_link = '<a class="pm-maintenance-link" href="' . rcube::Q($maintenance_url) . '" data-confirm="' . rcube::Q($this->gettext('maintenance_confirm') ?: 'Run allowlisted maintenance for this plugin? This may perform plugin-specific post-update tasks.') . '" data-busy="' . rcube::Q($this->gettext('maintenance_running') ?: 'Running maintenance ... ') . '">[' . rcube::Q($maintenance_label) . ']</a>';
            }

            $en_label_yes = rcube::Q($this->gettext('enabled'));
            $en_label_no  = rcube::Q($this->gettext('disabled'));
            $en_html = $r['enabled'] ? '<strong class="pm-enabled">' . $en_label_yes . '</strong>' : '<strong class="pm-disabled">' . $en_label_no . '</strong>';
            $en_sort = $r['enabled'] ? '1' : '0';

            
            $edit_label = $this->gettext('edit_config') ?: 'Edit config';
            // Only show Edit Config when some config file exists in the plugin directory
            $has_cfg = false;
            $cfg_p  = $plugins_root ? ($plugins_root . DIRECTORY_SEPARATOR . $dir_name . DIRECTORY_SEPARATOR . 'config.inc.php') : null;
            $cfg_d  = $plugins_root ? ($plugins_root . DIRECTORY_SEPARATOR . $dir_name . DIRECTORY_SEPARATOR . 'config.inc.php.dist') : null;
            $cfg_s  = $plugins_root ? ($plugins_root . DIRECTORY_SEPARATOR . $dir_name . DIRECTORY_SEPARATOR . 'config.inc.php.sample') : null;
            if (($cfg_p && is_file($cfg_p)) || ($cfg_d && is_file($cfg_d)) || ($cfg_s && is_file($cfg_s))) {
                $edit_link = '<a href="#" class="pm-edit-config" data-plug="'.rcube::Q($dir_name).'">['.rcube::Q($edit_label).']</a>';
            } else {
                $edit_link = '';
            }
				$h[] = '<tr data-outdated="' . ($is_outdated ? '1' : '0') . '" data-enabled="' . ($r['enabled'] ? '1' : '0') . '" data-error="' . ($has_error ? '1' : '0') . '">'
                . '<td style="text-align:center;"><input type="checkbox" class="pm-select" data-dir="' . rcube::Q($dir_name) . '" data-backup-count="' . count($baks) . '"></td>'
                . '<td style="text-align:left;"><strong>' . rcube::Q($r['name']) . '</strong>' . $maintenance_badge . ' &nbsp; ' . $edit_link . ($maintenance_link !== '' ? ' &nbsp; ' . $maintenance_link : '') . '</td>'
                . '<td style="text-align:left;">' . rcube::Q($r['dir']) . '</td>'
                . '<td data-sort="' . $en_sort . '" style="text-align:left;">' . $en_html . '</td>'
                . '<td style="text-align:left;">' . rcube::Q($r['local']) . '</td>'
                . '<td style="text-align:left;">' . rcube::Q($r['remote']) . '</td>'
                . '<td data-sort="' . rcube::Q($st_sort) . '" style="text-align:left;">' . $st_html . '</td>'
                . '<td style="text-align:left;">' . implode(' &middot; ', $links_html) . '</td>'
                . '</tr>';
        }

        $h[] = '</tbody></table>';
        if ($this->is_update_admin() && $audit_html !== '') {
            $h[] = '<div class="pm-maint-activity-toggle"><label><input type="checkbox" class="pm-hide-maint-activity" /> ' . rcube::Q($this->gettext('maintenance_hide_activity') ?: 'Hide recent maintenance activity') . '</label></div>';
            $h[] = $audit_html;
        }
        $h[] = '</div>'; // .pm-scroll
        $h[] = '<script>(function(){var t=document.getElementById("pm-table");if(!t)return;function v(s){if(!s)return[];s=(s+"").trim().replace(/^v/i,"");var m=s.match(/^(\d+)(?:\.(\d+))?(?:\.(\d+))?/);if(!m)return[0,0,0];return[parseInt(m[1]||0,10),parseInt(m[2]||0,10),parseInt(m[3]||0,10)];}function key(td,type){var raw=td.getAttribute("data-sort");if(raw==null)raw=td.textContent||td.innerText||"";raw=(raw+"").trim();if(type==="number"||type==="bool"){var n=parseFloat(raw);if(isNaN(n))n=0;return n;}if(type==="semver"){return v(raw);}if(type==="status"){var l=raw.toLowerCase().replace(/\s+/g,"_");if(/^\d+$/.test(raw))return parseInt(raw,10);var map={"update_available":0,"up_to_date":1,"bundled":2,"unknown":3};return map.hasOwnProperty(l)?map[l]:9;}return raw.toLowerCase();}function cmp(a,b){if(Array.isArray(a)&&Array.isArray(b)){for(var i=0;i<Math.max(a.length,b.length);i++){var av=a[i]||0,bv=b[i]||0;if(av<bv)return-1;if(av>bv)return 1;}return 0;}if(a<b)return-1;if(a>b)return 1;return 0;}function clear(th){var ths=th.parentNode.querySelectorAll("th.pm-sort");for(var i=0;i<ths.length;i++){ths[i].classList.remove("pm-sorted-asc");ths[i].classList.remove("pm-sorted-desc");}}function sortBy(th){var idx=Array.prototype.indexOf.call(th.parentNode.children,th);var type=th.getAttribute("data-type")||"text";var tbody=t.querySelector("tbody");if(!tbody)return;var rows=Array.prototype.slice.call(tbody.querySelectorAll("tr"));var asc=!th.classList.contains("pm-sorted-asc");rows.sort(function(r1,r2){var c1=r1.children[idx],c2=r2.children[idx];var k1=key(c1,type),k2=key(c2,type);return asc?cmp(k1,k2):cmp(k2,k1);});var frag=document.createDocumentFragment();rows.forEach(function(r){frag.appendChild(r);});tbody.appendChild(frag);clear(th);th.classList.add(asc?"pm-sorted-asc":"pm-sorted-desc");}var hs=t.querySelectorAll("th.pm-sort");for(var i=0;i<hs.length;i++){(function(th){th.addEventListener("click",function(){sortBy(th);});})(hs[i]);}})();</script>';


        // Busy text + basic handlers
        $h[] = '<script>(function(){function setBusy(el,txt){if(!el||el.classList.contains("pm-busy"))return;el.dataset.originalText=el.textContent;el.textContent=txt;el.classList.add("pm-busy");el.setAttribute("aria-busy","true");}function syncRowState(cb){var row=cb&&cb.closest?cb.closest("tr"):null;if(row)row.classList.toggle("selected",!!cb.checked);}function getSelectedBoxes(){return Array.prototype.slice.call(document.querySelectorAll(".pm-select:checked")).filter(function(el){return !!(el.getAttribute("data-dir")||"");});}function getSelectedPlugins(){return getSelectedBoxes().map(function(el){return el.getAttribute("data-dir")||"";}).filter(Boolean);}function getSelectedBackupCount(){return getSelectedBoxes().reduce(function(total,el){var count=parseInt(el.getAttribute("data-backup-count")||"0",10);return total+(isNaN(count)?0:count);},0);}function updateBulkButtons(){var count=getSelectedBoxes().length;Array.prototype.slice.call(document.querySelectorAll(".pm-update-selected,.pm-delete-selected-backups")).forEach(function(btn){btn.disabled=count===0;btn.setAttribute("aria-disabled",count===0?"true":"false");});}function applyFilters(){var rows=Array.prototype.slice.call(document.querySelectorAll("#pm-table tbody tr"));var onlyOutdated=document.querySelector(".pm-only-outdated");var onlyEnabled=document.querySelector(".pm-only-enabled");var onlyErrors=document.querySelector(".pm-only-errors");rows.forEach(function(row){var show=true;if(onlyOutdated&&onlyOutdated.checked&&row.getAttribute("data-outdated")!=="1")show=false;if(onlyEnabled&&onlyEnabled.checked&&row.getAttribute("data-enabled")!=="1")show=false;if(onlyErrors&&onlyErrors.checked&&row.getAttribute("data-error")!=="1")show=false;row.style.display=show?"":"none";});}function syncOutdatedSelection(){var onlyOutdated=document.querySelector(".pm-only-outdated");if(!onlyOutdated)return;var boxes=Array.prototype.slice.call(document.querySelectorAll("#pm-table tbody .pm-select"));boxes.forEach(function(box){var row=box.closest("tr");if(!row||row.getAttribute("data-outdated")!=="1")return;if(onlyOutdated.checked){box.checked=true;box.dataset.pmAutoSelected="outdated";}else if(box.dataset.pmAutoSelected==="outdated"){box.checked=false;delete box.dataset.pmAutoSelected;}syncRowState(box);});updateBulkButtons();}function confirmDeleteBackups(selectedCount,backupCount){var msg="'. rcube::Q($this->gettext('delete_backups_confirm') ?: 'Delete backup folders for the selected plugins? This does not delete the live plugins.') .'";var extra=backupCount>0?" ("+backupCount+" backups)":"";if(msg.indexOf("%d")!==-1||msg.indexOf("%s")!==-1){msg=msg.replace("%d",String(selectedCount)).replace("%s",extra);}else if(backupCount>0){msg+=" ("+backupCount+" backups)";}return window.confirm(msg);}function applyMaintenanceActivityVisibility(){var toggle=document.querySelector(".pm-hide-maint-activity");var panel=document.querySelector(".pm-maint-activity");if(!toggle||!panel)return;panel.style.display=toggle.checked?"none":"";}var reload=document.querySelector(".pm-reload");if(reload)reload.addEventListener("click",function(){setBusy(this,this.getAttribute("data-busy")||"'. rcube::Q($this->gettext('reloading') ?: 'Reloading …') .'");});var diag=document.querySelector(".pm-diagnostics");if(diag)diag.addEventListener("click",function(){setBusy(this,this.getAttribute("data-busy")||"'. rcube::Q($this->gettext('running') ?: 'Running …') .'");});var refresh=document.querySelector(".pm-refresh");if(refresh)refresh.addEventListener("click",function(){setBusy(this,this.getAttribute("data-busy")||"'. rcube::Q($this->gettext('checking') ?: 'Checking …') .'");});document.addEventListener("click",function(ev){var a=ev.target.closest(".pm-update-link,.pm-restore-link");if(!a)return;setBusy(a,a.getAttribute("data-busy")||"'. rcube::Q($this->gettext('updating') ?: 'Updating …') .'");});document.addEventListener("click",function(ev){var a=ev.target.closest(".pm-maintenance-link");if(!a)return;var confirmText=a.getAttribute("data-confirm")||"";if(confirmText&&!window.confirm(confirmText)){ev.preventDefault();return;}setBusy(a,a.getAttribute("data-busy")||"'. rcube::Q($this->gettext('maintenance_running') ?: 'Running maintenance ... ') .'");});Array.prototype.slice.call(document.querySelectorAll("#pm-table tbody .pm-select")).forEach(function(box){syncRowState(box);box.addEventListener("change",function(){if(box.dataset.pmAutoSelected&&(!document.querySelector(".pm-only-outdated")||!document.querySelector(".pm-only-outdated").checked||!box.checked)){delete box.dataset.pmAutoSelected;}syncRowState(box);updateBulkButtons();});});Array.prototype.slice.call(document.querySelectorAll(".pm-only-outdated,.pm-only-enabled,.pm-only-errors")).forEach(function(filterBox){filterBox.addEventListener("change",function(){if(filterBox.classList.contains("pm-only-outdated"))syncOutdatedSelection();applyFilters();});});var maintToggle=document.querySelector(".pm-hide-maint-activity");if(maintToggle){var key="pm-hide-maint-activity";try{maintToggle.checked=window.localStorage&&window.localStorage.getItem(key)==="1";}catch(e){}applyMaintenanceActivityVisibility();maintToggle.addEventListener("change",function(){try{if(window.localStorage){window.localStorage.setItem(key,maintToggle.checked?"1":"0");}}catch(e){}applyMaintenanceActivityVisibility();});}syncOutdatedSelection();applyFilters();updateBulkButtons();var bulkBtn=document.querySelector(".pm-update-selected");if(bulkBtn){bulkBtn.addEventListener("click",function(){var selected=getSelectedPlugins();if(!selected.length){alert("'. rcube::Q($this->gettext('no_plugins_selected') ?: 'No plugins selected.') .'");return;}setBusy(this,this.getAttribute("data-busy")||"'. rcube::Q($this->gettext('updating') ?: 'Updating …') .'");var token=this.getAttribute("data-token")||"";var url="?_task=settings&_action=plugin.plugin_manager&_pm_update_all=1&_pm_selected="+encodeURIComponent(selected.join(","));if(token){url+="&_token="+encodeURIComponent(token);}window.location.href=url;});}var deleteBtn=document.querySelector(".pm-delete-selected-backups");if(deleteBtn){deleteBtn.addEventListener("click",function(){var selected=getSelectedPlugins();if(!selected.length){alert("'. rcube::Q($this->gettext('no_plugins_selected') ?: 'No plugins selected.') .'");return;}var backupCount=getSelectedBackupCount();if(!confirmDeleteBackups(selected.length,backupCount)){return;}setBusy(this,this.getAttribute("data-busy")||"'. rcube::Q($this->gettext('deleting_backups') ?: 'Deleting backups ... ') .'");var token=this.getAttribute("data-token")||"";var url="?_task=settings&_action=plugin.plugin_manager.delete_backups&_pm_selected="+encodeURIComponent(selected.join(","));if(token){url+="&_token="+encodeURIComponent(token);}window.location.href=url;});}})();</script>';

        // Column sorting
        $h[] = '<script>(function(){var table=document.getElementById("pm-table");if(!table)return;var thead=table.tHead,tbody=table.tBodies[0];if(!thead||!tbody)return;function txt(el){return(el&&(el.textContent||el.innerText)||"").trim();}function parseSemver(v){v=(v||"").trim();if(!v||v==="—")return{k:[-1]};var vl=v.toLowerCase();if(vl==="unknown"||vl==="unk"||vl==="?")return{k:[-1]};v=v.replace(/^v/i,"");var parts=v.split(/[^0-9a-zA-Z]+/).filter(Boolean);var out=[];for(var i=0;i<parts.length;i++){var p=parts[i];if(/^\d+$/.test(p))out.push(parseInt(p,10));else out.push(-0.5);}return{k:out,raw:v};}function cmpCells(aCell,bCell,type){if(type==="bool"){var av=parseInt(aCell.getAttribute("data-sort")||"0",10);var bv=parseInt(bCell.getAttribute("data-sort")||"0",10);return av-bv;}if(type==="semver"){var sa=parseSemver(txt(aCell)).k,sb=parseSemver(txt(bCell)).k;var n=Math.max(sa.length,sb.length);for(var i=0;i<n;i++){var ai=(i<sa.length)?sa[i]:0,bi=(i<sb.length)?sb[i]:0;if(ai!==bi)return ai-bi;}return 0;}var a=txt(aCell).toLowerCase(),b=txt(bCell).toLowerCase();if(a===b)return 0;return a>b?1:-1;}var headers=thead.rows[0].cells;var state={col:null,dir:"asc"};function clearIndicators(){for(var i=0;i<headers.length;i++){headers[i].classList.remove("pm-sorted-asc","pm-sorted-desc");headers[i].removeAttribute("aria-sort");}}function sortBy(colIndex,type,dir){var rows=Array.prototype.slice.call(tbody.rows);rows.sort(function(r1,r2){var c1=r1.cells[colIndex]||document.createElement("td");var c2=r2.cells[colIndex]||document.createElement("td");var c=cmpCells(c1,c2,type);return dir==="asc"?c:-c;});var frag=document.createDocumentFragment();rows.forEach(function(r){frag.appendChild(r);});tbody.appendChild(frag);clearIndicators();var th=headers[colIndex];th.classList.add(dir==="asc"?"pm-sorted-asc":"pm-sorted-desc");th.setAttribute("aria-sort",dir==="asc"?"ascending":"descending");}for(let i=0;i<headers.length;i++){let th=headers[i];if(!th.classList.contains("pm-sort"))continue;th.addEventListener("click",function(){var type=th.getAttribute("data-type")||"text";if(state.col===i){state.dir=(state.dir==="asc"?"desc":"asc");}else{state.col=i;state.dir="asc";}sortBy(i,type,state.dir);});}})();</script>';

        // Fit table to viewport
        $h[] = '<script>(function(){function footerHeight(){var f=document.querySelector("#footer")||document.querySelector(".footer")||document.querySelector(".taskbar");if(!f)return 32;var r=f.getBoundingClientRect();return Math.max(0,r.height||32);}function fit(){var c=document.querySelector(".pm-scroll");if(!c)return;var vh=window.innerHeight||document.documentElement.clientHeight||0;var rect=c.getBoundingClientRect();var fh=footerHeight();var pad=24;var h=Math.max(220,vh-rect.top-fh-pad);c.style.height=h+"px";c.style.overflow="auto";}if(document.readyState==="loading"){document.addEventListener("DOMContentLoaded",function(){fit();setTimeout(fit,150);setTimeout(fit,500);},{once:true});}else{fit();setTimeout(fit,150);setTimeout(fit,500);}window.addEventListener("resize",fit,{passive:true});})();</script>';

        $h[] = '</div></div>';

        $html = implode("\n", $h);
        $this->log_debug('render_page end', array('html_len' => strlen($html)));
        return $html;
    }

    private function roundcube_version_info()
    {
        $local = null;
        if (defined('RCMAIL_VERSION')) {
            $local = RCMAIL_VERSION;
        } elseif (defined('RCUBE_VERSION')) {
            $local = RCUBE_VERSION;
        }
        if (!$local && $this->rc && $this->rc->config) {
            foreach (array('release', 'release_version', 'version', 'product_version') as $key) {
                $val = $this->rc->config->get($key);
                if ($val) {
                    $local = $val;
                    break;
                }
            }
        }

        $channel = 'stable';
        if ($this->config) {
            $cfg_channel = strtolower((string)$this->config->get('pm_roundcube_release_channel', 'stable'));
            if (in_array($cfg_channel, array('stable','rc'), true)) {
                $channel = $cfg_channel;
            }
        }
        $allow_prerelease = ($channel === 'rc');

        $download = 'https://roundcube.net/download/';
        if ($this->config) {
            $cfg = (string)$this->config->get('pm_roundcube_download_url', '');
            if ($cfg !== '') {
                $download = $cfg;
            }
        }

        $remote = null;
        if ($this->remote_checks) {
            $sources = array(
                'composer_name' => 'roundcube/roundcubemail',
                'github' => 'https://github.com/roundcube/roundcubemail',
                'allow_prerelease' => $allow_prerelease,
            );
            $remote = $this->latest_version_cached($sources);
        }

        if ($remote && strpos($download, '{version}') !== false) {
            $download = str_replace('{version}', rawurlencode($remote), $download);
        }

        return array(
            'local' => $local,
            'remote' => $remote,
            'download' => $download,
        );
    }

    private function enabled_plugins()
    {
        $list = $this->config->get('plugins', array());
        if (!is_array($list)) return array();
        return array_map(function($x){
            return is_array($x) ? ($x['name'] ?? '') : (string)$x;
        }, $list);
    }

    private function plugins_root_dir()
    {
        $candidates = array();
        if (!empty($this->plugin_root) && is_dir($this->plugin_root)) {
            $candidates[] = $this->plugin_root;
        }
        $candidates[] = dirname(__DIR__);
        if (defined('INSTALL_PATH')) {
            $candidates[] = rtrim(INSTALL_PATH, DIRECTORY_SEPARATOR) . DIRECTORY_SEPARATOR . 'plugins';
        }
        if (defined('RCUBE_INSTALL_PATH')) {
            $candidates[] = rtrim(RCUBE_INSTALL_PATH, DIRECTORY_SEPARATOR) . DIRECTORY_SEPARATOR . 'plugins';
        }
        foreach ($candidates as $cand) {
            if ($cand && is_dir($cand)) {
                $real = realpath($cand);
                if ($real) return $real;
            }
        }
        return null;
    }

    private function discover_plugins()
    {
        $root = $this->plugins_root_dir();
        $this->log_debug('discover_plugins root', array('root' => $root));
        $out = array();
        if (!$root) return $out;

        $dh = @opendir($root);
        if (!$dh) return $out;

        while (($entry = readdir($dh)) !== false) {
            if ($entry === '.' || $entry === '..') continue;
            if (stripos($entry, '.bak') !== false) continue;
            $dir = $root . DIRECTORY_SEPARATOR . $entry;
            if (is_dir($dir)) {
                if (!empty($this->hidden_plugins) && in_array(strtolower($entry), $this->hidden_plugins, true)) { continue; }
                $out[$entry] = array('name' => $entry, 'dir' => $dir);
            }
        }
        closedir($dh);
        ksort($out, SORT_NATURAL | SORT_FLAG_CASE);
        return $out;
    }

    private function read_plugin_meta($dir)
    {
        $meta = array('composer' => null, 'mainfile' => null);
        $cj = $dir . DIRECTORY_SEPARATOR . 'composer.json';
        if (is_readable($cj)) {
            $json = json_decode(@file_get_contents($cj), true);
            if (is_array($json)) $meta['composer'] = $json;
        }
        $base = basename($dir);
        $candidates = array(
            $dir . DIRECTORY_SEPARATOR . $base . '.php',
            $dir . DIRECTORY_SEPARATOR . 'plugin.php',
            $dir . DIRECTORY_SEPARATOR . $base . '_plugin.php',
        );
        foreach ($candidates as $mf) {
            if (is_readable($mf)) { $meta['mainfile'] = $mf; break; }
        }

        if (empty($meta['mainfile'])) {
            foreach (glob($dir . DIRECTORY_SEPARATOR . '*.php') ?: array() as $mf) {
                if (!is_readable($mf)) {
                    continue;
                }

                $src = @file_get_contents($mf);
                if (!is_string($src) || $src === '') {
                    continue;
                }

                if (preg_match('/class\s+\w+\s+extends\s+(?:\\\)?rcube_plugin\b/i', $src)) {
                    $meta['mainfile'] = $mf;
                    break;
                }
            }
        }

        return $meta;
    }

    private function detect_local_version($dir, $meta)
    {
        if ($this->is_self_plugin_dir($dir)) {
            return self::PLUGIN_VERSION;
        }

        if (!empty($meta['composer']['version'])) {
            return (string)$meta['composer']['version'];
        }

        if (!empty($meta['mainfile'])) {
            $src = @file_get_contents($meta['mainfile']);
            if ($src !== false) {
                if (preg_match('/const\s+PLUGIN_VERSION\s*=\s*[\'"]([^\'"]+)[\'"]\s*;?/i', $src, $m)) {
                    return trim($m[1]);
                }
                if (preg_match('/const\s+VERSION\s*=\s*[\'"]([^\'"]+)[\'"]\s*;?/i', $src, $m)) {
                    return trim($m[1]);
                }
                if (preg_match('/define\s*\(\s*[\'"]VERSION[\'"]\s*,\s*[\'"]([^\'"]+)[\'"]\s*\)\s*;?/i', $src, $m)) {
                    return trim($m[1]);
                }
                if (preg_match('/[\'"]version[\'"]\s*=>\s*self::PLUGIN_VERSION\b/i', $src)) {
                    if (preg_match('/const\s+PLUGIN_VERSION\s*=\s*[\'"]([^\'"]+)[\'"]\s*;?/i', $src, $m)) {
                        return trim($m[1]);
                    }
                }
                if (preg_match('/[\'"]version[\'"]\s*=>\s*[\'"]([^\'"]+)[\'"]/i', $src, $m)) {
                    return trim($m[1]);
                }
                if (preg_match('/^\s*\*\s*Version:\s*([0-9][0-9a-zA-Z\.\-\+_]*)/mi', $src, $m)) {
                    return trim($m[1]);
                }
            }
        }

        $map = $this->pm_read_installed_versions();
        $base = basename($dir);
        if (!empty($map[$base]) && !empty($map[$base]['version'])) {
            $version = trim((string)$map[$base]['version']);
            if ($version !== '' && strpos($version, 'local-') !== 0) {
                return $version;
            }
        }

        return $this->pm_read_plugin_version($dir);
    }

    private function build_sources($meta)
    {
        $out = array('packagist' => null, 'github' => null, 'composer_name' => null);
        if (!empty($meta['composer']['name'])) {
            $name = $meta['composer']['name'];
            $out['composer_name'] = $name;
            $out['packagist'] = 'https://packagist.org/packages/' . rawurlencode($name);
        }
        $gh = null;
        if (!empty($meta['composer']['support']['source'])) {
            $gh = $meta['composer']['support']['source'];
        } elseif (!empty($meta['composer']['homepage'])) {
            $gh = $meta['composer']['homepage'];
        }

        if ($gh && preg_match('~^https?://github\.com/[^/\s]+/[^/\s#]+~i', $gh, $m)) {
            $out['github'] = rtrim($m[0], '/');
        }

        if (empty($out['github']) && !empty($meta['mainfile'])) {
            $dir = dirname($meta['mainfile']);
            foreach (array('README.md','README','readme.md','readme') as $rf) {
                $rp = $dir . DIRECTORY_SEPARATOR . $rf;
                if (is_readable($rp)) {
                    $txt = @file_get_contents($rp);
                    if ($txt && preg_match('~https?://github\.com/[^/\s]+/[^/\s#]+~i', $txt, $m2)) {
                        $out['github'] = rtrim($m2[0], '/');
                        break;
                    }
                }
            }
        }
        if (empty($out['github']) && !empty($meta['mainfile']) && is_readable($meta['mainfile'])) {
            $src = @file_get_contents($meta['mainfile']);
            if ($src && preg_match('~https?://github\.com/[^/\s]+/[^/\s#]+~i', $src, $m3)) {
                $out['github'] = rtrim($m3[0], '/');
            }
        }
        // Overlay with sources.map.php if present
	try {
    $base = null;
    if (!empty($meta['mainfile'])) {
        $dir = dirname($meta['mainfile']);
        $base = basename($dir);
    }
    $map = $this->get_sources_map();
    if ($base && is_array($map) && isset($map[$base]) && is_array($map[$base])) {
        $ov = $map[$base];
        // bundled flag
        if (array_key_exists('bundled', $ov)) {
            $out['bundled'] = !empty($ov['bundled']);
        }
        // explicit composer_name override
        if (!empty($ov['composer_name'])) {
            $out['composer_name'] = (string)$ov['composer_name'];
            $out['packagist'] = 'https://packagist.org/packages/' . rawurlencode($out['composer_name']);
        }
        // explicit packagist override (allow short vendor/name or full URL)
        if (!empty($ov['packagist'])) {
            if (preg_match('~^https?://~i', $ov['packagist'])) {
                $out['packagist'] = $ov['packagist'];
            } else {
                $out['packagist'] = 'https://packagist.org/packages/' . rawurlencode($ov['packagist']);
                if (empty($out['composer_name'])) {
                    $out['composer_name'] = (string)$ov['packagist'];
                }
            }
        }
        // explicit github override (allow owner/repo or full URL)
        if (!empty($ov['github'])) {
            if (preg_match('~^https?://~i', $ov['github'])) {
                $out['github'] = rtrim($ov['github'], '/');
            } else {
                $out['github'] = 'https://github.com/' . trim($ov['github'], '/');
            }
        }
    }
	} catch (\Throwable $e) {
		// do not break discovery if map overlay fails
	}
	return $out;
    }

    private function latest_version_cached($sources, $force=false)
    {
        $this->last_reason = '';
        $this->last_via = '';
        $cache = $this->read_cache();
        $key = sha1(json_encode($sources));
        if (!$force && isset($cache[$key]) && (time() - $cache[$key]['ts'] < $this->cache_ttl)) {
            $this->last_ts     = isset($cache[$key]['ts']) ? intval($cache[$key]['ts']) : time();
            $this->last_via    = isset($cache[$key]['via']) ? $cache[$key]['via'] : '';
            $this->last_reason = isset($cache[$key]['reason']) ? $cache[$key]['reason'] : '';
            return $cache[$key]['ver'];
        }
        $meta = $this->latest_version_online($sources);
        $ver  = $meta ? (isset($meta['ver']) ? $meta['ver'] : null) : null;
        if ($meta) { $this->last_via = isset($meta['via']) ? $meta['via'] : ''; $this->last_reason = isset($meta['reason']) ? $meta['reason'] : ''; }
        if ($ver) {
            $this->last_ts = time();
            $cache[$key] = array('ver' => $ver, 'ts' => $this->last_ts, 'via' => $this->last_via, 'reason' => $this->last_reason);
            $this->write_cache($cache);
        }
        return $ver;
    }

    private function read_cache()
    {
        if (is_readable($this->cache_file)) {
            $json = json_decode(@file_get_contents($this->cache_file), true);
            if (is_array($json)) return $json;
        }
        return array();
    }

    private function write_cache($data)
    {
        @file_put_contents($this->cache_file, json_encode($data));
    }

    private function pm_time_ago($ts) {
        $ts = intval($ts);
        if ($ts <= 0) return '';
        $diff = time() - $ts;
        if ($diff < 60) return rcube::Q($this->gettext('just_now'));
        if ($diff < 3600) return intval($diff/60) . rcube::Q($this->gettext('min_ago'));
        if ($diff < 86400) return intval($diff/3600) . rcube::Q($this->gettext('hr_ago'));
        return intval($diff/86400) . ' d ago';
    }

    private function latest_version_online($sources)
    {
        $result = array('ver'=>null,'via'=>'','reason'=>'');
        $allow_prerelease = !isset($sources['allow_prerelease']) || (bool)$sources['allow_prerelease'];

        if (!empty($sources['composer_name'])) {
            $name = $sources['composer_name'];
            $url = 'https://repo.packagist.org/p2/' . $name . '.json';
            $st=0;$er=null; $resp = $this->http_get2($url, array(), $st, $er);
            if ($st === 200 && $resp && ($data = json_decode($resp, true)) && !empty($data['packages'][$name])) {
                $versions = $data['packages'][$name];
                $best = null;
                $filtered = false;
                foreach ($versions as $v) {
                    $ver = isset($v['version']) ? $v['version'] : null;
                    if (!$ver) continue;
                    if (preg_match('/^dev-|dev$/i', $ver)) continue;
                    if (!$allow_prerelease && $this->is_prerelease_version($ver)) {
                        $filtered = true;
                        continue;
                    }
                    if ($best === null || version_compare(ltrim($best,'v'), ltrim($ver,'v')) < 0) {
                        $best = $ver;
                    }
                }
                if ($best) { $result['ver']=$best; $result['via']='packagist'; return $result; }
                if ($filtered) { $result['reason'] = 'prerelease_filtered'; }
            }
        }

        if (!empty($sources['github'])) {
            $gh = $sources['github'];
            if (preg_match('~github\.com/([^/\s]+)/([^/\s#]+)~i', $gh, $m)) {
                $repo = $m[1] . '/' . $m[2];
                $hdrs = array('User-Agent: Roundcube-Plugin-Manager');
                if (!empty($this->gh_token)) { $hdrs[] = 'Authorization: token ' . $this->gh_token; }
                $api = 'https://api.github.com/repos/' . $repo . '/releases/latest';
                $st=0;$er=null; $resp = $this->http_get2($api, $hdrs, $st, $er);
                if ($st === 200 && $resp && ($data = json_decode($resp, true)) && !empty($data['tag_name'])) {
                    $tag = (string)$data['tag_name'];
                    $is_pre = (!empty($data['prerelease']) || $this->is_prerelease_version($tag));
                    if ($allow_prerelease || !$is_pre) {
                        $result['ver'] = ltrim($tag, 'v');
                        $result['via'] = 'github-release';
                        return $result;
                    }
                    $result['reason'] = 'prerelease_filtered';
                }
                $api2 = 'https://api.github.com/repos/' . $repo . '/tags';
                $st2=0;$er2=null; $resp2 = $this->http_get2($api2, $hdrs, $st2, $er2);
                if ($st2 === 200 && $resp2 && ($tags = json_decode($resp2, true)) && is_array($tags)) {
                    $best = null;
                    foreach ($tags as $t) {
                        $tag = isset($t['name']) ? $t['name'] : '';
                        if (!$tag) continue;
                        if (!$allow_prerelease && $this->is_prerelease_version($tag)) continue;
                        $tag = ltrim($tag, 'v');
                        if ($best === null || version_compare($best, $tag) < 0) { $best = $tag; }
                    }
                    if ($best) { $result['ver']=$best; $result['via']='github-tags'; return $result; }
                }
                $result['reason'] = $st ? ('http_' . (string)$st) : 'no_release';
            }
        }
        return $result;
    }

    private function compare_versions($local, $remote)
    {
        if (!$local) return -1;
        $a = ltrim((string)$local, 'v');
        $b = ltrim((string)$remote, 'v');
        return version_compare($a, $b);
    }

    private function is_prerelease_version($version)
    {
        if ($version === null) return false;
        return (bool)preg_match('/(?:alpha|beta|rc)/i', (string)$version);
    }

    private function http_get2($url, $headers = array(), &$status = null, &$err = null)
    {
        $status = 0; $err = null;
        if (function_exists('curl_init')) {
            $ch = curl_init();
            $proto_https = defined('CURLPROTO_HTTPS') ? CURLPROTO_HTTPS : (defined('CURLPROTO_HTTP') ? (CURLPROTO_HTTP|CURLPROTO_HTTPS) : 3);
            curl_setopt_array($ch, array(
                CURLOPT_PROTOCOLS => $proto_https,
                CURLOPT_REDIR_PROTOCOLS => $proto_https,
                CURLOPT_SSL_VERIFYPEER => true,
                CURLOPT_SSL_VERIFYHOST => 2,
                CURLOPT_USERAGENT => isset($this->http_user_agent) ? $this->http_user_agent : 'Roundcube-Plugin-Manager/1.0',
                CURLOPT_URL => $url,
                CURLOPT_RETURNTRANSFER => true,
                CURLOPT_FOLLOWLOCATION => true,
                CURLOPT_CONNECTTIMEOUT => $this->timeout,
                CURLOPT_TIMEOUT => $this->timeout,
                CURLOPT_HTTPHEADER => $headers,
                CURLOPT_HEADER => true,
            ));
            $resp = curl_exec($ch);
            if ($resp === false) {
                $err = curl_error($ch);
                curl_close($ch);
                return false;
            }
            $code = curl_getinfo($ch, CURLINFO_HTTP_CODE);
            $header_size = curl_getinfo($ch, CURLINFO_HEADER_SIZE);
            $body = substr($resp, $header_size);
            $status = (int)$code;
            curl_close($ch);
            return $body;
        }
        $ctx = stream_context_create(array('http' => array('method' => 'GET', 'timeout'=> $this->timeout, 'header' => implode("\r\n", $headers))));
        $body = @file_get_contents($url, false, $ctx);
        if (isset($http_response_header) && is_array($http_response_header)) {
            foreach ($http_response_header as $h) {
                if (preg_match('~^HTTP/\S+\s+(\d+)~', $h, $m)) { $status = (int)$m[1]; break; }
            }
        }
        if ($body === false) { $err = 'stream_error'; }
        return $body;
    }

    function action_update()
    {
        $rc = $this->rc;
        if (!$this->is_update_admin()) {
            $rc->output->show_message('' . rcube::Q($this->gettext('not_authorized')) . '.', 'error');
            $rc->output->redirect(array('_task'=>'settings','_action' => 'plugin.plugin_manager'));
            return;
        }
        if (!$this->request_token_valid()) {
            $rc->output->show_message('' . rcube::Q($this->gettext('not_authorized')) . '.', 'error');
            $rc->output->redirect(array('_task'=>'settings','_action' => 'plugin.plugin_manager'));
            return;
        }
        $plugin_dir = rcube_utils::get_input_value('_pm', rcube_utils::INPUT_GPC);
        $plugin_dir = preg_replace('~[^a-zA-Z0-9_\-]~', '', (string)$plugin_dir);
        if (!$plugin_dir) {
            $rc->output->show_message('' . rcube::Q($this->gettext('missing_parameter')) . '.', 'error');
            $rc->output->redirect(array('_task'=>'settings','_action' => 'plugin.plugin_manager'));
            return;
        }
        try {
            $ok = $this->perform_update($plugin_dir);
            if (is_array($ok) && !empty($ok['ok'])) {
                $rc->output->show_message('' . rcube::Q($this->gettext('plugin_update_good')) . '.', 'confirmation');
                if (!empty($ok['advisory']) && is_array($ok['advisory'])) {
                    $this->flash_post_update_advisory($ok['advisory']);
                }
                if (!empty($ok['hook']) && is_array($ok['hook'])) {
                    $this->flash_post_update_hook_result($ok['hook'], $plugin_dir);
                }
            } else {
                $rc->output->show_message('Update finished: ' . rcube::Q((string)$ok), 'notice');
            }
        } catch (Exception $e) {
            $this->log_debug('Update error', array('plugin'=>$plugin_dir, 'err'=>$e->getMessage()));
            $rc->output->show_message('Update failed: ' . rcube::Q($e->getMessage()), 'error');
        }
        $rc->output->redirect(array('_task'=>'settings','_action' => 'plugin.plugin_manager'));
    }    

    function action_restore()
    {
        $rc = $this->rc;
        if (!$this->is_update_admin()) {
            $rc->output->show_message('' . rcube::Q($this->gettext('not_authorized')) . '.', 'error');
            $rc->output->redirect(array('_task'=>'settings','_action' => 'plugin.plugin_manager'));
            return;
        }
        if (!$this->request_token_valid()) {
            $rc->output->show_message('' . rcube::Q($this->gettext('not_authorized')) . '.', 'error');
            $rc->output->redirect(array('_task'=>'settings','_action' => 'plugin.plugin_manager'));
            return;
        }
        $dir_name = rcube_utils::get_input_value('_pm', rcube_utils::INPUT_GPC);
        $dir_name = preg_replace('~[^a-zA-Z0-9_\-]~', '', (string)$dir_name);
        $bak_name = rcube_utils::get_input_value('_bak', rcube_utils::INPUT_GPC);
        $bak_name = preg_replace('~[^a-zA-Z0-9_\-\.]+~', '', (string)$bak_name);

        $plugins_root = $this->plugins_root_dir();
        if (!$plugins_root || !$dir_name) {
            $rc->output->show_message('' . rcube::Q($this->gettext('missing_parameter')) . '.', 'error');
            $rc->output->redirect(array('_task'=>'settings','_action' => 'plugin.plugin_manager'));
            return;
        }

        $plugdir = $plugins_root . DIRECTORY_SEPARATOR . $dir_name;
        $bakdir = null;
        if ($bak_name && is_dir($plugins_root . DIRECTORY_SEPARATOR . $bak_name)) {
            $bakdir = $plugins_root . DIRECTORY_SEPARATOR . $bak_name;
        } else {
            $candidates = (array)glob($plugdir . '.bak-*', GLOB_NOSORT);
            if ($candidates) {
                usort($candidates, function($a,$b){ return filemtime($b) <=> filemtime($a); });
                $bakdir = $candidates[0];
            }
        }
        if (!$bakdir || !is_dir($bakdir)) {
            $rc->output->show_message('' . rcube::Q($this->gettext('no_backups')) . '.', 'error');
            $rc->output->redirect(array('_task'=>'settings','_action' => 'plugin.plugin_manager'));
            return;
        }

        try {
            $stamp = date('Ymd-His');
            $restore_bak = $plugdir . '.bak-restore-' . $stamp;
            if (is_dir($plugdir)) { $this->recurse_copy($plugdir, $restore_bak, array()); $this->rrmdir($plugdir); }
            $this->recurse_copy($bakdir, $plugdir, array());

            $meta_r = $this->read_plugin_meta($plugdir);
            $ver_r  = $this->detect_local_version($plugdir, $meta_r);
            $installed_r = $this->pm_read_installed_versions();
            if (!is_array($installed_r)) { $installed_r = array(); }
            $installed_r[$dir_name] = array('version' => $ver_r, 'last_updated' => gmdate('c'));
            $this->pm_write_installed_versions($installed_r);
            $this->pm_write_central_versions();

            $rc->output->show_message('' . rcube::Q($this->gettext('restored')) . '.', 'confirmation');
        } catch (Exception $e) {
            $rc->output->show_message('' . rcube::Q($e->getMessage()) . '.', 'error');
        }
        $rc->output->redirect(array('_task'=>'settings','_action' => 'plugin.plugin_manager'));
    }

    function action_delete_backups()
    {
        $rc = $this->rc;
        if (!$this->is_update_admin()) {
            $this->flash_add($this->gettext('not_authorized'), 'error');
            $rc->output->redirect(array('_task' => 'settings', '_action' => 'plugin.plugin_manager'));
            return;
        }
        if (!$this->request_token_valid()) {
            $this->flash_add($this->gettext('not_authorized'), 'error');
            $rc->output->redirect(array('_task' => 'settings', '_action' => 'plugin.plugin_manager'));
            return;
        }

        $selected = $this->sanitize_selected_plugins(rcube_utils::get_input_value('_pm_selected', rcube_utils::INPUT_GPC));
        if (empty($selected)) {
            $this->flash_add($this->gettext('delete_backups_no_selection') ?: 'No valid selected plugins were provided.', 'warning');
            $rc->output->redirect(array('_task' => 'settings', '_action' => 'plugin.plugin_manager'));
            return;
        }

        $valid_plugins = 0;
        $deleted_dirs = 0;
        $plugins_without_backups = 0;
        $failed_deletions = 0;
        $failure_details = array();

        foreach ($selected as $plugin) {
            $live_dir = $this->resolve_live_plugin_dir($plugin);
            if ($live_dir === null) {
                continue;
            }

            $valid_plugins++;
            $backup_dirs = $this->find_plugin_backup_dirs($plugin);
            if (empty($backup_dirs)) {
                $plugins_without_backups++;
                continue;
            }

            foreach ($backup_dirs as $backup_dir) {
                if ($this->delete_directory_recursive($backup_dir)) {
                    $deleted_dirs++;
                    continue;
                }

                $failed_deletions++;
                $failure_details[] = basename($backup_dir);
            }
        }

        if ($valid_plugins === 0) {
            $this->flash_add($this->gettext('delete_backups_no_selection') ?: 'No valid selected plugins were provided.', 'warning');
            $rc->output->redirect(array('_task' => 'settings', '_action' => 'plugin.plugin_manager'));
            return;
        }

        if ($deleted_dirs === 0 && $plugins_without_backups === 0 && $failed_deletions === 0) {
            $this->flash_add($this->gettext('delete_backups_no_valid_targets') ?: 'No valid backup folders were found for the selected plugins.', 'warning');
            $rc->output->redirect(array('_task' => 'settings', '_action' => 'plugin.plugin_manager'));
            return;
        }

        $summary = sprintf(
            $this->gettext('delete_backups_summary') ?: 'Backup deletion complete: %d deleted, %d plugins had no backups, %d failed.',
            $deleted_dirs,
            $plugins_without_backups,
            $failed_deletions
        );
        $this->flash_add($summary, $failed_deletions > 0 ? 'warning' : 'confirmation');

        if (!empty($failure_details)) {
            $detail_list = array_slice($failure_details, 0, 12);
            $detail_text = implode(', ', $detail_list);
            if (count($failure_details) > count($detail_list)) {
                $detail_text .= ', +' . (count($failure_details) - count($detail_list)) . ' more';
            }

            $this->flash_add(
                sprintf(
                    $this->gettext('delete_backups_failed_detail') ?: 'Failed backup deletions: %s',
                    $detail_text
                ),
                'warning'
            );
        }

        $rc->output->redirect(array('_task' => 'settings', '_action' => 'plugin.plugin_manager'));
    }

    function action_run_maintenance()
    {
        $rc = $this->rc;
        $plugin = rcube_utils::get_input_value('_pm', rcube_utils::INPUT_GPC);
        $plugin = preg_replace('~[^a-zA-Z0-9_\-\.]~', '', (string) $plugin);

        $this->log_debug('manual_maintenance_requested', array('plugin' => $plugin));

        if (!$this->is_update_admin()) {
            $this->flash_add($this->gettext('not_authorized'), 'error');
            $rc->output->redirect(array('_task' => 'settings', '_action' => 'plugin.plugin_manager'));
            return;
        }
        if (!$this->request_token_valid()) {
            $this->flash_add($this->gettext('not_authorized'), 'error');
            $rc->output->redirect(array('_task' => 'settings', '_action' => 'plugin.plugin_manager'));
            return;
        }
        if ($plugin === '') {
            $this->flash_add($this->gettext('missing_parameter'), 'error');
            $rc->output->redirect(array('_task' => 'settings', '_action' => 'plugin.plugin_manager'));
            return;
        }

        $preflight = $this->preflight_post_update_hook($plugin, 'manual');
        if (empty($preflight['ok'])) {
            $this->log_debug('manual_maintenance_ineligible', array('plugin' => $plugin));
            $reasons = !empty($preflight['reasons']) && is_array($preflight['reasons']) ? implode(' ', $preflight['reasons']) : '';
            $this->record_maintenance_audit(array(
                'plugin' => $plugin,
                'event' => 'manual',
                'result' => 'refused',
                'message' => $reasons !== '' ? $reasons : 'Manual maintenance not runnable.',
                'current_version' => null,
                'previous_version' => null,
                'hook_summary' => isset($preflight['hook_path']) ? $preflight['hook_path'] : '',
            ));
            $this->flash_add(
                sprintf($this->gettext('maintenance_unavailable') ?: 'Maintenance could not run for plugin %s: invalid hook configuration.', $plugin)
                . ($reasons !== '' ? ' ' . $reasons : ''),
                'warning'
            );
            $rc->output->redirect(array('_task' => 'settings', '_action' => 'plugin.plugin_manager'));
            return;
        }

        $context = $this->build_manual_maintenance_context($plugin);
        $result = $this->run_allowlisted_post_update_hook($plugin, 'manual', $context);
        $this->flash_manual_maintenance_result($result, $plugin);
        $rc->output->redirect(array('_task' => 'settings', '_action' => 'plugin.plugin_manager'));
    }

    private function perform_update($dir_name)
    {
        $root = $this->plugins_root_dir();
        if (!$root) { throw new Exception(rcube::Q($this->gettext('no_locate_dir'))); }
        $this->last_post_update_advisory = null;

        $plugdir = $root . DIRECTORY_SEPARATOR . $dir_name;
        $previous_version = null;
        if (is_dir($plugdir)) {
            try {
                $previous_meta = $this->read_plugin_meta($plugdir);
                $previous_version = $this->detect_local_version($plugdir, $previous_meta);
            } catch (Exception $e) {
                $previous_version = null;
            }
        }

        $do_bak = $this->config->get('pm_backups', true);
        if ($do_bak) {
            $bak = $plugdir . '.bak-' . date('Ymd-His');
            $this->recurse_copy($plugdir, $bak, array());
            $this->prune_backups($dir_name);
        }

        if (!is_dir($plugdir)) { throw new Exception('' . rcube::Q($this->gettext('plugin_not_found')) . ': ' . $dir_name); }

        $meta    = $this->read_plugin_meta($plugdir);
        $sources = $this->build_sources($meta);
        if (!empty($sources['bundled'])) {
            throw new Exception('Updates for bundled Roundcube plugins are disabled. Update Roundcube itself to receive new versions.');
        }
        $channel = strtolower((string)$this->config->get('pm_update_channel', 'release'));

        $zipurl = null; $j = null; $owner = null; $repo = null;
        if (!empty($sources['github']) && preg_match('~https://github\.com/([^/]+)/([^/\.]+)~', $sources['github'], $m)) {
            $owner = $m[1]; $repo = $m[2];
            if ($channel === 'release') {
                $api = "https://api.github.com/repos/$owner/$repo/releases/latest";
                $hdrs = array('User-Agent: Roundcube-Plugin-Manager');
                if (!empty($this->gh_token)) { $hdrs[] = 'Authorization: token ' . $this->gh_token; }
                $st=0;$er=null;$resp=$this->http_get2($api, $hdrs, $st, $er);
                if ($st >= 200 && $st < 300 && $resp) {
                    $j = @json_decode($resp, true);
                    if (!empty($j['zipball_url'])) { $zipurl = $j['zipball_url']; }
                }
            }
            if (!$zipurl || $channel === 'dev') {
                $zipurl = "https://github.com/$owner/$repo/archive/refs/heads/master.zip";
            }
        }
        if (!$zipurl) {
            throw new Exception(rcube::Q($this->gettext('no_dnld_url')) . $dir_name);
        }

        $status=0;$err=null;
        $data = $this->http_get2($zipurl, array('User-Agent: Roundcube-Plugin-Manager'), $status, $err);
        if (($status < 200 || $status >= 300 || !$data) && preg_match('~archive/refs/heads/master\.zip$~', $zipurl)) {
            $zipurl = preg_replace('~master\.zip$~', 'main.zip', $zipurl);
            $status=0;$err=null;
            $data = $this->http_get2($zipurl, array('User-Agent: Roundcube-Plugin-Manager'), $status, $err);
        }
        if ($status < 200 || $status >= 300 || !$data) {
            throw new Exception(rcube::Q($this->gettext('dnld_failed')) . ' (HTTP ' . intval($status) . ', ' . $err . ')');
        }

        if (!class_exists('ZipArchive')) { throw new Exception(rcube::Q($this->gettext('zip_no_avail'))); }
        $tmpzip = $plugdir . '.update.zip';
        @file_put_contents($tmpzip, $data);

        $tmpdir = $plugdir . '.update';
        $this->rrmdir($tmpdir);
        @mkdir($tmpdir, 0775, true);

        $zip = new ZipArchive();
        if ($zip->open($tmpzip) !== true) {
            @unlink($tmpzip);
            throw new Exception('Cannot open zip');
        }
        if (!$this->is_safe_update_zip_archive($zip)) {
            $zip->close();
            @unlink($tmpzip);
            $this->rrmdir($tmpdir);
            throw new Exception('Update archive contains unsafe paths.');
        }
        $zip->extractTo($tmpdir);
        $zip->close();
        @unlink($tmpzip);

        $entries = @scandir($tmpdir);
        $srcdir = $tmpdir;
        if ($entries) {
            foreach ($entries as $e) {
                if ($e === '.' || $e === '..') continue;
                if (is_dir($tmpdir . DIRECTORY_SEPARATOR . $e)) { $srcdir = $tmpdir . DIRECTORY_SEPARATOR . $e; break; }
            }
        }

        $this->recurse_copy($srcdir, $plugdir, array('config.inc.php'));
        $this->rrmdir($tmpdir);

        if (!empty($this->cache_file) && file_exists($this->cache_file)) { @unlink($this->cache_file); }
        
        try {
            $meta_new  = $this->read_plugin_meta($plugdir);
            $ver_remote = $this->latest_version_cached($sources, true);
            $ver_local  = $this->detect_local_version($plugdir, $meta_new);
            $ver_final  = $ver_remote ?: $ver_local;
            $map = $this->pm_read_installed_versions();
            if (!is_array($map)) { $map = array(); }
            $map[$dir_name] = array('version' => (string)$ver_final, 'last_updated' => gmdate('c'));
            $this->pm_write_installed_versions($map);
        } catch (Exception $e) { }
        
        $this->pm_write_central_versions();

        $advisory = $this->inspect_post_update_requirements($dir_name);
        $this->last_post_update_advisory = $advisory;
        $hook_result = $this->run_allowlisted_post_update_hook($dir_name, 'update', array(
            'previous_version' => $previous_version,
            'current_version' => isset($ver_final) ? (string) $ver_final : null,
        ));

        return array(
            'ok' => true,
            'advisory' => $advisory,
            'hook' => $hook_result,
        );
    }

    private function recurse_copy($src, $dst, $preserve = array())
    {
        $it = new RecursiveIteratorIterator(new RecursiveDirectoryIterator($src, FilesystemIterator::SKIP_DOTS), RecursiveIteratorIterator::SELF_FIRST);
        foreach ($it as $item) {
            $rel = substr($item->getPathname(), strlen($src)+1);
            $target = $dst . DIRECTORY_SEPARATOR . $rel;
            if ($item->isDir()) {
                if (!is_dir($target)) { @mkdir($target, 0775, true); }
            } else {
                $base = basename($rel);
                if (in_array($base, $preserve, true) && file_exists($target)) { continue; }
                @copy($item->getPathname(), $target);
            }
        }
    }

    private function rrmdir($dir)
    {
        if (!is_dir($dir)) return;
        $it = new RecursiveIteratorIterator(new RecursiveDirectoryIterator($dir, FilesystemIterator::SKIP_DOTS), RecursiveIteratorIterator::CHILD_FIRST);
        foreach ($it as $file) {
            if ($file->isDir()) { @rmdir($file->getPathname()); }
            else { @unlink($file->getPathname()); }
        }
        @rmdir($dir);
    }

    private function prune_backups($dir_name)
    {
        $keep = (int)$this->config->get('pm_keep_backups', 3);
        $max_age_days = (int)$this->config->get('pm_backups_max_age_days', 0);
        $root = $this->plugins_root_dir();
        if (!$root) { return; }

        $plugdir = $root . DIRECTORY_SEPARATOR . $dir_name;
        $parent = dirname($plugdir);
        $prefix = basename($plugdir) . '.bak-';
        $now = time();
        $items = array();

        foreach ((array)@scandir($parent) as $e) {
            if ($e === '.' || $e === '..') continue;
            if (strpos($e, $prefix) !== 0) continue;
            $p = $parent . DIRECTORY_SEPARATOR . $e;
            if (!is_dir($p)) continue;
            $items[] = array('path' => $p, 'name' => $e, 'mtime' => @filemtime($p) ?: 0);
        }

        if (!$items) return;

        usort($items, function($a,$b){ return ($b['mtime'] <=> $a['mtime']); });

        $delete = array();
        if ($max_age_days > 0) {
            $cut = $now - ($max_age_days * 86400);
            foreach ($items as $idx => $it) {
                if ($keep > 0 && $idx < $keep) continue;
                if ($it['mtime'] > 0 && $it['mtime'] < $cut) $delete[] = $it;
            }
        }
        if ($keep > 0) {
            for ($i = $keep; $i < count($items); $i++) {
                $already = false;
                foreach ($delete as $d) { if ($d['path'] === $items[i]['path']) { $already = true; break; } }
                if (!$already) $delete[] = $items[$i];
            }
        }
        foreach ($delete as $d) {
            $this->log_debug('prune_backup delete', array('path' => $d['path'], 'mtime' => $d['mtime']));
            $this->rrmdir($d['path']);
        }
    }

    private function cfg_true($key, $default=false) {
        $master = $this->config->get('pm_features_enabled', true);
        if (!$master) return false;
        return (bool)$this->config->get($key, $default);
    }

    private function policy_for($dir_name) {
        $out = array(
            'ignored' => array('discover'=>false, 'notify'=>false, 'bulk'=>false, 'ui'=>false),
            'pinned'  => null,
            'reason'  => '',
        );
        if (!$this->cfg_true('pm_policies_enabled', true)) return $out;

        if ($this->cfg_true('pm_pins_enabled', true)) {
            $pins = (array)$this->config->get('pm_pins', array());
            if (isset($pins[$dir_name]) && is_string($pins[$dir_name]) && $pins[$dir_name] !== '') {
                $out['pinned'] = (string)$pins[$dir_name];
                $out['reason'] = 'pinned';
            }
        }
        if ($this->cfg_true('pm_ignore_enabled', true)) {
            $rules = (array)$this->config->get('pm_ignore_rules', array());
            foreach ($rules as $r) {
                $match = false;
                if (isset($r['plugin']) && is_string($r['plugin']) && $r['plugin'] === $dir_name) $match = true;
                elseif (isset($r['pattern']) && is_string($r['pattern']) && @preg_match($r['pattern'], $dir_name)) $match = true;
                if ($match) {
                    $scopes = isset($r['scopes']) && is_array($r['scopes']) ? $r['scopes'] : array('bulk','notify');
                    foreach ($scopes as $s) {
                        if (isset($out['ignored'][$s])) $out['ignored'][$s] = true;
                    }
                    if (empty($out['reason']) && !empty($r['reason'])) $out['reason'] = (string)$r['reason'];
                }
            }
        }
        return $out;
    }

    private function pm_data_init()
    {
        $this->home = dirname(__FILE__);
        $plugin_dir = realpath($this->home) ?: $this->home;
        $this->data_dir = $plugin_dir . DIRECTORY_SEPARATOR . 'data';
        if (!is_dir($this->data_dir)) @mkdir($this->data_dir, 0775, true);
        $this->central_version_file    = $this->data_dir . DIRECTORY_SEPARATOR . 'version.json';
        $this->installed_versions_file = $this->data_dir . DIRECTORY_SEPARATOR . 'installed_versions.json';
        $this->maintenance_audit_file  = $this->data_dir . DIRECTORY_SEPARATOR . 'maintenance_audit.json';

        $this->pm_ensure_json_file($this->installed_versions_file, array());
        $this->pm_ensure_json_file($this->central_version_file, $this->pm_default_central_versions_data());
    }

    private function pm_default_central_versions_data()
    {
        return array(
            'generated_at' => gmdate('c'),
            'plugins_root' => null,
            'plugins' => array(),
        );
    }

    private function pm_ensure_json_file($path, array $default)
    {
        if (!is_string($path) || $path === '' || is_file($path)) {
            return;
        }

        $dir = dirname($path);
        if (!is_dir($dir)) {
            @mkdir($dir, 0775, true);
        }

        if (!is_dir($dir) || !is_writable($dir)) {
            return;
        }

        @file_put_contents($path, json_encode($default, JSON_PRETTY_PRINT | JSON_UNESCAPED_SLASHES), LOCK_EX);
    }

    private function pm_bootstrap_version_data()
    {
        $this->pm_data_init();

        if ($this->pm_installed_versions_need_bootstrap()) {
            $this->pm_write_installed_versions($this->pm_build_installed_versions_snapshot());
        }

        if ($this->pm_central_versions_need_bootstrap()) {
            $this->pm_write_central_versions();
        }
    }

    private function pm_installed_versions_need_bootstrap()
    {
        if (!is_file($this->installed_versions_file) || filesize($this->installed_versions_file) === 0) {
            return true;
        }

        $map = $this->pm_read_installed_versions();
        if (count($map) === 0) {
            return true;
        }

        foreach ($map as $entry) {
            $version = isset($entry['version']) ? trim((string) $entry['version']) : '';
            if ($version === '' || strpos($version, 'local-') === 0) {
                return true;
            }
        }

        return false;
    }

    private function pm_central_versions_need_bootstrap()
    {
        if (!is_file($this->central_version_file) || filesize($this->central_version_file) === 0) {
            return true;
        }

        $raw = @file_get_contents($this->central_version_file);
        $json = @json_decode($raw, true);
        if (!is_array($json)) {
            return true;
        }

        if (!isset($json['plugins']) || !is_array($json['plugins'])) {
            return true;
        }

        if (empty($json['plugins'])) {
            $plugins_root = $this->plugins_root_dir();
            if ($plugins_root && is_dir($plugins_root)) {
                foreach (new DirectoryIterator($plugins_root) as $entry) {
                    if ($entry->isDot() || !$entry->isDir()) {
                        continue;
                    }

                    if (preg_match('/\.bak-\d{8}-\d{6}$/', $entry->getFilename())) {
                        continue;
                    }

                    return true;
                }
            }
        }

        return empty($json['generated_at']);
    }

    private function pm_build_installed_versions_snapshot()
    {
        $plugins_root = $this->plugins_root_dir();
        if (!$plugins_root || !is_dir($plugins_root)) {
            return array();
        }

        $snapshot = array();
        $timestamp = gmdate('c');
        $plugins = $this->discover_plugins();

        foreach ($plugins as $dir_name => $plugin) {
            if (empty($plugin['dir']) || !is_dir($plugin['dir'])) {
                continue;
            }

            $meta = $this->read_plugin_meta($plugin['dir']);
            $snapshot[$dir_name] = array(
                'version' => $this->detect_local_version($plugin['dir'], $meta),
                'last_updated' => $timestamp,
            );
        }

        return $snapshot;
    }

    private function pm_read_plugin_version($dir)
    {
        if ($this->is_self_plugin_dir($dir)) {
            return self::PLUGIN_VERSION;
        }

        $vj = rtrim($dir, DIRECTORY_SEPARATOR) . DIRECTORY_SEPARATOR . 'version.json';
        if (is_file($vj)) {
            $raw = @file_get_contents($vj);
            $j = @json_decode($raw, true);
            if (is_array($j) && !empty($j['version'])) return (string)$j['version'];
        }
        $cj = rtrim($dir, DIRECTORY_SEPARATOR) . DIRECTORY_SEPARATOR . 'composer.json';
        if (is_file($cj)) {
            $raw = @file_get_contents($cj);
            $j = @json_decode($raw, true);
            if (is_array($j) && !empty($j['version'])) {
                $v = trim((string)$j['version']);
                if ($v !== '') return $v;
            }
        }
        $latest = 0;
        $it = new RecursiveIteratorIterator(new RecursiveDirectoryIterator($dir, FilesystemIterator::SKIP_DOTS));
        foreach ($it as $f) {
            if ($f->isDir()) continue;
            $mt = @filemtime($f->getPathname());
            if ($mt && $mt > $latest) $latest = $mt;
        }
        return 'local-' . gmdate('Y.m.d.His', $latest ?: time());
    }

    private function is_self_plugin_dir($dir)
    {
        $plugin_dir = realpath($this->home ?: dirname(__FILE__));
        $dir_real = realpath($dir);

        if ($plugin_dir && $dir_real) {
            return $plugin_dir === $dir_real;
        }

        return rtrim((string)$dir, DIRECTORY_SEPARATOR) === rtrim($this->home ?: dirname(__FILE__), DIRECTORY_SEPARATOR);
    }

    public function pm_write_central_versions()
    {
        $this->pm_data_init();
        $plugins_root = $this->plugins_root_dir();
        if (!$plugins_root) {
            $this->log_debug('pm_write_central_versions: missing root');
            return;
        }

        $out = array(
            'generated_at' => gmdate('c'),
            'plugins_root' => $plugins_root,
            'plugins'      => array(),
        );

        $entries = array();
        if (is_dir($plugins_root)) {
            $dh = @opendir($plugins_root);
            if ($dh) {
                while (($entry = readdir($dh)) !== false) {
                    if ($entry === '.' || $entry === '..') continue;
                    if (preg_match('/\.bak-\d{8}-\d{6}$/', $entry)) continue;
                    $dir = $plugins_root . DIRECTORY_SEPARATOR . $entry;
                    if (!is_dir($dir)) continue;
                    $entries[] = $entry;
                }
                closedir($dh);
            }
        }
        sort($entries, SORT_STRING);

        foreach ($entries as $entry) {
            $dir = $plugins_root . DIRECTORY_SEPARATOR . $entry;
            $map = $this->pm_read_installed_versions();
            if (!empty($map[$entry]) && !empty($map[$entry]['version'])) {
                $out['plugins'][$entry] = (string)$map[$entry]['version'];
            } else {
                $out['plugins'][$entry] = $this->pm_read_plugin_version($dir);
            }
        }

        @file_put_contents($this->central_version_file, json_encode($out, JSON_PRETTY_PRINT | JSON_UNESCAPED_SLASHES));
    }

    private function pm_read_installed_versions()
    {
        $this->pm_data_init();
        if (!is_file($this->installed_versions_file)) return array();
        $raw = @file_get_contents($this->installed_versions_file);
        $j = @json_decode($raw, true);
        if (!is_array($j)) return array();
        $out = array();
        foreach ($j as $name => $val) {
            if (is_string($val)) {
                $out[$name] = array('version' => $val, 'last_updated' => null);
            } else if (is_array($val)) {
                $v = isset($val['version']) ? (string)$val['version'] : null;
                $lu = isset($val['last_updated']) ? $val['last_updated'] : null;
                $out[$name] = array('version' => $v, 'last_updated' => $lu);
            }
        }
        return $out;
    }

    private function pm_write_installed_versions(array $map)
    {
        $this->pm_data_init();
        @file_put_contents($this->installed_versions_file, json_encode($map, JSON_PRETTY_PRINT | JSON_UNESCAPED_SLASHES));
    }

    private function can_view()
    {
        if ($this->visibility === 'admin_only') {
            return $this->is_update_admin();
        }
        return true;
    }

    private function is_update_admin()
    {
        $uid = method_exists($this->rc, 'get_user_id') ? intval($this->rc->get_user_id()) : (isset($this->rc->user) && isset($this->rc->user->ID) ? intval($this->rc->user->ID) : 0);
        $admins = (array)$this->config->get('pm_update_admins', array(1));
        $admins = array_map('intval', $admins);
        return in_array($uid, $admins, true);
    }

    private function request_token_valid()
    {
        $token = rcube_utils::get_input_value('_token', rcube_utils::INPUT_GPC);
        if (($token === null || $token === '') && !empty($_SERVER['HTTP_X_RCUBE_TOKEN'])) {
            $token = (string)$_SERVER['HTTP_X_RCUBE_TOKEN'];
        }
        $token = (string)$token;
        $expected = (string)$this->rc->get_request_token();
        if ($token === '' || $expected === '') {
            return false;
        }
        return hash_equals($expected, $token);
    }

    private function format_skip_reasons($skipped, $limit = 12) {
        if (!$skipped) return '';
        $map = array(
            'backup_dir' => 'backup dir',
            'pinned' => 'pinned',
            'ignored_bulk' => 'ignored by policy',
            'bundled' => 'bundled plugin',
            'no_sources' => 'no sources',
            'no_remote_version' => 'no remote version',
            'up_to_date' => 'up to date',
            'dry' => 'dry-run'
        );
        $parts = array();
        $n = 0;
        foreach ($skipped as $s) {
            $n++;
            if ($n > $limit) break;
            $dir = isset($s['dir']) ? $s['dir'] : '?';
            $why = isset($s['reason']) ? (isset($map[$s['reason']]) ? $map[$s['reason']] : $s['reason']) : '';
            $extra = '';
            if ($s['reason'] === 'dry' && isset($s['from']) && isset($s['to'])) {
                $extra = ' ' . $s['from'] . '→' . $s['to'];
            }
            $parts[] = $dir . ' (' . $why . $extra . ')';
        }
        $more = count($skipped) - min(count($skipped), $limit);
        $msg = implode(', ', $parts);
        if ($more > 0) { $msg .= ', +' . $more . ' more'; }
        return $msg;
    }

    public function action_load_config()
    {
        while (ob_get_level() > 0) { @ob_end_clean(); }
        $this->rc->output->reset();
        @header('Content-Type: application/json; charset=UTF-8');

        if (!$this->is_update_admin()) {
            echo json_encode(array('ok'=>false, 'error'=>'not_authorized'));
            exit;
        }
        if (!$this->request_token_valid()) {
            echo json_encode(array('ok'=>false, 'error'=>'invalid_token'));
            exit;
        }

        $plug = rcube_utils::get_input_value('_pm_plug', rcube_utils::INPUT_GPC);
        $plug = preg_replace('~[^a-zA-Z0-9_\-\.]+~', '', (string)$plug);

        $plugdir = $plug !== '' ? $this->resolve_live_plugin_dir($plug) : null;
        $cfg   = $plugdir ? ($plugdir . DIRECTORY_SEPARATOR . 'config.inc.php') : null;
        $cfgd  = $plugdir ? ($plugdir . DIRECTORY_SEPARATOR . 'config.inc.php.dist') : null;
        $cfgs  = $plugdir ? ($plugdir . DIRECTORY_SEPARATOR . 'config.inc.php.sample') : null;

        if ($plug === '' || !$plugdir || !is_dir($plugdir)) {
            echo json_encode(array('ok'=>false, 'error'=>'plugdir_not_found'));
            exit;
        }

        $path = null; $readonly = false;
        if ($cfg && is_readable($cfg)) { $path = $cfg; }
        elseif ($cfgd && is_readable($cfgd)) { $path = $cfgd; $readonly = true; }
        elseif ($cfgs && is_readable($cfgs)) { $path = $cfgs; $readonly = true; }
        else { echo json_encode(array('ok'=>false,'error'=>'no_config')); exit; }

        $text = @file_get_contents($path);
        if ($text === false) {
            echo json_encode(array('ok'=>false,'error'=>'read_fail'));
            exit;
        }
        echo json_encode(array('ok'=>true, 'path'=>$path, 'readonly'=>$readonly, 'content'=>$text, 'plug'=>$plug));
        exit;
    }

    public function action_save_config()
    {
        while (ob_get_level() > 0) { @ob_end_clean(); }
        $this->rc->output->reset();
        @header('Content-Type: application/json; charset=UTF-8');

        if (!$this->is_update_admin()) {
            echo json_encode(array('ok'=>false, 'error'=>'not_authorized'));
            exit;
        }
        if (!$this->request_token_valid()) {
            echo json_encode(array('ok'=>false, 'error'=>'invalid_token'));
            exit;
        }

        $plug = rcube_utils::get_input_value('_pm_plug', rcube_utils::INPUT_POST);
        $plug = preg_replace('~[^a-zA-Z0-9_\-\.]+~', '', (string)$plug);
        $content = rcube_utils::get_input_value('_pm_content', rcube_utils::INPUT_POST, true);

        $plugdir = $plug !== '' ? $this->resolve_live_plugin_dir($plug) : null;

        if ($plug === '' || $content === null) {
            echo json_encode(array('ok'=>false, 'error'=>'bad_params'));
            exit;
        }
        if (!$plugdir || !is_dir($plugdir)) {
            echo json_encode(array('ok'=>false, 'error'=>'plugdir_not_found'));
            exit;
        }

        $file = $plugdir . DIRECTORY_SEPARATOR . 'config.inc.php';
        if (file_exists($file) && !is_writable($file)) {
            echo json_encode(array('ok'=>false, 'error'=>'not_writable'));
            exit;
        }
        if (!file_exists($file) && !is_writable($plugdir)) {
            echo json_encode(array('ok'=>false, 'error'=>'dir_not_writable'));
            exit;
        }
        $ok = @file_put_contents($file, $content);
        if ($ok === false) {
            echo json_encode(array('ok'=>false, 'error'=>'write_fail'));
            exit;
        }
        echo json_encode(array('ok'=>true, 'file'=>$file));
        exit;
    }

    private function is_safe_update_zip_archive(ZipArchive $zip): bool
    {
        for ($i = 0; $i < $zip->numFiles; $i++) {
            $stat = $zip->statIndex($i);
            if (!is_array($stat) || !isset($stat['name'])) {
                return false;
            }

            $name = (string) $stat['name'];
            if ($name === '' || strpos($name, "\0") !== false) {
                return false;
            }

            $normalized = str_replace('\\', '/', $name);
            if ($normalized[0] === '/' || preg_match('~^[A-Za-z]:/~', $normalized)) {
                return false;
            }

            $parts = explode('/', rtrim($normalized, '/'));
            foreach ($parts as $part) {
                if ($part === '' || $part === '.') {
                    continue;
                }
                if ($part === '..') {
                    return false;
                }
            }

            if (isset($stat['external_attributes_opsys'], $stat['external_attributes'])
                && (int) $stat['external_attributes_opsys'] === ZipArchive::OPSYS_UNIX) {
                $mode = ((int) $stat['external_attributes'] >> 16) & 0xF000;
                if ($mode === 0xA000) {
                    return false;
                }
            }
        }

        return true;
    }

    private function pm_cache_last_ts() {
        $ts = 0;
        if (is_readable($this->cache_file)) {
            $json = @json_decode(@file_get_contents($this->cache_file), true);
            if (is_array($json)) {
                foreach ($json as $k => $v) {
                    if (is_array($v) && isset($v['ts'])) {
                        $t = intval($v['ts']);
                        if ($t > $ts) $ts = $t;
                    }
                }
            }
        }
        return $ts;
    }

    private function pm_diag_probe_url($url, $headers = array())
    {
        $status = 0;
        $err = null;
        $body = $this->http_get2($url, $headers, $status, $err);

        return array(
            'url' => $url,
            'status' => (int) $status,
            'ok' => ($status >= 200 && $status < 400),
            'err' => $err,
            'len' => is_string($body) ? strlen($body) : 0,
        );
    }

    private function pm_collect_diagnostics()
    {
        $plugin_root = $this->plugins_root_dir();
        $temp_dir = $this->config ? $this->config->get('temp_dir', sys_get_temp_dir()) : sys_get_temp_dir();
        $headers = array('User-Agent: Roundcube-Plugin-Manager');
        if (!empty($this->gh_token)) {
            $headers[] = 'Authorization: token ' . $this->gh_token;
        }

        return array(
            'generated_at' => date('c'),
            'roundcube_version' => defined('RCMAIL_VERSION') ? RCMAIL_VERSION : (defined('RCUBE_VERSION') ? RCUBE_VERSION : 'unknown'),
            'plugin_version' => self::PLUGIN_VERSION,
            'remote_checks' => (bool) $this->remote_checks,
            'http_timeout' => (int) $this->timeout,
            'curl' => function_exists('curl_init'),
            'zip' => class_exists('ZipArchive'),
            'openssl' => extension_loaded('openssl'),
            'allow_url_fopen' => (bool) ini_get('allow_url_fopen'),
            'plugin_root' => $plugin_root,
            'plugin_root_exists' => ($plugin_root && is_dir($plugin_root)),
            'plugin_root_writable' => ($plugin_root && is_writable($plugin_root)),
            'cache_file' => $this->cache_file,
            'cache_dir_writable' => is_writable(dirname($this->cache_file)),
            'temp_dir' => $temp_dir,
            'temp_dir_writable' => is_dir($temp_dir) && is_writable($temp_dir),
            'github_token_configured' => ($this->gh_token !== ''),
            'packagist_probe' => $this->pm_diag_probe_url('https://repo.packagist.org/packages.json'),
            'github_probe' => $this->pm_diag_probe_url('https://api.github.com/rate_limit', $headers),
        );
    }

    private function pm_render_diagnostics()
    {
        $diag = $this->pm_collect_diagnostics();
        $summary_rows = array(
            array('label' => 'Generated', 'value' => $diag['generated_at']),
            array('label' => 'Roundcube', 'value' => $diag['roundcube_version']),
            array('label' => 'Plugin', 'value' => $diag['plugin_version']),
            array('label' => 'Remote checks', 'value' => $diag['remote_checks'] ? 'Enabled' : 'Disabled'),
            array('label' => 'HTTP timeout', 'value' => $diag['http_timeout'] . 's'),
            array('label' => 'cURL', 'value' => $diag['curl'] ? 'Available' : 'Missing'),
            array('label' => 'ZipArchive', 'value' => $diag['zip'] ? 'Available' : 'Missing'),
            array('label' => 'OpenSSL', 'value' => $diag['openssl'] ? 'Loaded' : 'Missing'),
            array('label' => 'allow_url_fopen', 'value' => $diag['allow_url_fopen'] ? 'On' : 'Off'),
            array('label' => 'GitHub token', 'value' => $diag['github_token_configured'] ? 'Configured' : 'Not set'),
        );

        $path_rows = array(
            array('label' => 'Plugin root', 'value' => $diag['plugin_root'] ?: 'not found'),
            array('label' => 'Plugin root writable', 'value' => $diag['plugin_root_writable'] ? 'Yes' : 'No'),
            array('label' => 'Cache file', 'value' => $diag['cache_file']),
            array('label' => 'Cache dir writable', 'value' => $diag['cache_dir_writable'] ? 'Yes' : 'No'),
            array('label' => 'Temp dir', 'value' => $diag['temp_dir']),
            array('label' => 'Temp dir writable', 'value' => $diag['temp_dir_writable'] ? 'Yes' : 'No'),
        );

        $probe_cards = '';
        foreach (array('packagist_probe' => 'Packagist', 'github_probe' => 'GitHub API') as $key => $label) {
            $probe = $diag[$key];
            $status_class = $probe['ok'] ? 'pm-diag-ok' : 'pm-diag-fail';
            $meta = 'HTTP ' . intval($probe['status']) . ($probe['err'] ? (' • ' . $probe['err']) : (' • ' . intval($probe['len']) . ' bytes'));
            $probe_cards .= '<div class="pm-diag-probe-card">'
                . '<div class="pm-diag-probe-head"><strong>' . rcube::Q($label) . '</strong><span class="' . $status_class . '">' . ($probe['ok'] ? 'OK' : 'Fail') . '</span></div>'
                . '<div class="pm-diag-url">' . rcube::Q($probe['url']) . '</div>'
                . '<div class="pm-diag-meta">' . rcube::Q($meta) . '</div>'
                . '</div>';
        }

        $render_rows = function ($rows) {
            $html = '';
            foreach ($rows as $row) {
                $html .= '<div class="pm-diag-item"><span class="pm-diag-label">' . rcube::Q($row['label']) . '</span><span class="pm-diag-value">' . rcube::Q($row['value']) . '</span></div>';
            }
            return $html;
        };

        return '<div class="pm-diag-card">'
            . '<div class="pm-diag-card-head"><h3>' . rcube::Q($this->gettext('conn_diag') ?: 'Connectivity diagnostics') . '</h3><span class="pm-diag-pill">' . rcube::Q($this->gettext('diag_running') ?: 'Diagnostics Running') . '</span></div>'
            . '<div class="pm-diag-grid">'
            . '<div class="pm-diag-section"><div class="pm-diag-section-title">Environment</div>' . $render_rows($summary_rows) . '</div>'
            . '<div class="pm-diag-section"><div class="pm-diag-section-title">Paths</div>' . $render_rows($path_rows) . '</div>'
            . '</div>'
            . '<div class="pm-diag-probes">' . $probe_cards . '</div>'
            . '</div>';
    }

    private function sanitize_selected_plugins($selected)
    {
        if ($selected === null || $selected === '') {
            return array();
        }

        if (!is_array($selected)) {
            $selected = explode(',', (string) $selected);
        }

        $out = array();
        foreach ($selected as $item) {
            $item = trim((string) $item);
            if ($item === '' || !preg_match('/^[A-Za-z0-9_.-]+$/', $item)) {
                continue;
            }
            $out[$item] = true;
        }

        return array_keys($out);
    }

    private function resolve_live_plugin_dir(string $plugin): ?string
    {
        $root = $this->plugins_root_dir();
        if (!$root || !preg_match('/^[A-Za-z0-9_.-]+$/', $plugin)) {
            return null;
        }

        $candidate = $root . DIRECTORY_SEPARATOR . $plugin;
        if (is_link($candidate) || !is_dir($candidate)) {
            return null;
        }

        $real_root = realpath($root);
        $real_candidate = realpath($candidate);
        if (!$real_root || !$real_candidate) {
            return null;
        }

        $prefix = rtrim($real_root, DIRECTORY_SEPARATOR) . DIRECTORY_SEPARATOR;
        if (strpos($real_candidate . DIRECTORY_SEPARATOR, $prefix) !== 0) {
            return null;
        }

        return $real_candidate;
    }

    private function find_plugin_backup_dirs(string $plugin): array
    {
        $root = $this->plugins_root_dir();
        $live_dir = $this->resolve_live_plugin_dir($plugin);
        if (!$root || $live_dir === null) {
            return array();
        }

        $paths = array();
        foreach ((array) @scandir($root) as $entry) {
            if ($entry === '.' || $entry === '..') {
                continue;
            }

            $candidate = $root . DIRECTORY_SEPARATOR . $entry;
            if ($this->is_valid_plugin_backup_dir($plugin, $candidate)) {
                $paths[] = realpath($candidate);
            }
        }

        sort($paths, SORT_STRING);
        return array_values(array_unique(array_filter($paths)));
    }

    private function is_valid_plugin_backup_dir(string $plugin, string $path): bool
    {
        $root = $this->plugins_root_dir();
        $live_dir = $this->resolve_live_plugin_dir($plugin);
        if (!$root || $live_dir === null || !preg_match('/^[A-Za-z0-9_.-]+$/', $plugin)) {
            return false;
        }

        $basename = basename($path);
        $pattern = '/^' . preg_quote($plugin, '/') . '\.bak-\d{8}-\d{6}$/';
        if (!preg_match($pattern, $basename)) {
            return false;
        }

        if (is_link($path) || !is_dir($path)) {
            return false;
        }

        $real_root = realpath($root);
        $real_path = realpath($path);
        if (!$real_root || !$real_path || !is_dir($real_path)) {
            return false;
        }

        $prefix = rtrim($real_root, DIRECTORY_SEPARATOR) . DIRECTORY_SEPARATOR;
        if (strpos($real_path . DIRECTORY_SEPARATOR, $prefix) !== 0) {
            return false;
        }

        if ($real_path === $live_dir) {
            return false;
        }

        return true;
    }

    private function delete_directory_recursive(string $path): bool
    {
        if (is_link($path) || !is_dir($path)) {
            return false;
        }

        $real_path = realpath($path);
        if (!$real_path || !is_dir($real_path) || is_link($real_path)) {
            return false;
        }

        $scan = new RecursiveIteratorIterator(
            new RecursiveDirectoryIterator($real_path, FilesystemIterator::SKIP_DOTS),
            RecursiveIteratorIterator::SELF_FIRST
        );
        foreach ($scan as $item) {
            if ($item->isLink()) {
                return false;
            }
        }

        $delete = new RecursiveIteratorIterator(
            new RecursiveDirectoryIterator($real_path, FilesystemIterator::SKIP_DOTS),
            RecursiveIteratorIterator::CHILD_FIRST
        );
        foreach ($delete as $item) {
            $target = $item->getPathname();
            $ok = $item->isDir() ? @rmdir($target) : @unlink($target);
            if (!$ok) {
                return false;
            }
        }

        return @rmdir($real_path);
    }

    private function update_all_outdated($dry = false, array $selected = array())
    {
        $result = array('ok'=>0,'fail'=>0,'skipped'=>array(),'advisories'=>array(),'hooks'=>array());
        $selected_lookup = array();
        foreach ($selected as $name) {
            $selected_lookup[(string) $name] = true;
        }
        $plugins = $this->discover_plugins();
        foreach ($plugins as $info) {
            $dir = $info['dir'];
            $base = basename($dir);
            if (!empty($selected_lookup) && empty($selected_lookup[$base])) {
                continue;
            }
            $policy = $this->policy_for($base);
            if (!empty($policy['ignored']['bulk'])) {
                $result['skipped'][] = array('dir'=>$base,'reason'=>'ignored_bulk');
                continue;
            }
            if (preg_match('/\.bak-\d{8}-\d{6}$/', $dir)) {
                $result['skipped'][] = array('dir'=>$base,'reason'=>'backup_dir');
                continue;
            }
            $meta = $this->read_plugin_meta($dir);
            $sources = $this->build_sources($meta);
            if (!empty($sources['bundled'])) {
                $result['skipped'][] = array('dir'=>$base,'reason'=>'bundled');
                continue;
            }
            if (empty($sources['composer_name']) && empty($sources['github'])) {
                $result['skipped'][] = array('dir'=>$base,'reason'=>'no_sources');
                continue;
            }
            $local = $this->detect_local_version($dir, $meta);
            $remote = $this->latest_version_cached($sources, true);
            if (!$remote) {
                $result['skipped'][] = array('dir'=>$base,'reason'=>'no_remote_version');
                continue;
            }
            if ($this->compare_versions($local, $remote) >= 0) {
                $result['skipped'][] = array('dir'=>$base,'reason'=>'up_to_date');
                continue;
            }
            if ($dry) {
                $result['skipped'][] = array('dir'=>$base,'reason'=>'dry','from'=>$local,'to'=>$remote);
                continue;
            }
            try {
                $ok = $this->perform_update($base);
                if (is_array($ok) && !empty($ok['ok'])) {
                    $result['ok']++;
                    if (!empty($ok['advisory']) && is_array($ok['advisory']) && ($ok['advisory']['status'] ?? 'none') !== 'none') {
                        $result['advisories'][] = $ok['advisory'];
                    }
                    if (!empty($ok['hook']) && is_array($ok['hook']) && ($ok['hook']['status'] ?? 'none') !== 'none') {
                        $result['hooks'][] = $ok['hook'];
                    }
                }
                else $result['fail']++;
            } catch (Exception $e) {
                $result['fail']++;
            }
        }
        return $result;
    }

    private function inspect_post_update_requirements(string $plugin): array
    {
        $plugin_path = $this->resolve_live_plugin_dir($plugin);
        if ($plugin_path === null) {
            return array(
                'status' => 'none',
                'plugin' => $plugin,
                'artifacts_found' => array(),
                'composer_signals' => array(),
                'message' => '',
                'details' => array(),
            );
        }

        $artifacts = $this->scan_plugin_upgrade_artifacts($plugin_path);
        $composer_signals = $this->inspect_plugin_composer_signals($plugin_path);

        return $this->build_post_update_advisory($artifacts, $composer_signals, $plugin);
    }

    private function scan_plugin_upgrade_artifacts(string $plugin_path): array
    {
        $resolved = $this->validate_plugin_inspection_path($plugin_path);
        if ($resolved === null) {
            return array();
        }

        $targets = array(
            'sql' => 'warning',
            'db' => 'warning',
            'database' => 'warning',
            'migrations' => 'warning',
            'updates' => 'warning',
            'upgrade' => 'warning',
            'upgrade.md' => 'warning',
            'upgrade.txt' => 'warning',
            'upgrading' => 'warning',
            'upgrading.md' => 'warning',
            'upgrading.txt' => 'warning',
            'install' => 'warning',
            'install.md' => 'warning',
            'install.txt' => 'warning',
            'changelog' => 'info',
            'changelog.md' => 'info',
            'readme' => 'info',
            'readme.md' => 'info',
        );

        $found = array();
        $iterator = new RecursiveIteratorIterator(
            new RecursiveDirectoryIterator($resolved, FilesystemIterator::SKIP_DOTS),
            RecursiveIteratorIterator::SELF_FIRST
        );

        foreach ($iterator as $item) {
            if ($iterator->getDepth() > 2 || $item->isLink()) {
                continue;
            }

            $name = strtolower($item->getBasename());
            if (!isset($targets[$name])) {
                continue;
            }

            $path = $item->getPathname();
            $real = realpath($path);
            if (!$real || strpos($real . DIRECTORY_SEPARATOR, $resolved . DIRECTORY_SEPARATOR) !== 0) {
                continue;
            }

            $relative = ltrim(substr($real, strlen($resolved)), DIRECTORY_SEPARATOR);
            if ($relative === '') {
                $relative = basename($real);
            }

            $key = strtolower($relative);
            $existing = $found[$key] ?? null;
            if ($existing === null || ($targets[$name] === 'warning' && $existing['severity'] !== 'warning')) {
                $found[$key] = array(
                    'path' => str_replace(DIRECTORY_SEPARATOR, '/', $relative),
                    'severity' => $targets[$name],
                    'kind' => $item->isDir() ? 'dir' : 'file',
                );
            }
        }

        usort($found, function ($a, $b) {
            if ($a['severity'] !== $b['severity']) {
                return $a['severity'] === 'warning' ? -1 : 1;
            }

            return strcmp($a['path'], $b['path']);
        });

        return array_values($found);
    }

    private function inspect_plugin_composer_signals(string $plugin_path): array
    {
        $resolved = $this->validate_plugin_inspection_path($plugin_path);
        if ($resolved === null) {
            return array();
        }

        $composer_file = $resolved . DIRECTORY_SEPARATOR . 'composer.json';
        if (!is_file($composer_file) || is_link($composer_file) || !is_readable($composer_file)) {
            return array();
        }

        $raw = @file_get_contents($composer_file);
        if (!is_string($raw) || $raw === '') {
            return array();
        }

        $json = json_decode($raw, true);
        if (!is_array($json)) {
            return array(
                array(
                    'signal' => 'composer.json unreadable or malformed',
                    'severity' => 'info',
                ),
            );
        }

        $signals = array();
        $script_patterns = array(
            '/\b(post-install|post-update|install|update|migrat|schema|database|sql|upgrade)\b/i',
            '/\b(seed|setup)\b/i',
        );

        if (!empty($json['scripts']) && is_array($json['scripts'])) {
            foreach ($json['scripts'] as $event => $handlers) {
                $matched = preg_match('/\b(post-install|post-update|install|update)\b/i', (string) $event) === 1;
                $handlers = is_array($handlers) ? $handlers : array($handlers);

                foreach ($handlers as $handler) {
                    $handler = is_scalar($handler) ? (string) $handler : '';
                    if ($handler === '') {
                        continue;
                    }

                    foreach ($script_patterns as $pattern) {
                        if ($matched || preg_match($pattern, $handler)) {
                            $signals[] = array(
                                'signal' => 'composer script: ' . $event,
                                'severity' => 'warning',
                            );
                            break 2;
                        }
                    }
                }
            }
        }

        foreach (array('suggest', 'extra') as $key) {
            if (empty($json[$key])) {
                continue;
            }

            $encoded = json_encode($json[$key]);
            if (!is_string($encoded) || !preg_match('/\b(migrat|schema|database|sql|upgrade|install|setup)\b/i', $encoded)) {
                continue;
            }

            $signals[] = array(
                'signal' => 'composer ' . $key . ' mentions upgrade/setup',
                'severity' => $key === 'extra' ? 'warning' : 'info',
            );
        }

        return $signals;
    }

    private function build_post_update_advisory(array $artifacts, array $composer_signals, string $plugin): array
    {
        $status = 'none';
        $details = array();

        foreach ($artifacts as $artifact) {
            $details[] = 'Artifact: ' . $artifact['path'];
            if (($artifact['severity'] ?? 'info') === 'warning') {
                $status = 'warning';
            } elseif ($status === 'none') {
                $status = 'info';
            }
        }

        foreach ($composer_signals as $signal) {
            $details[] = $signal['signal'];
            if (($signal['severity'] ?? 'info') === 'warning') {
                $status = 'warning';
            } elseif ($status === 'none') {
                $status = 'info';
            }
        }

        $message = '';
        if ($status === 'warning') {
            $message = $this->gettext('post_update_advisory_warning')
                ?: 'Plugin updated successfully. Manual database or upgrade steps may be required.';
        } elseif ($status === 'info') {
            $message = $this->gettext('post_update_advisory_info')
                ?: 'Upgrade notes detected for this plugin. Review plugin documentation before using it.';
        }

        return array(
            'status' => $status,
            'plugin' => $plugin,
            'artifacts_found' => array_values(array_map(function ($artifact) {
                return $artifact['path'];
            }, $artifacts)),
            'composer_signals' => array_values(array_map(function ($signal) {
                return $signal['signal'];
            }, $composer_signals)),
            'message' => $message,
            'details' => $details,
        );
    }

    private function flash_post_update_advisory(array $advisory): void
    {
        $status = isset($advisory['status']) ? (string) $advisory['status'] : 'none';
        if ($status === 'none') {
            return;
        }

        $plugin = isset($advisory['plugin']) ? (string) $advisory['plugin'] : '';
        $message = isset($advisory['message']) ? trim((string) $advisory['message']) : '';
        if ($message === '') {
            return;
        }

        $type = $status === 'warning' ? 'warning' : 'notice';
        $prefix = $plugin !== '' ? ($plugin . ': ') : '';
        $this->flash_add($prefix . $message, $type);

        $details = array();
        if (!empty($advisory['artifacts_found']) && is_array($advisory['artifacts_found'])) {
            $details[] = 'Artifacts: ' . implode(', ', array_slice($advisory['artifacts_found'], 0, 8));
        }
        if (!empty($advisory['composer_signals']) && is_array($advisory['composer_signals'])) {
            $details[] = 'Composer: ' . implode(', ', array_slice($advisory['composer_signals'], 0, 4));
        }
        if (!empty($details)) {
            $this->flash_add($prefix . implode(' | ', $details), 'notice');
        }
    }

    private function get_post_update_hook_config(string $plugin): ?array
    {
        if (!preg_match('/^[A-Za-z0-9_.-]+$/', $plugin)) {
            return null;
        }

        if (!isset($this->post_update_hooks[$plugin]) || !is_array($this->post_update_hooks[$plugin])) {
            return null;
        }

        return $this->post_update_hooks[$plugin];
    }

    private function is_valid_internal_hook_relative_path(string $path): bool
    {
        if ($path === '' || strlen($path) > 255) {
            return false;
        }

        if ($path[0] === '/' || $path[0] === '\\') {
            return false;
        }

        if (preg_match('/(^|[\/\\\\])\.\.([\/\\\\]|$)/', $path)) {
            return false;
        }

        return preg_match('/^[A-Za-z0-9._\/-]+$/', $path) === 1;
    }

    private function resolve_internal_post_update_hook_file(string $plugin, string $path): ?string
    {
        if (!preg_match('/^[A-Za-z0-9_.-]+$/', $plugin)) {
            return null;
        }

        if (!$this->is_valid_internal_hook_relative_path($path)) {
            return null;
        }

        $base = __DIR__ . DIRECTORY_SEPARATOR . 'webhooks' . DIRECTORY_SEPARATOR . $plugin;
        if (is_link($base) || !is_dir($base) || !is_readable($base)) {
            return null;
        }

        $resolved_base = realpath($base);
        if (!$resolved_base || is_link($resolved_base)) {
            return null;
        }

        $candidate = $resolved_base . DIRECTORY_SEPARATOR . str_replace(array('/', '\\'), DIRECTORY_SEPARATOR, $path);
        if (is_link($candidate) || !file_exists($candidate) || !is_file($candidate) || !is_readable($candidate)) {
            return null;
        }

        $resolved = realpath($candidate);
        if (!$resolved || is_link($resolved)) {
            return null;
        }

        $prefix = rtrim($resolved_base, DIRECTORY_SEPARATOR) . DIRECTORY_SEPARATOR;
        if (strpos($resolved, $prefix) !== 0) {
            return null;
        }

        return $resolved;
    }

    private function preflight_post_update_hook(string $plugin, string $event): array
    {
        $result = array(
            'ok' => false,
            'state' => 'none',
            'plugin' => $plugin,
            'event' => $event,
            'reasons' => array(),
            'warnings' => array(),
            'hook' => null,
            'hook_file' => null,
            'hook_path' => '',
            'plugin_path' => null,
        );

        if (!preg_match('/^[A-Za-z0-9_.-]+$/', $plugin)) {
            $result['state'] = 'blocked';
            $result['reasons'][] = 'Invalid plugin name.';
            return $result;
        }

        $hook = $this->get_post_update_hook_config($plugin);
        if ($hook === null) {
            return $result;
        }

        $result['state'] = 'blocked';
        $result['hook'] = $hook;

        if (empty($hook['enabled'])) {
            $result['reasons'][] = 'Hook is disabled.';
            return $result;
        }

        if (strtolower((string) ($hook['type'] ?? '')) !== 'internal') {
            $result['reasons'][] = 'Unsupported hook type.';
            return $result;
        }

        $plugin_path = $this->resolve_live_plugin_dir($plugin);
        if ($plugin_path === null) {
            $result['reasons'][] = 'Plugin directory is not valid.';
            return $result;
        }
        $result['plugin_path'] = $plugin_path;

        if ($event === 'manual' && isset($hook['allow_manual_run']) && !$hook['allow_manual_run']) {
            $result['reasons'][] = 'Manual run is not allowed.';
            return $result;
        }

        if (!$this->should_run_post_update_hook($hook, $event)) {
            $result['reasons'][] = 'Hook is not configured for the ' . $event . ' event.';
            return $result;
        }

        $hook_path = isset($hook['path']) ? trim((string) $hook['path']) : '';
        $result['hook_path'] = $hook_path;
        if (!$this->is_valid_internal_hook_relative_path($hook_path)) {
            $result['reasons'][] = 'Hook path is invalid.';
            return $result;
        }

        $hook_file = $this->resolve_internal_post_update_hook_file($plugin, $hook_path);
        if ($hook_file === null) {
            $result['reasons'][] = 'Hook file is not available under plugin_manager/webhooks.';
            return $result;
        }

        if ($event !== 'manual' && !empty($hook['require_confirmation'])) {
            $result['warnings'][] = 'Hook requires manual confirmation before automatic runs.';
        }

        $result['ok'] = true;
        $result['state'] = 'available';
        $result['hook_file'] = $hook_file;
        return $result;
    }

    private function should_run_post_update_hook(array $hook, string $event): bool
    {
        $run_on = isset($hook['run_on']) ? $hook['run_on'] : array('update');
        if (!is_array($run_on)) {
            $run_on = array($run_on);
        }

        $allowed = array();
        foreach ($run_on as $value) {
            $value = strtolower(trim((string) $value));
            if ($value === 'install' || $value === 'update' || $value === 'manual') {
                $allowed[$value] = true;
            }
        }

        return isset($allowed[strtolower($event)]);
    }

    private function can_plugin_run_manual_maintenance(string $plugin): bool
    {
        $preflight = $this->preflight_post_update_hook($plugin, 'manual');
        return !empty($preflight['ok']);
    }

    private function should_show_manual_maintenance_link(string $plugin): bool
    {
        if (!$this->can_plugin_run_manual_maintenance($plugin)) {
            return false;
        }

        $hook = $this->get_post_update_hook_config($plugin);
        if (!is_array($hook)) {
            return false;
        }

        if (!empty($hook['require_confirmation'])) {
            return true;
        }

        return !empty($hook['show_manual_link']);
    }

    private function get_plugin_maintenance_state(string $plugin): array
    {
        $preflight = $this->preflight_post_update_hook($plugin, 'manual');
        $latest = $this->get_latest_maintenance_audit_for_plugin($plugin);

        if (!empty($preflight['ok'])) {
            if (!empty($latest) && !empty($latest['result']) && in_array($latest['result'], array('success', 'warning'), true) && !empty($latest['ts']) && ((time() - (int) $latest['ts']) < 86400)) {
                return array('state' => 'ran_recently', 'reasons' => array(), 'warnings' => array('Maintenance ran recently.'));
            }
            return array('state' => 'available', 'reasons' => array(), 'warnings' => $preflight['warnings']);
        }

        if (($preflight['state'] ?? 'none') === 'blocked') {
            return array('state' => 'blocked', 'reasons' => $preflight['reasons'], 'warnings' => $preflight['warnings']);
        }

        return array('state' => 'none', 'reasons' => array(), 'warnings' => array());
    }

    private function get_plugin_maintenance_badge_data(string $plugin): array
    {
        $state = $this->get_plugin_maintenance_state($plugin);
        $badge = array(
            'state' => $state['state'],
            'label' => '',
            'title' => '',
        );

        $labels = array(
            'available' => $this->gettext('maintenance_status_available') ?: 'Available',
            'blocked' => $this->gettext('maintenance_status_blocked') ?: 'Blocked',
            'ran_recently' => $this->gettext('maintenance_status_ran_recently') ?: 'Ran recently',
        );

        if ($badge['state'] !== 'none' && isset($labels[$badge['state']])) {
            $badge['label'] = $labels[$badge['state']];
        }

        $parts = array();
        if (!empty($state['reasons'])) {
            $parts[] = implode(' ', $state['reasons']);
        }
        if (!empty($state['warnings'])) {
            $parts[] = implode(' ', array_slice($state['warnings'], 0, 3));
        }
        if (empty($parts) && $badge['state'] === 'available') {
            $parts[] = $this->gettext('maintenance_status_available_title') ?: 'Post-updates are enabled for this plugin.';
        }
        $badge['title'] = implode(' ', $parts);

        return $badge;
    }

    private function build_manual_maintenance_context(string $plugin): array
    {
        $plugin_path = $this->resolve_live_plugin_dir($plugin);
        $current_version = null;
        if ($plugin_path !== null) {
            try {
                $meta = $this->read_plugin_meta($plugin_path);
                $current_version = $this->detect_local_version($plugin_path, $meta);
            } catch (Exception $e) {
                $current_version = null;
            }
        }

        return array(
            'plugin' => $plugin,
            'plugin_path' => $plugin_path,
            'event' => 'manual',
            'previous_version' => null,
            'current_version' => $current_version,
            'request_time' => time(),
        );
    }

    private function run_allowlisted_post_update_hook(string $plugin, string $event, array $context = array()): array
    {
        $result = array(
            'ok' => false,
            'status' => 'none',
            'message' => '',
            'details' => array(),
            'plugin' => $plugin,
            'event' => $event,
            'executed' => false,
        );

        $this->log_debug('post_update_hook_consider', array('plugin' => $plugin, 'event' => $event));

        if (!$this->is_update_admin() || !$this->request_token_valid()) {
            $this->log_debug('post_update_hook_refused', array('plugin' => $plugin, 'reason' => 'auth'));
            $result['status'] = 'warning';
            $result['message'] = $this->gettext('post_update_hook_refused_auth') ?: 'Post-update hook refused: authorization failed.';
            $result['audit_result'] = 'refused';
            return $result;
        }

        $preflight = $this->preflight_post_update_hook($plugin, $event);
        if (($preflight['state'] ?? 'none') === 'none') {
            return $result;
        }

        if (empty($preflight['ok'])) {
            $this->log_debug('post_update_hook_refused', array('plugin' => $plugin, 'reason' => implode('; ', $preflight['reasons'] ?? array())));
            $result['status'] = 'warning';
            $result['message'] = !empty($preflight['reasons']) ? implode(' ', $preflight['reasons']) : ($this->gettext('post_update_hook_refused_path') ?: 'Post-update hook refused: invalid hook path.');
            $result['details'] = $preflight['warnings'] ?? array();
            $result['audit_result'] = 'refused';
            $this->record_maintenance_audit(array(
                'plugin' => $plugin,
                'event' => $event,
                'result' => 'refused',
                'message' => $result['message'],
                'current_version' => $context['current_version'] ?? null,
                'previous_version' => $context['previous_version'] ?? null,
                'hook_summary' => $preflight['hook_path'] ?? '',
            ));
            return $result;
        }

        $hook = $preflight['hook'];
        if ($event !== 'manual' && !empty($hook['require_confirmation'])) {
            $this->log_debug('post_update_hook_skip', array('plugin' => $plugin, 'reason' => 'confirmation_required'));
            $result['status'] = 'notice';
            $result['message'] = $this->gettext('post_update_hook_confirmation_required') ?: 'Post-update hook available but not run because confirmation is required.';
            $result['audit_result'] = 'skipped';
            $this->record_maintenance_audit(array(
                'plugin' => $plugin,
                'event' => $event,
                'result' => 'skipped',
                'message' => $result['message'],
                'current_version' => $context['current_version'] ?? null,
                'previous_version' => $context['previous_version'] ?? null,
                'hook_summary' => $preflight['hook_path'] ?? '',
            ));
            return $result;
        }

        $hook_file = $preflight['hook_file'];
        $hook_path = isset($preflight['hook_path']) ? (string) $preflight['hook_path'] : '';

        $timeout = isset($hook['timeout']) ? (int) $hook['timeout'] : 0;
        if ($timeout > 0) {
            $this->log_debug('post_update_hook_timeout_reserved', array('plugin' => $plugin, 'timeout' => $timeout));
        }

        $hook_context = array(
            'plugin' => $plugin,
            'plugin_path' => $preflight['plugin_path'],
            'event' => $event,
            'previous_version' => $context['previous_version'] ?? null,
            'current_version' => $context['current_version'] ?? null,
            'request_time' => time(),
        );

        $this->log_debug('post_update_hook_execute', array(
            'plugin' => $plugin,
            'event' => $event,
            'hook_file' => $hook_file,
        ));

        try {
            $hook_result = $this->execute_internal_post_update_hook($hook_file, $hook_context);
            $hook_result['plugin'] = $plugin;
            $hook_result['event'] = $event;
            $hook_result['executed'] = true;
            $hook_result['path'] = $hook_path;
            $this->log_debug('post_update_hook_complete', array(
                'plugin' => $plugin,
                'ok' => $hook_result['ok'],
                'status' => $hook_result['status'],
                'message' => $hook_result['message'],
                'path' => $hook_path,
            ));
            $audit_result = !empty($hook_result['ok']) ? 'success' : 'failure';
            if (($hook_result['status'] ?? '') === 'notice') {
                $audit_result = 'warning';
            }
            $this->record_maintenance_audit(array(
                'plugin' => $plugin,
                'event' => $event,
                'result' => $audit_result,
                'message' => $hook_result['message'],
                'current_version' => $context['current_version'] ?? null,
                'previous_version' => $context['previous_version'] ?? null,
                'hook_summary' => $hook_path,
            ));

            return $hook_result;
        } catch (Throwable $e) {
            $this->log_debug('post_update_hook_failed', array(
                'plugin' => $plugin,
                'path' => $hook_path,
                'error' => $e->getMessage(),
            ));

            $this->record_maintenance_audit(array(
                'plugin' => $plugin,
                'event' => $event,
                'result' => 'failure',
                'message' => $e->getMessage(),
                'current_version' => $context['current_version'] ?? null,
                'previous_version' => $context['previous_version'] ?? null,
                'hook_summary' => $hook_path,
            ));

            return array(
                'ok' => false,
                'status' => 'warning',
                'message' => $this->gettext('post_update_hook_failed') ?: 'Plugin updated successfully, but the post-update hook failed.',
                'details' => array($e->getMessage()),
                'plugin' => $plugin,
                'event' => $event,
                'executed' => true,
            );
        }
    }

    private function execute_internal_post_update_hook(string $hook_file, array $context): array
    {
        if (is_link($hook_file) || !is_file($hook_file) || !is_readable($hook_file)) {
            throw new RuntimeException('Hook file is not readable.');
        }

        $hook = (static function (string $file) {
            return require $file;
        })($hook_file);

        if (is_array($hook) && isset($hook['callable']) && is_callable($hook['callable'])) {
            $hook = $hook['callable'];
        }

        if (!is_callable($hook)) {
            throw new RuntimeException('Hook file did not return a callable.');
        }

        $result = $hook($context);

        return $this->normalize_post_update_hook_result($result);
    }

    private function normalize_post_update_hook_result($result): array
    {
        if (!is_array($result)) {
            throw new RuntimeException('Hook result must be an array.');
        }

        if (!array_key_exists('ok', $result)) {
            throw new RuntimeException('Hook result missing ok flag.');
        }

        $ok = (bool) $result['ok'];
        $message = isset($result['message']) ? trim((string) $result['message']) : '';
        $details = isset($result['details']) && is_array($result['details']) ? $result['details'] : array();
        $normalized_details = array();
        foreach ($details as $detail) {
            if (is_scalar($detail) || (is_object($detail) && method_exists($detail, '__toString'))) {
                $text = trim((string) $detail);
                if ($text !== '') {
                    $normalized_details[] = $text;
                }
            }
        }

        return array(
            'ok' => $ok,
            'status' => $ok ? 'confirmation' : 'warning',
            'message' => $message !== '' ? $message : ($ok
                ? ($this->gettext('post_update_hook_completed') ?: 'Plugin updated successfully. Post-update hook completed.')
                : ($this->gettext('post_update_hook_failed') ?: 'Plugin updated successfully, but the post-update hook failed.')),
            'details' => $normalized_details,
        );
    }

    private function flash_post_update_hook_result(array $result, string $plugin): void
    {
        $status = isset($result['status']) ? (string) $result['status'] : 'none';
        if ($status === 'none') {
            return;
        }

        $message = isset($result['message']) ? trim((string) $result['message']) : '';
        if ($message === '') {
            return;
        }

        $type_map = array(
            'confirmation' => 'confirmation',
            'notice' => 'notice',
            'warning' => 'warning',
        );
        $type = $type_map[$status] ?? 'notice';
        $prefix = $plugin !== '' ? ($plugin . ': ') : '';
        $this->flash_add($prefix . $message, $type);

        if (!empty($result['details']) && is_array($result['details'])) {
            $detail_list = array_slice($result['details'], 0, 4);
            $detail_text = implode(' | ', $detail_list);
            if (count($result['details']) > count($detail_list)) {
                $detail_text .= ' | +' . (count($result['details']) - count($detail_list)) . ' more';
            }
            $this->flash_add($prefix . $detail_text, 'notice');
        }
    }

    private function flash_manual_maintenance_result(array $result, string $plugin): void
    {
        $status = isset($result['status']) ? (string) $result['status'] : 'warning';
        $ok = !empty($result['ok']);
        $details = isset($result['details']) && is_array($result['details']) ? $result['details'] : array();

        if ($ok) {
            $message = sprintf($this->gettext('maintenance_success') ?: 'Maintenance completed for plugin %s.', $plugin);
            $type = 'confirmation';
        } else {
            $base_message = sprintf($this->gettext('maintenance_failure') ?: 'Maintenance failed for plugin %s.', $plugin);
            $message = isset($result['message']) && trim((string) $result['message']) !== ''
                ? ($base_message . ' ' . trim((string) $result['message']))
                : $base_message;
            $type = $status === 'notice' ? 'notice' : 'warning';
        }

        $this->flash_add($message, $type);

        if (!empty($details)) {
            $detail_list = array_slice($details, 0, 4);
            $detail_text = implode(' | ', $detail_list);
            if (count($details) > count($detail_list)) {
                $detail_text .= ' | +' . (count($details) - count($detail_list)) . ' more';
            }
            $this->flash_add($plugin . ': ' . $detail_text, 'notice');
        }
    }

    private function get_manual_maintenance_label(string $plugin, array $hook): string
    {
        $label = isset($hook['label']) ? trim((string) $hook['label']) : '';
        if ($label !== '') {
            return $label;
        }

        return $this->gettext('run_maintenance') ?: 'Run maintenance';
    }

    private function record_maintenance_audit(array $entry): void
    {
        if (!$this->maintenance_audit_enabled || !$this->maintenance_audit_file) {
            return;
        }

        $row = array(
            'ts' => isset($entry['ts']) ? (int) $entry['ts'] : time(),
            'plugin' => isset($entry['plugin']) ? (string) $entry['plugin'] : '',
            'event' => isset($entry['event']) ? (string) $entry['event'] : '',
            'result' => isset($entry['result']) ? (string) $entry['result'] : '',
            'message' => isset($entry['message']) ? trim((string) $entry['message']) : '',
            'current_version' => isset($entry['current_version']) ? (string) $entry['current_version'] : '',
            'previous_version' => isset($entry['previous_version']) ? (string) $entry['previous_version'] : '',
            'hook_summary' => isset($entry['hook_summary']) ? (string) $entry['hook_summary'] : '',
        );

        $history = $this->get_recent_maintenance_audit($this->maintenance_audit_limit);
        array_unshift($history, $row);
        $history = array_slice($history, 0, $this->maintenance_audit_limit);
        $written = @file_put_contents($this->maintenance_audit_file, json_encode($history, JSON_PRETTY_PRINT | JSON_UNESCAPED_SLASHES), LOCK_EX);
        if ($written === false) {
            $this->log_debug('maintenance_audit_write_failed', array('file' => $this->maintenance_audit_file));
        }
    }

    private function get_recent_maintenance_audit(int $limit = 20): array
    {
        if (!$this->maintenance_audit_file || !is_file($this->maintenance_audit_file) || !is_readable($this->maintenance_audit_file)) {
            return array();
        }

        $raw = @file_get_contents($this->maintenance_audit_file);
        $json = json_decode((string) $raw, true);
        if (!is_array($json)) {
            return array();
        }

        return array_slice($json, 0, max(1, $limit));
    }

    private function get_latest_maintenance_audit_for_plugin(string $plugin): ?array
    {
        foreach ($this->get_recent_maintenance_audit($this->maintenance_audit_limit) as $entry) {
            if (!empty($entry['plugin']) && (string) $entry['plugin'] === $plugin) {
                return $entry;
            }
        }

        return null;
    }

    private function render_maintenance_activity_panel(): string
    {
        $items = $this->get_recent_maintenance_audit(12);
        if (empty($items)) {
            return '';
        }

        $html = '<div class="pm-maint-activity"><h3>' . rcube::Q($this->gettext('maintenance_recent_activity') ?: 'Recent maintenance activity') . '</h3>';
        $html .= '<table><thead><tr>'
            . '<th>' . rcube::Q($this->gettext('last_checked') ?: 'Time') . '</th>'
            . '<th>' . rcube::Q($this->gettext('plugin') ?: 'Plugin') . '</th>'
            . '<th>' . rcube::Q($this->gettext('status') ?: 'Status') . '</th>'
            . '<th>' . rcube::Q($this->gettext('details') ?: 'Details') . '</th>'
            . '</tr></thead><tbody>';

        foreach ($items as $item) {
            $result = isset($item['result']) ? (string) $item['result'] : 'skipped';
            $message = isset($item['message']) ? (string) $item['message'] : '';
            $event = isset($item['event']) ? (string) $item['event'] : '';
            $plugin = isset($item['plugin']) ? (string) $item['plugin'] : '';
            $ts = !empty($item['ts']) ? date('Y-m-d H:i:s', (int) $item['ts']) : '';
            $html .= '<tr>'
                . '<td>' . rcube::Q($ts) . '</td>'
                . '<td>' . rcube::Q($plugin) . '<div class="hint">' . rcube::Q($event) . '</div></td>'
                . '<td><span class="pm-maint-result pm-maint-result-' . rcube::Q($result) . '">' . rcube::Q($result) . '</span></td>'
                . '<td>' . rcube::Q($message) . '</td>'
                . '</tr>';
        }

        $html .= '</tbody></table></div>';
        return $html;
    }

    private function validate_plugin_inspection_path(string $plugin_path): ?string
    {
        if ($plugin_path === '' || is_link($plugin_path) || !is_dir($plugin_path)) {
            return null;
        }

        $real_plugin = realpath($plugin_path);
        $real_root = $this->plugins_root_dir();
        if (!$real_plugin || !$real_root) {
            return null;
        }

        $prefix = rtrim($real_root, DIRECTORY_SEPARATOR) . DIRECTORY_SEPARATOR;
        if (strpos($real_plugin . DIRECTORY_SEPARATOR, $prefix) !== 0) {
            return null;
        }

        return $real_plugin;
    }


/**
 * Load sources map from sources.map.php (plugin root or config/) with caching.
 * The file should return an associative array mapping source keys to definitions.
 */
private function get_sources_map(): array
{
    static $cache = null;
    if ($cache !== null) {
        return $cache;
    }
    $file = __DIR__ . '/sources.map.php';
    if (is_readable($file)) {
        $map = include $file;
        if (is_array($map)) {
            $cache = $map;
            return $cache;
        }
    }
    return $cache ?? [];
}
    

/**
 * Public accessor for sources map for use across plugin components/templates.
 */
public function get_sources(): array
{
    return $this->get_sources_map();
}
}