class.QuickButtonsPlugin.php

<?php
/**
 * Quick Buttons Plugin - Main Class
 *
 * @author  ChesnoTech
 * @version 8.5.0
 */

require_once 'config.php';

/**
 * Plugin-scoped translation function.
 * Uses the 'quick-buttons' text domain registered via Plugin::translate().
 */
function qb__($msgid) {
    return _dgettext('quick-buttons', $msgid);
}

/**
 * v7.0.6: resolve a translatable label.
 *
 * Accepts either:
 *   - a plain string (legacy single-language label) → returned as-is
 *   - an object/array {lang_code: text, ...} → returns the entry for $locale,
 *     falling back to 'en', then to the first non-empty entry, then to ''.
 *
 * Empty or null input → ''.
 */
function qb_resolve_label($value, $locale = null) {
    if ($value === null) return '';
    if (is_string($value)) return $value;
    if (is_object($value)) $value = (array)$value;
    if (!is_array($value)) return (string)$value;
    // Build fallback chain: full locale → short → en_US → en → first non-empty
    $tried = array();
    if ($locale) {
        $norm = qb_normalize_lang($locale);
        $tried[] = $norm;
        if (strpos($norm, '_') !== false) $tried[] = strtolower(strtok($norm, '_'));
    }
    $tried[] = 'en_US';
    $tried[] = 'en';
    foreach ($tried as $key) {
        if (isset($value[$key]) && $value[$key] !== '')
            return (string)$value[$key];
    }
    foreach ($value as $v) {
        if (is_string($v) && $v !== '') return $v;
    }
    return '';
}

/**
 * v7.0.6: list of language codes for label translation, sourced from
 * osTicket's enabled system languages (Primary + Secondary in admin →
 * System Settings). Mirrors the translator UX shown in osTicket form fields.
 *
 * Falls back to {en} if config not available.
 */
function qb_available_languages() {
    static $cache = null;
    if ($cache !== null) return $cache;
    global $cfg;
    $langs = array();
    if ($cfg && method_exists($cfg, 'getPrimaryLanguage')) {
        $primary = $cfg->getPrimaryLanguage();
        if ($primary) $langs[] = qb_normalize_lang($primary);
        $sec = method_exists($cfg, 'getSecondaryLanguages') ? $cfg->getSecondaryLanguages() : array();
        foreach ((array)$sec as $l) {
            $l = qb_normalize_lang($l);
            if ($l && !in_array($l, $langs, true)) $langs[] = $l;
        }
    }
    if (!$langs) $langs = array('en');
    return $cache = $langs;
}

/**
 * v7.0.6: normalize osTicket lang code (e.g. "en_US.po@.UTF-8" → "en_US",
 * "ru-RU" → "ru_RU", "ru" → "ru") to a stable format usable as a JSON key.
 */
function qb_normalize_lang($code) {
    $code = (string)$code;
    $code = preg_replace('/[^A-Za-z_-]/', '', $code);
    $code = str_replace('-', '_', $code);
    if (strpos($code, '_') !== false) {
        list($lo, $up) = explode('_', $code, 2);
        return strtolower($lo) . '_' . strtoupper($up);
    }
    return strtolower($code);
}

class QuickButtonsPlugin extends Plugin {
    var $config_class = 'QuickButtonsConfig';

    const CURRENT_SCHEMA = '7.0.0';
    const GITHUB_REPO = 'ChesnoTech/ost-quick-buttons';
    const GITHUB_BRANCH = 'stable';

    static private $bootstrapped = false;

    function bootstrap() {
        self::bootstrapStatic();
        // v7.0.12: self-heal ost_plugin.version mismatch (e.g. after manual file
        // replace or earlier auto-update that did not refresh the row).
        $this->syncPluginRowVersion();

        // v8.5.3: upgrade DB cnx to utf8mb4 so 4-byte emojis (🎯 🚀 📦 👍 etc.,
        // any code point U+10000+) survive INSERT into the already-utf8mb4
        // ost_config columns. osTicket core sets `SET NAMES utf8` which is the
        // legacy 3-byte alias (utf8mb3); MySQL silently substitutes 4-byte
        // chars with `?`. Reissuing here flips the cnx to 4-byte for all
        // subsequent queries in this request (incl. widget_config save).
        self::ensureUtf8mb4Connection();

        // v8.5.0: check for pending two-phase upgrade (Phase 2 finalizer).
        // If marker file present, this fresh PHP process can safely swap files +
        // run migrations using the freshly-loaded class definitions. Failure is
        // non-blocking; saved job state allows retry.
        self::checkPendingUpgrade();
    }

    /**
     * v8.5.3 — Promote DB cnx from utf8mb3 to utf8mb4 so 4-byte emojis
     * round-trip cleanly. Idempotent. Safe to call multiple times.
     */
    private static function ensureUtf8mb4Connection() {
        static $done = false;
        if ($done) return;
        $done = true;
        // SET NAMES alters client / connection / results charsets in one go.
        // utf8mb4_unicode_ci preserves correct emoji + accented sort order.
        @db_query("SET NAMES utf8mb4 COLLATE utf8mb4_unicode_ci");
    }

    /**
     * v7.0.12: keep ost_plugin.version aligned with plugin.php manifest.
     * Cheap idempotent SELECT + conditional UPDATE on every bootstrap.
     */
    private function syncPluginRowVersion() {
        $pid = (int) $this->getId();
        if (!$pid) return;
        $manifestPath = dirname(__FILE__) . '/plugin.php';
        if (!file_exists($manifestPath)) return;
        $info = @include $manifestPath;
        $manifestVersion = is_array($info) ? ($info['version'] ?? null) : null;
        if (!$manifestVersion) return;

        $row = db_fetch_array(db_query(sprintf(
            "SELECT version FROM %splugin WHERE id = %d", TABLE_PREFIX, $pid)));
        $currentRowVersion = $row ? (string)$row['version'] : '';
        if ($currentRowVersion === (string)$manifestVersion) return;

        db_query(sprintf(
            "UPDATE %splugin SET version = %s WHERE id = %d",
            TABLE_PREFIX, db_input((string)$manifestVersion), $pid));
    }

    /**
     * Prevent osTicket's auto-upgrade from running without confirmation.
     * We handle upgrades manually via the admin UI.
     */
    function pre_upgrade(&$errors) {
        // Don't auto-upgrade — let admin confirm via the UI banner
        return false;
    }

    // ================================================================
    //  Upgrade detection & admin banner
    // ================================================================

    /**
     * Check if a database upgrade is pending.
     * Compares migrated_version in DB against CURRENT_SCHEMA.
     */
    static function isUpgradePending() {
        $ns = 'plugin.quick-buttons.meta';
        $res = db_query(sprintf(
            "SELECT value FROM %s WHERE namespace = '%s' AND `key` = 'migrated_version'",
            CONFIG_TABLE, $ns));
        $row = $res ? db_fetch_row($res) : null;
        $migrated = $row ? $row[0] : '0';
        return version_compare($migrated, self::CURRENT_SCHEMA, '<');
    }

    /**
     * Get the currently migrated version from DB.
     */
    static function getMigratedVersion() {
        $ns = 'plugin.quick-buttons.meta';
        $res = db_query(sprintf(
            "SELECT value FROM %s WHERE namespace = '%s' AND `key` = 'migrated_version'",
            CONFIG_TABLE, $ns));
        $row = $res ? db_fetch_row($res) : null;
        return $row ? $row[0] : '0';
    }

    /**
     * Inject an upgrade banner into admin pages when upgrade is pending.
     */
    static function injectUpgradeBanner(&$buffer) {
        if (!self::isUpgradePending())
            return;

        $from = self::getMigratedVersion();
        $to = self::CURRENT_SCHEMA;
        $csrfToken = '';
        if (preg_match('/name="__CSRFToken__"[^>]*value="([^"]+)"/', $buffer, $m))
            $csrfToken = $m[1];

        $banner = '
<div id="qa-upgrade-banner" style="
    position: sticky;
    top: 0;
    z-index: 99999;
    background: linear-gradient(135deg, #ff9800, #f57c00);
    color: #fff;
    padding: 14px 24px;
    margin: 0;
    border-radius: 0;
    font-family: -apple-system, BlinkMacSystemFont, \'Segoe UI\', sans-serif;
    font-size: 14px;
    box-shadow: 0 2px 8px rgba(0,0,0,0.2);
    display: flex;
    align-items: center;
    gap: 16px;
    min-height: 36px;
    box-sizing: border-box;
">
    <span style="font-size: 24px; flex-shrink:0;">&#9888;</span>
    <div style="flex:1; min-width:0;">
        <strong>Quick Buttons — Database Update Required</strong><br>
        <span style="opacity:0.9;font-size:13px;">
            Schema version <strong>' . htmlspecialchars($from ?: 'none') . '</strong>
            &rarr; <strong>' . htmlspecialchars($to) . '</strong>.
            A backup will be created automatically before upgrading.
        </span>
    </div>
    <button id="qa-upgrade-btn" onclick="QAUpgrade.run()" style="
        background: #fff;
        color: #e65100;
        border: none;
        padding: 10px 24px;
        border-radius: 6px;
        font-size: 14px;
        font-weight: 700;
        cursor: pointer;
        white-space: nowrap;
        flex-shrink: 0;
        box-shadow: 0 1px 4px rgba(0,0,0,0.2);
    ">&#x2B06; Upgrade Now</button>
</div>
<script>
var QAUpgrade = {
    run: function() {
        var btn = document.getElementById("qa-upgrade-btn");
        if (!confirm("This will:\\n\\n1. Backup database config\\n2. Backup plugin files\\n3. Run schema migrations\\n\\nProceed with upgrade?"))
            return;
        btn.disabled = true;
        btn.textContent = "Upgrading...";
        btn.style.opacity = "0.7";
        var xhr = new XMLHttpRequest();
        xhr.open("POST", "ajax.php/quick-buttons/upgrade", true);
        xhr.setRequestHeader("Content-Type", "application/x-www-form-urlencoded");
        xhr.setRequestHeader("X-CSRFToken", "' . $csrfToken . '");
        xhr.onload = function() {
            if (xhr.status === 200) {
                try {
                    var res = JSON.parse(xhr.responseText);
                    if (res.success) {
                        var banner = document.getElementById("qa-upgrade-banner");
                        banner.style.background = "linear-gradient(135deg, #4caf50, #388e3c)";
                        banner.innerHTML = \'<span style="font-size:28px;">&#x2705;</span>\' +
                            \'<div style="flex:1;"><strong>Upgrade Complete!</strong><br>\' +
                            \'<span style="opacity:0.9;font-size:13px;">Schema updated to v\' + res.version +
                            \'. Backups saved to <code>backups/</code> directory.</span></div>\';
                    } else {
                        btn.textContent = "Retry Upgrade";
                        btn.disabled = false;
                        btn.style.opacity = "1";
                        alert("Upgrade failed: " + (res.error || "Unknown error"));
                    }
                } catch(e) {
                    btn.textContent = "Retry Upgrade";
                    btn.disabled = false;
                    btn.style.opacity = "1";
                    alert("Upgrade failed: Invalid response");
                }
            } else {
                btn.textContent = "Retry Upgrade";
                btn.disabled = false;
                btn.style.opacity = "1";
                alert("Upgrade failed: HTTP " + xhr.status);
            }
        };
        xhr.onerror = function() {
            btn.textContent = "Retry Upgrade";
            btn.disabled = false;
            btn.style.opacity = "1";
            alert("Network error during upgrade");
        };
        xhr.send("__CSRFToken__=' . urlencode($csrfToken) . '");
    }
};
</script>';

        // Inject right after <body> so it sits above all page content
        $pos = strpos($buffer, '<body');
        if ($pos !== false) {
            $insertPos = strpos($buffer, '>', $pos);
            if ($insertPos !== false)
                $buffer = substr_replace($buffer, '>' . $banner, $insertPos, 1);
        }
    }

    // ================================================================
    //  Upgrade execution (called via AJAX)
    // ================================================================

    /**
     * Execute the full upgrade: backup + migrate + set version flag.
     * Returns array with success/error status.
     */
    static function executeUpgrade() {
        if (!self::isUpgradePending())
            return array('success' => true, 'version' => self::CURRENT_SCHEMA, 'msg' => 'Already up to date');

        $fromVersion = self::getMigratedVersion();
        $toVersion = self::CURRENT_SCHEMA;
        $ns = 'plugin.quick-buttons.meta';

        // Step 1: Create backups
        $dbOk = self::backupDatabase($fromVersion, $toVersion);
        $filesOk = self::backupFiles($fromVersion, $toVersion);

        if (!$dbOk || !$filesOk)
            return array('success' => false, 'error' => 'Backup failed. Check backups/ directory permissions.');

        // Step 2: Run migrations
        self::runMigrations();

        // Step 3: Set version flag
        if ($fromVersion === '0') {
            db_query(sprintf(
                "INSERT INTO %s (namespace, `key`, value) VALUES ('%s', 'migrated_version', '%s')",
                CONFIG_TABLE, $ns, $toVersion));
        } else {
            db_query(sprintf(
                "UPDATE %s SET value = '%s' WHERE namespace = '%s' AND `key` = 'migrated_version'",
                CONFIG_TABLE, $toVersion, $ns));
        }

        return array('success' => true, 'version' => $toVersion);
    }

    // ================================================================
    //  Backups
    // ================================================================

    /**
     * Backup all plugin-related config rows to a SQL file.
     * Returns true on success.
     */
    private static function backupDatabase($fromVersion, $toVersion) {
        $candidates = array(
            dirname(__FILE__) . '/backups',
            sys_get_temp_dir() . '/quick-buttons-backups',
        );
        $backupDir = null;
        foreach ($candidates as $d) {
            if (!is_dir($d)) @mkdir($d, 0755, true);
            if (is_dir($d) && is_writable($d)) { $backupDir = $d; break; }
        }
        if (!$backupDir) {
            error_log('[quick-buttons] backup dir not writable; proceeding without DB backup');
            return true;
        }

        $timestamp = date('Ymd_His');
        $file = $backupDir . "/db_backup_{$fromVersion}_to_{$toVersion}_{$timestamp}.sql";

        $rows = array();
        $res = db_query("SELECT * FROM " . CONFIG_TABLE
            . " WHERE namespace LIKE 'plugin.%.instance.%'"
            . " OR namespace LIKE 'plugin.quick-buttons.%'"
            . " ORDER BY namespace, `key`");
        if ($res) {
            while ($row = db_fetch_array($res)) {
                $vals = array(
                    db_input($row['namespace']),
                    db_input($row['key']),
                    db_input($row['value']),
                );
                $rows[] = sprintf("(%s, %s, %s)", $vals[0], $vals[1], $vals[2]);
            }
        }

        if ($rows) {
            $sql = "-- Quick Buttons plugin DB backup\n"
                 . "-- Date: " . date('Y-m-d H:i:s') . "\n"
                 . "-- Upgrade: {$fromVersion} -> {$toVersion}\n"
                 . "-- Restore: Run this SQL to revert config changes\n\n"
                 . "-- Delete current plugin configs\n"
                 . "DELETE FROM " . CONFIG_TABLE . " WHERE namespace LIKE 'plugin.%.instance.%'"
                 . " OR namespace LIKE 'plugin.quick-buttons.%';\n\n"
                 . "-- Re-insert original values\n"
                 . "INSERT INTO " . CONFIG_TABLE . " (namespace, `key`, value) VALUES\n"
                 . implode(",\n", $rows) . ";\n";
            return @file_put_contents($file, $sql) !== false;
        }
        return true; // No rows to back up is still success
    }

    /**
     * Backup plugin PHP/JS/CSS files to a timestamped zip or directory.
     * Returns true on success.
     */
    private static function backupFiles($fromVersion, $toVersion) {
        $pluginDir = dirname(__FILE__);
        $candidates = array(
            $pluginDir . '/backups',
            sys_get_temp_dir() . '/quick-buttons-backups',
        );
        $backupDir = null;
        foreach ($candidates as $d) {
            if (!is_dir($d)) @mkdir($d, 0755, true);
            if (is_dir($d) && is_writable($d)) { $backupDir = $d; break; }
        }
        if (!$backupDir) {
            // v7.0.11: don't block the update — log and proceed without backup
            error_log('[quick-buttons] backup dir not writable; proceeding without backup');
            return true;
        }

        $timestamp = date('Ymd_His');
        $filesToBackup = array(
            'plugin.php', 'config.php',
            'class.QuickButtonsPlugin.php', 'class.QuickButtonsAjax.php',
            'assets/quick-buttons.js', 'assets/quick-buttons.css',
            'assets/workflow-builder.js', 'assets/workflow-builder.css',
            'assets/icon-picker.js', 'assets/icon-picker.css',
        );

        // Try zip first
        if (class_exists('ZipArchive')) {
            $zipFile = $backupDir . "/files_backup_{$fromVersion}_to_{$toVersion}_{$timestamp}.zip";
            $zip = new \ZipArchive();
            if ($zip->open($zipFile, \ZipArchive::CREATE | \ZipArchive::OVERWRITE) === true) {
                foreach ($filesToBackup as $f) {
                    $fullPath = $pluginDir . '/' . $f;
                    if (file_exists($fullPath))
                        $zip->addFile($fullPath, $f);
                }
                $zip->close();
                if (file_exists($zipFile)) return true;
            }
        }

        // Fallback: copy files
        $copyDir = $backupDir . "/files_{$fromVersion}_to_{$toVersion}_{$timestamp}";
        @mkdir($copyDir, 0755, true);
        @mkdir($copyDir . '/assets', 0755, true);
        foreach ($filesToBackup as $f) {
            $src = $pluginDir . '/' . $f;
            if (file_exists($src)) @copy($src, $copyDir . '/' . $f);
        }
        return true; // best effort — never block update
    }

    // ================================================================
    //  Auto-Update from GitHub
    // ================================================================

    /**
     * v7.0.13: Fetch latest release tag from GitHub Releases API.
     * Falls back to raw.githubusercontent and codeload if api.github.com is blocked.
     * Reading manifest version is the legacy local check (kept as fallback).
     */
    static function checkForUpdate() {
        // Use plugin.php manifest as authoritative local version (was CURRENT_SCHEMA
        // which only tracks DB schema, not the plugin release line).
        $localVersion = self::getLocalManifestVersion() ?: self::CURRENT_SCHEMA;

        // Try GitHub Releases API first — works when raw.githubusercontent is blocked.
        $apiUrl = 'https://api.github.com/repos/' . self::GITHUB_REPO . '/releases/latest';
        $apiBody = self::httpGet($apiUrl);
        $remoteVersion = null;
        $remoteAsset = null;
        if ($apiBody) {
            $j = @json_decode($apiBody, true);
            if (is_array($j) && !empty($j['tag_name'])) {
                $remoteVersion = ltrim($j['tag_name'], 'v');
                // Find first .zip asset (e.g. quick-buttons-v7.0.12.zip)
                if (!empty($j['assets']) && is_array($j['assets'])) {
                    foreach ($j['assets'] as $a) {
                        if (!empty($a['browser_download_url'])
                                && substr($a['browser_download_url'], -4) === '.zip') {
                            $remoteAsset = $a['browser_download_url'];
                            break;
                        }
                    }
                }
            }
        }

        // Fallback 1: raw.githubusercontent.com (legacy path)
        if (!$remoteVersion) {
            $rawUrl = 'https://raw.githubusercontent.com/' . self::GITHUB_REPO . '/' . self::GITHUB_BRANCH . '/plugin.php';
            $rawBody = self::httpGet($rawUrl);
            if ($rawBody && preg_match("/'version'\s*=>\s*'([^']+)'/", $rawBody, $m))
                $remoteVersion = $m[1];
        }

        if (!$remoteVersion)
            return array('error' => 'Cannot reach GitHub. Check server internet connectivity.');

        return array(
            'current'   => $localVersion,
            'latest'    => $remoteVersion,
            'available' => version_compare($remoteVersion, $localVersion, '>'),
            'asset_url' => $remoteAsset,  // null = use codeload fallback
        );
    }

    /**
     * v7.0.13: read 'version' from plugin.php manifest.
     */
    private static function getLocalManifestVersion() {
        $f = dirname(__FILE__) . '/plugin.php';
        if (!file_exists($f)) return null;
        $info = @include $f;
        return is_array($info) && !empty($info['version']) ? (string)$info['version'] : null;
    }

    /**
     * Download latest zip from GitHub, backup current files, replace, and run upgrade.
     */
    /**
     * v8.5.0 — Phase 1 of two-phase upgrade ceremony.
     *
     * Runs pre-flight checks, downloads the zip, extracts to a _staging/
     * sub-directory, creates a marker file, and returns immediately with
     * a job_id. The active PHP process never touches live plugin files
     * (avoids the self-replace-mid-request crash that produced 500s on
     * v8.3.x → v8.4.x upgrades).
     *
     * Phase 2 (finalizeUpdate) runs in a fresh PHP process on the next
     * bootstrap, when the new code is loaded cleanly from disk.
     *
     * Returns: {success: true, job_id, stage: 'staged_awaiting_swap'}
     *          {success: false, error: '...'}  on pre-flight or stage failure
     */
    static function stageUpdate() {
        $pluginDir = dirname(__FILE__);

        // Concurrency guard: refuse if another update is in progress.
        $pending = self::getPendingUpgrade();
        if ($pending && (time() - ($pending['started_at'] ?? 0)) < 3600) {
            return array('success' => false, 'error' => 'Another update is in progress (job ' . $pending['job_id'] . '). Wait or force-unlock.');
        }

        // 1. Pre-flight: writability, disk, memory, network
        $pre = self::preflightUpdate();
        if (!empty($pre['error']))
            return array('success' => false, 'error' => 'Pre-flight failed: ' . $pre['error']);

        $check = self::checkForUpdate();
        if (isset($check['error']))
            return array('success' => false, 'error' => $check['error']);
        if (empty($check['available']))
            return array('success' => false, 'error' => 'Already up to date');

        $latestVersion = $check['latest'];
        $currentVersion = $check['current'];
        $jobId = (string) time();

        // 2. Init job state
        $job = array(
            'job_id'           => $jobId,
            'from_version'     => $currentVersion,
            'to_version'       => $latestVersion,
            'stage'            => 'download',
            'stages_done'      => array('preflight'),
            'stages_remaining' => array('download', 'stage', 'swap', 'migrate'),
            'started_at'       => time(),
            'last_update'      => time(),
            'staging_path'     => '',
            'backup_path'      => '',
            'asset_url'        => $check['asset_url'] ?? null,
            'error'            => null,
            'percent'          => 10,
            'msg'              => 'Pre-flight passed',
        );
        self::saveJobState($job);

        // 3. Backup current files (existing logic, reused for rollback path)
        $backupOk = self::backupFiles(self::CURRENT_SCHEMA, $latestVersion);
        if (!$backupOk) {
            return self::failJob($job, 'File backup failed. Check backups/ directory permissions.');
        }

        // 4. Download zip
        $job['percent'] = 25;
        $job['msg'] = 'Downloading v' . $latestVersion . '...';
        self::saveJobState($job);

        $candidates = array();
        if (!empty($check['asset_url'])) $candidates[] = $check['asset_url'];
        $candidates[] = 'https://github.com/' . self::GITHUB_REPO
            . '/releases/download/v' . $latestVersion . '/quick-buttons-v' . $latestVersion . '.zip';
        $candidates[] = 'https://codeload.github.com/' . self::GITHUB_REPO
            . '/zip/refs/heads/' . self::GITHUB_BRANCH;
        $candidates[] = 'https://github.com/' . self::GITHUB_REPO
            . '/archive/refs/heads/' . self::GITHUB_BRANCH . '.zip';
        $zipContent = null;
        foreach (array_unique($candidates) as $u) {
            $zipContent = self::httpGet($u);
            if ($zipContent) break;
        }
        if (!$zipContent) {
            return self::failJob($job, 'Failed to download update from GitHub.');
        }

        $tmpFile = tempnam(sys_get_temp_dir(), 'qb_update_');
        file_put_contents($tmpFile, $zipContent);

        // 5. Extract zip
        $job['stage'] = 'stage';
        $job['stages_done'][] = 'download';
        $job['percent'] = 50;
        $job['msg'] = 'Extracting...';
        self::saveJobState($job);

        if (!class_exists('ZipArchive')) {
            return self::failJob($job, 'ZipArchive PHP extension required.');
        }
        $zip = new \ZipArchive();
        if ($zip->open($tmpFile) !== true) {
            @unlink($tmpFile);
            return self::failJob($job, 'Cannot open downloaded zip.');
        }
        $stagingDir = $pluginDir . DIRECTORY_SEPARATOR . '_staging' . DIRECTORY_SEPARATOR . $latestVersion;
        self::recursiveDelete($stagingDir); // clean any prior attempt
        @mkdir($stagingDir, 0755, true);
        $zip->extractTo($stagingDir);
        $zip->close();
        @unlink($tmpFile);

        // 6. Find extracted source dir.
        //
        // v8.5.1 — handle three known layouts:
        //   A. GitHub release zip with `quick-buttons-<ver>/` wrapper (preferred)
        //   B. Flat zip with files at root (no wrapper) — treat staging dir as source
        //   C. PowerShell Compress-Archive zip — files extracted with literal
        //      backslash in name (e.g. `quick-buttons-8.5.0\plugin.php`) because
        //      Linux ZipArchive treats `\` as a filename character. Auto-repair
        //      by recreating real subdirs from backslash-prefixed names.
        $dirs = glob($stagingDir . DIRECTORY_SEPARATOR . '*', GLOB_ONLYDIR);
        $sourceDir = null;
        if ($dirs) {
            // Case A
            $sourceDir = $dirs[0];
        } elseif (file_exists($stagingDir . DIRECTORY_SEPARATOR . 'plugin.php')) {
            // Case B — flat zip, use staging dir as source
            $sourceDir = $stagingDir;
        } else {
            // Case C — try to repair backslash-mangled filenames (PowerShell)
            $entries = @scandir($stagingDir) ?: array();
            $repaired = 0;
            foreach ($entries as $name) {
                if ($name === '.' || $name === '..') continue;
                if (strpos($name, '\\') === false) continue;
                $src = $stagingDir . DIRECTORY_SEPARATOR . $name;
                if (!is_file($src)) continue;
                $real = str_replace('\\', '/', $name);
                $target = $stagingDir . DIRECTORY_SEPARATOR . $real;
                @mkdir(dirname($target), 0755, true);
                if (@rename($src, $target)) $repaired++;
            }
            if ($repaired > 0) {
                // Retry: should now find a wrapper dir
                $dirs = glob($stagingDir . DIRECTORY_SEPARATOR . '*', GLOB_ONLYDIR);
                if ($dirs) {
                    $sourceDir = $dirs[0];
                    $job['msg'] = 'Repaired ' . $repaired . ' Windows-separator filename(s).';
                    self::saveJobState($job);
                }
            }
            if (!$sourceDir) {
                self::recursiveDelete($stagingDir);
                return self::failJob($job, 'Invalid archive structure (no subdir, no plugin.php at root, no repairable backslash names).');
            }
        }

        // 7. Verify staged manifest version matches expected
        $stagedManifest = $sourceDir . '/plugin.php';
        if (file_exists($stagedManifest)) {
            $info = @include $stagedManifest;
            $stagedVer = is_array($info) ? ($info['version'] ?? '') : '';
            if ($stagedVer !== $latestVersion) {
                self::recursiveDelete($stagingDir);
                return self::failJob($job, 'Staged manifest version mismatch (expected ' . $latestVersion . ', got ' . $stagedVer . ').');
            }
        }

        $job['stages_done'][] = 'stage';
        $job['stage'] = 'staged_awaiting_swap';
        $job['staging_path'] = $sourceDir;
        $job['percent'] = 65;
        $job['msg'] = 'Staged. Awaiting finalize.';
        self::saveJobState($job);

        // 8. Marker file — Phase 2 trigger
        self::createMarker($jobId);

        return array(
            'success' => true,
            'job_id'  => $jobId,
            'stage'   => 'staged_awaiting_swap',
            'message' => 'Files staged. Reload any admin page to finalize.',
        );
    }

    /**
     * v8.5.0 — Phase 2 of two-phase upgrade ceremony.
     *
     * Called automatically by bootstrap() when the pending-update marker
     * file is detected. Runs in a fresh PHP process — new class definitions
     * are loaded cleanly from disk, no mid-request self-replace risk.
     *
     * Atomically moves staged files to the live plugin dir (per-file rename),
     * updates ost_plugin.version row, runs migrations, clears marker.
     *
     * Idempotent: re-running with the same job_id resumes from last good stage.
     */
    static function finalizeUpdate($jobId) {
        $job = self::readJobState($jobId);
        if (!$job || empty($job['staging_path'])) return false;
        if ($job['stage'] === 'done') return true;
        $pluginDir = dirname(__FILE__);
        $sourceDir = $job['staging_path'];

        try {
            // 1. Atomic file swap (per-file rename)
            $job['stage'] = 'swap';
            $job['percent'] = 75;
            $job['msg'] = 'Swapping files...';
            $job['last_update'] = time();
            self::saveJobState($job);

            self::resetCopyFailures();
            $copyOk = self::recursiveCopy($sourceDir, $pluginDir);
            if (!$copyOk) {
                $fails = self::getLastCopyFailures();
                $detail = !empty($fails) ? ' Failed paths: ' . implode('; ', array_slice($fails, 0, 5)) : '';
                return self::failJob($job, 'Swap failed.' . $detail);
            }

            // 2. Migrate
            $job['stages_done'][] = 'swap';
            $job['stage'] = 'migrate';
            $job['percent'] = 90;
            $job['msg'] = 'Running migrations + sync...';
            $job['last_update'] = time();
            self::saveJobState($job);

            self::runMigrations();

            // Sync DB version row immediately (was previously bootstrap-deferred)
            $plugin = self::findPlugin();
            if ($plugin) {
                db_query(sprintf(
                    "UPDATE %splugin SET version = %s, install_path = install_path WHERE id = %d",
                    TABLE_PREFIX, db_input($job['to_version']), (int)$plugin->getId()
                ));
            }

            // 3. Done
            $job['stages_done'][] = 'migrate';
            $job['stage'] = 'done';
            $job['percent'] = 100;
            $job['msg'] = 'Upgraded to v' . $job['to_version'];
            $job['last_update'] = time();
            self::saveJobState($job);

            // Clean staging + marker
            self::recursiveDelete(dirname($sourceDir));
            self::clearMarker();
            self::pruneJobStates();

            return true;
        } catch (\Throwable $e) {
            return self::failJob($job, 'Finalize exception: ' . $e->getMessage());
        }
    }

    /**
     * v8.5.0 — Bootstrap hook. Detects pending marker + invokes finalizer.
     * No-op if no marker present.
     */
    private static function checkPendingUpgrade() {
        $marker = self::getMarkerPath();
        if (!file_exists($marker)) return;
        $jobId = trim(@file_get_contents($marker));
        if (!$jobId) {
            @unlink($marker);
            return;
        }
        // Stale marker: clear if > 1 hour old
        if ((time() - @filemtime($marker)) > 3600) {
            @unlink($marker);
            return;
        }
        self::finalizeUpdate($jobId);
    }

    private static function getMarkerPath() {
        return dirname(__FILE__) . '/_pending_update.flag';
    }
    private static function createMarker($jobId) {
        @file_put_contents(self::getMarkerPath(), $jobId);
    }
    private static function clearMarker() {
        @unlink(self::getMarkerPath());
    }

    /**
     * v8.5.0 — Pre-flight checks before destructive ops.
     * Returns ['ok' => bool, 'error' => string|null].
     */
    static function preflightUpdate() {
        $pluginDir = dirname(__FILE__);
        if (!is_writable($pluginDir))
            return array('error' => 'Plugin directory not writable: ' . $pluginDir);
        $free = @disk_free_space($pluginDir);
        if ($free !== false && $free < (50 * 1024 * 1024))
            return array('error' => sprintf('Insufficient disk: %d MB free, need 50 MB.', (int)($free / 1024 / 1024)));
        $mem = self::parseMemoryLimit(ini_get('memory_limit'));
        if ($mem > 0 && $mem < (64 * 1024 * 1024))
            return array('error' => sprintf('PHP memory_limit too low (%s). Increase to 64M+.', ini_get('memory_limit')));
        // Network: HEAD api.github.com
        $apiOk = false;
        if (function_exists('curl_init')) {
            $ch = curl_init('https://api.github.com');
            curl_setopt($ch, CURLOPT_NOBODY, true);
            curl_setopt($ch, CURLOPT_TIMEOUT, 10);
            curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
            curl_exec($ch);
            $code = curl_getinfo($ch, CURLINFO_HTTP_CODE);
            curl_close($ch);
            $apiOk = ($code >= 200 && $code < 500);
        } else {
            $apiOk = @file_get_contents('https://api.github.com', false, stream_context_create(array('http' => array('timeout' => 10)))) !== false;
        }
        if (!$apiOk)
            return array('error' => 'Cannot reach api.github.com. Check server internet/firewall.');
        return array('ok' => true);
    }

    private static function parseMemoryLimit($v) {
        $v = trim((string)$v);
        if ($v === '' || $v === '-1') return -1; // unlimited
        $u = strtolower(substr($v, -1));
        $n = (float) $v;
        if ($u === 'g') return (int)($n * 1024 * 1024 * 1024);
        if ($u === 'm') return (int)($n * 1024 * 1024);
        if ($u === 'k') return (int)($n * 1024);
        return (int) $n;
    }

    /**
     * v8.5.0 — Job state persistence (ost_config table, same plugin namespace).
     * Key pattern: update_job_<job_id>. JSON-encoded state.
     */
    static function saveJobState($job) {
        $plugin = self::findPlugin();
        if (!$plugin) return false;
        $ns = 'plugin.' . $plugin->getId();
        $key = 'update_job_' . $job['job_id'];
        $job['last_update'] = time();
        return db_query(sprintf(
            "INSERT INTO %s (namespace, `key`, value, updated) VALUES (%s, %s, %s, NOW())
             ON DUPLICATE KEY UPDATE value=VALUES(value), updated=NOW()",
            CONFIG_TABLE, db_input($ns), db_input($key), db_input(json_encode($job))
        ));
    }

    static function readJobState($jobId) {
        $plugin = self::findPlugin();
        if (!$plugin) return null;
        $ns = 'plugin.' . $plugin->getId();
        $key = 'update_job_' . $jobId;
        $row = db_fetch_array(db_query(sprintf(
            "SELECT value FROM %s WHERE namespace = %s AND `key` = %s LIMIT 1",
            CONFIG_TABLE, db_input($ns), db_input($key)
        )));
        if (!$row || empty($row['value'])) return null;
        return json_decode($row['value'], true);
    }

    static function listJobs() {
        $plugin = self::findPlugin();
        if (!$plugin) return array();
        $ns = 'plugin.' . $plugin->getId();
        $res = db_query(sprintf(
            "SELECT value FROM %s WHERE namespace = %s AND `key` LIKE 'update_job_%%' ORDER BY `key` DESC",
            CONFIG_TABLE, db_input($ns)
        ));
        $jobs = array();
        if ($res) {
            while ($r = db_fetch_array($res)) {
                $j = @json_decode($r['value'], true);
                if (is_array($j)) $jobs[] = $j;
            }
        }
        return $jobs;
    }

    static function pruneJobStates() {
        $plugin = self::findPlugin();
        if (!$plugin) return;
        $ns = 'plugin.' . $plugin->getId();
        $res = db_query(sprintf(
            "SELECT `key` FROM %s WHERE namespace = %s AND `key` LIKE 'update_job_%%' ORDER BY `key` DESC",
            CONFIG_TABLE, db_input($ns)
        ));
        if (!$res) return;
        $keys = array();
        while ($r = db_fetch_array($res)) $keys[] = $r['key'];
        if (count($keys) > 10) {
            $toDel = array_slice($keys, 10);
            $quoted = array_map(function($k) { return db_input($k); }, $toDel);
            db_query(sprintf(
                "DELETE FROM %s WHERE namespace = %s AND `key` IN (%s)",
                CONFIG_TABLE, db_input($ns), implode(',', $quoted)
            ));
        }
    }

    /** Returns the most recent unfinished job, or null. */
    static function getPendingUpgrade() {
        foreach (self::listJobs() as $j) {
            if (in_array($j['stage'] ?? '', array('done', 'failed'), true)) continue;
            return $j;
        }
        return null;
    }

    /** Mark a job failed + save state. Returns the standard error array. */
    private static function failJob($job, $err) {
        $job['stage'] = 'failed';
        $job['error'] = $err;
        $job['last_update'] = time();
        self::saveJobState($job);
        self::clearMarker(); // allow retry
        return array('success' => false, 'error' => $err, 'job_id' => $job['job_id']);
    }

    /**
     * v8.5.0 — Rollback by restoring a backup snapshot.
     * @param int $backupTs unix timestamp of backup file (matches backupFiles naming).
     */
    static function rollbackUpdate($backupTs) {
        $pluginDir = dirname(__FILE__);
        $backupDir = $pluginDir . '/backups';
        // Find backup zip by ts
        $matches = glob($backupDir . '/quick-buttons-*-' . (int)$backupTs . '.zip');
        if (!$matches) {
            // Try sys_get_temp_dir fallback used by v7.0.11
            $altDir = sys_get_temp_dir() . '/quick-buttons-backups';
            $matches = glob($altDir . '/quick-buttons-*-' . (int)$backupTs . '.zip');
        }
        if (!$matches) return array('success' => false, 'error' => 'Backup file not found for ts ' . $backupTs);
        $backupZip = $matches[0];

        // Snapshot current first (rollback is reversible)
        self::backupFiles(self::CURRENT_SCHEMA, 'rollback-' . time());

        // Extract backup to staging
        $stagingDir = $pluginDir . '/_staging/rollback-' . time();
        @mkdir($stagingDir, 0755, true);
        $zip = new \ZipArchive();
        if ($zip->open($backupZip) !== true)
            return array('success' => false, 'error' => 'Cannot open backup zip.');
        $zip->extractTo($stagingDir);
        $zip->close();

        // Find extracted source
        $dirs = glob($stagingDir . '/*', GLOB_ONLYDIR);
        $sourceDir = $dirs ? $dirs[0] : $stagingDir;

        // Copy back to live
        self::resetCopyFailures();
        $copyOk = self::recursiveCopy($sourceDir, $pluginDir);
        self::recursiveDelete($stagingDir);
        if (!$copyOk) return array('success' => false, 'error' => 'Rollback copy failed.');

        // Re-read manifest to get restored version
        $restoredVer = self::getLocalManifestVersion();
        $plugin = self::findPlugin();
        if ($plugin && $restoredVer) {
            db_query(sprintf(
                "UPDATE %splugin SET version = %s, install_path = install_path WHERE id = %d",
                TABLE_PREFIX, db_input($restoredVer), (int)$plugin->getId()
            ));
        }

        return array('success' => true, 'restored_version' => $restoredVer);
    }

    /** List available backups for rollback UI. */
    static function listBackups() {
        $pluginDir = dirname(__FILE__);
        $candidates = array(
            $pluginDir . '/backups',
            sys_get_temp_dir() . '/quick-buttons-backups',
        );
        $backups = array();
        foreach ($candidates as $dir) {
            if (!is_dir($dir)) continue;
            foreach (glob($dir . '/quick-buttons-*-*.zip') as $f) {
                if (preg_match('/quick-buttons-([^-]+)-(\d+)\.zip$/', basename($f), $m)) {
                    $backups[] = array(
                        'version'    => $m[1],
                        'ts'         => (int)$m[2],
                        'size_bytes' => @filesize($f),
                        'path'       => $f,
                    );
                }
            }
        }
        // Sort newest first
        usort($backups, function($a, $b) { return $b['ts'] - $a['ts']; });
        return $backups;
    }

    /**
     * v8.5.0 — Legacy applyUpdate kept as alias to stageUpdate for any external
     * code that may call it. Old single-phase behavior is gone.
     */
    static function applyUpdate() {
        return self::stageUpdate();
    }

    /**
     * HTTP GET with cURL fallback.
     */
    private static function httpGet($url) {
        // Try file_get_contents first
        $ctx = @stream_context_create(array('http' => array(
            'timeout'       => 15,
            'follow_location' => 1,
            'user_agent'    => 'osTicket-QuickButtons/' . self::CURRENT_SCHEMA,
        )));
        $content = @file_get_contents($url, false, $ctx);
        if ($content)
            return $content;

        // Fallback: cURL
        if (function_exists('curl_init')) {
            $ch = curl_init($url);
            curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
            curl_setopt($ch, CURLOPT_TIMEOUT, 15);
            curl_setopt($ch, CURLOPT_FOLLOWLOCATION, true);
            curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, true);
            curl_setopt($ch, CURLOPT_USERAGENT, 'osTicket-QuickButtons/' . self::CURRENT_SCHEMA);
            $content = curl_exec($ch);
            $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
            curl_close($ch);
            if ($content && $httpCode >= 200 && $httpCode < 400)
                return $content;
        }

        return null;
    }

    /**
     * Recursively copy directory contents.
     * v7.0.14: chmod target file to writable before copy (handles 644 files
     * owned by a different user), use unlink+copy fallback. Collects failures
     * in static $copyFailures for diagnostics.
     */
    private static $copyFailures = array();
    private static function recursiveCopy($src, $dst) {
        $dir = @opendir($src);
        if (!$dir) {
            self::$copyFailures[] = "open src failed: $src";
            return false;
        }
        if (!is_dir($dst)) @mkdir($dst, 0755, true);
        if (!is_writable($dst)) @chmod($dst, 0755);
        $ok = true;
        while (($file = readdir($dir)) !== false) {
            if ($file === '.' || $file === '..' || $file === '.git' || $file === 'backups')
                continue;
            $srcPath = $src . DIRECTORY_SEPARATOR . $file;
            $dstPath = $dst . DIRECTORY_SEPARATOR . $file;
            if (is_dir($srcPath)) {
                $ok = self::recursiveCopy($srcPath, $dstPath) && $ok;
                continue;
            }
            // File: ensure target is writable then copy
            if (file_exists($dstPath) && !is_writable($dstPath))
                @chmod($dstPath, 0644);
            $copied = @copy($srcPath, $dstPath);
            if (!$copied) {
                // Try unlink + copy as fallback
                @unlink($dstPath);
                $copied = @copy($srcPath, $dstPath);
            }
            if (!$copied) {
                $err = error_get_last();
                self::$copyFailures[] = $dstPath . ' (' . ($err['message'] ?? 'unknown') . ')';
                $ok = false;
            }
        }
        closedir($dir);
        return $ok;
    }

    /** v7.0.14: expose collected copy failures for error reporting. */
    static function getLastCopyFailures() {
        return self::$copyFailures;
    }
    static function resetCopyFailures() {
        self::$copyFailures = array();
    }

    /**
     * Recursively delete a directory.
     */
    private static function recursiveDelete($dir) {
        if (!is_dir($dir)) return;
        $items = scandir($dir);
        foreach ($items as $item) {
            if ($item === '.' || $item === '..') continue;
            $path = $dir . DIRECTORY_SEPARATOR . $item;
            if (is_dir($path))
                self::recursiveDelete($path);
            else
                @unlink($path);
        }
        @rmdir($dir);
    }

    // ================================================================
    //  Migrations
    // ================================================================

    /**
     * Database migrations for version upgrades.
     * Safe to run multiple times — each migration checks before acting.
     */
    static function runMigrations() {
        // v4.1.0: Enable show_deadline on all existing instances that don't have it
        self::migrate_410_showDeadline();
        // v4.1.0: Update stop icon from stacked to emoji checkmark
        self::migrate_410_stopIcon();
        // v5.0.0: Convert flat variant configs to dynamic steps arrays
        self::migrate_500_dynamicSteps();
        // v5.1.0: Add access_control defaults to existing steps
        self::migrate_510_accessControl();
        // v5.2.0: Add perf_mode + perf_value defaults to existing configs
        self::migrate_520_perfTracking();
        // v5.3.0: Add interruptions defaults to existing configs
        self::migrate_530_interruptions();
        // v6.0.0: Move perf + interruptions from dept-level to per-step
        self::migrate_600_perStepPerfAndInterruptions();
        // v7.0.0: Add Rejections panel + Icons table + kind column. Unwinds any
        // bad-v7 alt_steps wrapping so variants stay flat (status-driven button model).
        self::migrate_700_rejectionsAndIcons();
        // v7.0.4: Unify panels. Rejection is a TYPE attribute (kind=rejection), not
        // a separate panel. Merge step.rejections.types into step.interruptions.types
        // with kind=rejection set on migrated types. Drop step.rejections.
        self::migrate_704_unifyInterruptionPanels();
    }

    private static function migrate_410_showDeadline() {
        $res = db_query("SELECT DISTINCT c1.namespace
            FROM " . CONFIG_TABLE . " c1
            WHERE c1.namespace LIKE 'plugin.%.instance.%'
              AND c1.namespace NOT IN (
                  SELECT c2.namespace FROM " . CONFIG_TABLE . " c2
                  WHERE c2.`key` = 'show_deadline'
              )
            GROUP BY c1.namespace");
        if ($res) {
            while ($row = db_fetch_row($res)) {
                db_query(sprintf(
                    "INSERT INTO %s (namespace, `key`, value) VALUES (%s, 'show_deadline', '1')",
                    CONFIG_TABLE,
                    db_input($row[0])
                ));
            }
        }
    }

    private static function migrate_410_stopIcon() {
        db_query("UPDATE " . CONFIG_TABLE . " SET value = '{\"icon-ok-sign\":\"OK Sign (Bold Checkmark)\"}'
            WHERE `key` = 'button_icon'
              AND value LIKE '%icon-check+icon-share%'
              AND namespace LIKE 'plugin.%.instance.%'");
    }

    /**
     * v5.0.0: Convert flat single/twostep variant configs to dynamic steps arrays.
     * Reads each instance's widget_config, converts legacy dept configs, writes back.
     */
    private static function migrate_500_dynamicSteps() {
        $res = db_query("SELECT id, namespace, `key`, value FROM " . CONFIG_TABLE
            . " WHERE `key` = 'widget_config'"
            . "   AND namespace LIKE 'plugin.%.instance.%'");
        if (!$res) return;

        while ($row = db_fetch_array($res)) {
            $raw = strip_tags($row['value'] ?: '');
            $data = @json_decode($raw, true);
            if (!is_array($data) || empty($data['departments'])) continue;

            $changed = false;
            foreach ($data['departments'] as $deptId => &$deptCfg) {
                if (!empty($deptCfg['schema_version']) && (int)$deptCfg['schema_version'] >= 2)
                    continue; // Already migrated
                if (isset($deptCfg['steps']))
                    continue; // Already has steps

                $deptCfg = self::normalizeDeptConfig($deptCfg);
                $changed = true;
            }
            unset($deptCfg);

            if ($changed) {
                $json = json_encode($data, JSON_UNESCAPED_UNICODE);
                db_query(sprintf(
                    "UPDATE %s SET value = %s WHERE id = %d",
                    CONFIG_TABLE, db_input($json), (int)$row['id']
                ));
            }
        }
    }

    /**
     * v5.1.0: Add access_control to existing step configs.
     * Sets mode="native" on all existing steps to preserve current permission behavior.
     * New steps created in the workflow builder default to "workflow" mode.
     */
    private static function migrate_510_accessControl() {
        $res = db_query("SELECT id, namespace, `key`, value FROM " . CONFIG_TABLE
            . " WHERE `key` = 'widget_config'"
            . "   AND namespace LIKE 'plugin.%.instance.%'");
        if (!$res) return;

        while ($row = db_fetch_array($res)) {
            $raw = strip_tags($row['value'] ?: '');
            $data = @json_decode($raw, true);
            if (!is_array($data) || empty($data['departments'])) continue;

            $changed = false;
            foreach ($data['departments'] as $deptId => &$deptCfg) {
                if (empty($deptCfg['steps'])) continue;
                // Skip if already at schema_version 3
                if (!empty($deptCfg['schema_version']) && (int)$deptCfg['schema_version'] >= 3)
                    continue;

                foreach ($deptCfg['steps'] as &$step) {
                    if (!isset($step['access_control'])) {
                        // Existing steps get "native" to preserve current behavior
                        $step['access_control'] = array(
                            'mode' => 'native',
                            'restrict_to' => array('agents' => array(), 'teams' => array(), 'roles' => array()),
                        );
                        $changed = true;
                    }
                }
                unset($step);
                $deptCfg['schema_version'] = 3;
                $changed = true;
            }
            unset($deptCfg);

            if ($changed) {
                $json = json_encode($data, JSON_UNESCAPED_UNICODE);
                db_query(sprintf(
                    "UPDATE %s SET value = %s WHERE id = %d",
                    CONFIG_TABLE, db_input($json), (int)$row['id']
                ));
            }
        }
    }

    /**
     * v5.2.0: Add perf_mode and perf_value defaults to existing configs.
     * Sets perf_mode="off" on departments and perf_value="0" on steps.
     */
    private static function migrate_520_perfTracking() {
        $res = db_query("SELECT id, namespace, `key`, value FROM " . CONFIG_TABLE
            . " WHERE `key` = 'widget_config'"
            . "   AND namespace LIKE 'plugin.%.instance.%'");
        if (!$res) return;

        while ($row = db_fetch_array($res)) {
            $raw = strip_tags($row['value'] ?: '');
            $data = @json_decode($raw, true);
            if (!is_array($data) || empty($data['departments'])) continue;

            $changed = false;
            foreach ($data['departments'] as $deptId => &$deptCfg) {
                if (empty($deptCfg['steps'])) continue;
                // Skip if already at schema_version 4
                if (!empty($deptCfg['schema_version']) && (int)$deptCfg['schema_version'] >= 4)
                    continue;

                if (!isset($deptCfg['perf_mode'])) {
                    $deptCfg['perf_mode'] = 'off';
                    $changed = true;
                }

                foreach ($deptCfg['steps'] as &$step) {
                    if (!isset($step['perf_value'])) {
                        $step['perf_value'] = '0';
                        $changed = true;
                    }
                }
                unset($step);
                $deptCfg['schema_version'] = 4;
                $changed = true;
            }
            unset($deptCfg);

            if ($changed) {
                $json = json_encode($data, JSON_UNESCAPED_UNICODE);
                db_query(sprintf(
                    "UPDATE %s SET value = %s WHERE id = %d",
                    CONFIG_TABLE, db_input($json), (int)$row['id']
                ));
            }
        }
    }

    /**
     * v5.3.0: Add interruptions defaults to existing configs.
     * Adds interruptions={enabled:false,...} and bumps schema_version to 5.
     */
    private static function migrate_530_interruptions() {
        $res = db_query("SELECT id, namespace, `key`, value FROM " . CONFIG_TABLE
            . " WHERE `key` = 'widget_config'"
            . "   AND namespace LIKE 'plugin.%.instance.%'");
        if (!$res) return;

        $defaultInt = array(
            'enabled' => false,
            'label'   => '',
            'color'   => '#e67e22',
            'icon'    => 'icon-pause',
            'types'   => array(),
        );

        while ($row = db_fetch_array($res)) {
            $raw = strip_tags($row['value'] ?: '');
            $data = @json_decode($raw, true);
            if (!is_array($data) || empty($data['departments'])) continue;

            $changed = false;
            foreach ($data['departments'] as $deptId => &$deptCfg) {
                if (empty($deptCfg['steps'])) continue;
                if (!empty($deptCfg['schema_version']) && (int)$deptCfg['schema_version'] >= 5)
                    continue;

                if (!isset($deptCfg['interruptions'])) {
                    $deptCfg['interruptions'] = $defaultInt;
                    $changed = true;
                }
                $deptCfg['schema_version'] = 5;
                $changed = true;
            }
            unset($deptCfg);

            if ($changed) {
                $json = json_encode($data, JSON_UNESCAPED_UNICODE);
                db_query(sprintf(
                    "UPDATE %s SET value = %s WHERE id = %d",
                    CONFIG_TABLE, db_input($json), (int)$row['id']
                ));
            }
        }
    }

    /**
     * v6.0.0: Move perf_mode/perf_source_field/perf_mappings and interruptions
     * from dept-level into each step. Also add step_index column to interruptions table.
     */
    private static function migrate_600_perStepPerfAndInterruptions() {
        $res = db_query("SELECT id, namespace, `key`, value FROM " . CONFIG_TABLE
            . " WHERE `key` = 'widget_config'"
            . "   AND namespace LIKE 'plugin.%.instance.%'");
        if (!$res) return;

        $defaultInt = array(
            'enabled' => false,
            'label'   => '',
            'color'   => '#e67e22',
            'icon'    => 'icon-pause',
            'types'   => array(),
        );

        while ($row = db_fetch_array($res)) {
            $raw = strip_tags($row['value'] ?: '');
            $data = @json_decode($raw, true);
            if (!is_array($data) || empty($data['departments'])) continue;

            $changed = false;
            foreach ($data['departments'] as $deptId => &$deptCfg) {
                if (empty($deptCfg['steps'])) continue;
                if (!empty($deptCfg['schema_version']) && (int)$deptCfg['schema_version'] >= 6)
                    continue;

                // Copy dept-level perf config into every step
                $deptPerfMode = $deptCfg['perf_mode'] ?? 'off';
                $deptPerfSrc  = $deptCfg['perf_source_field'] ?? '';
                $deptPerfMap  = $deptCfg['perf_mappings'] ?? array();
                $deptInt      = $deptCfg['interruptions'] ?? $defaultInt;

                foreach ($deptCfg['steps'] as &$step) {
                    if (!isset($step['perf_mode']))
                        $step['perf_mode'] = $deptPerfMode;
                    if (!isset($step['perf_source_field']))
                        $step['perf_source_field'] = $deptPerfSrc;
                    if (!isset($step['perf_mappings']))
                        $step['perf_mappings'] = $deptPerfMap;
                    if (!isset($step['interruptions']))
                        $step['interruptions'] = $deptInt;
                }
                unset($step);

                // Remove dept-level keys
                unset($deptCfg['perf_mode']);
                unset($deptCfg['perf_source_field']);
                unset($deptCfg['perf_mappings']);
                unset($deptCfg['interruptions']);

                $deptCfg['schema_version'] = 6;
                $changed = true;
            }
            unset($deptCfg);

            if ($changed) {
                $json = json_encode($data, JSON_UNESCAPED_UNICODE);
                db_query(sprintf(
                    "UPDATE %s SET value = %s WHERE id = %d",
                    CONFIG_TABLE, db_input($json), (int)$row['id']
                ));
            }
        }

        // Add step_index column to interruptions table if it exists
        $tableCheck = db_query("SHOW TABLES LIKE '" . TABLE_PREFIX . "quick_buttons_interruptions'");
        if ($tableCheck && db_num_rows($tableCheck) > 0) {
            $colCheck = db_query("SHOW COLUMNS FROM `" . TABLE_PREFIX . "quick_buttons_interruptions` LIKE 'step_index'");
            if (!$colCheck || db_num_rows($colCheck) == 0) {
                db_query("ALTER TABLE `" . TABLE_PREFIX . "quick_buttons_interruptions`
                    ADD COLUMN `step_index` TINYINT UNSIGNED NOT NULL DEFAULT 0 AFTER `dept_id`");
            }
        }
    }

    /**
     * v7.0.0 (corrected model): Add Rejections panel + Icons table + kind column.
     *
     * BPA model: Workflow Builder is just status-driven action buttons. "Interruption
     * button" is a normal button differentiated only by the popup that collects
     * Type→Variant→Reason metadata before firing a single status change. After it fires,
     * the next visible action button (driven by ticket's new status) takes over.
     *
     * NOTE: an earlier v7.0.0/v7.0.1 release introduced a misguided alt_steps[] nested
     * workflow inside variants. This migration UNWINDS that mistake by collapsing
     * `variant.alt_steps[0]` back into variant root fields and stripping `terminus`,
     * `rejoin_status`, etc. Existing v6 (or v4.3.4 → v6 chain) configs pass through
     * unchanged except for the added rejections panel and icons table.
     *
     * Idempotent: skips dept configs already at schema_version >= 7.
     */
    private static function migrate_700_rejectionsAndIcons() {
        $res = db_query("SELECT id, namespace, `key`, value FROM " . CONFIG_TABLE
            . " WHERE `key` = 'widget_config'"
            . "   AND namespace LIKE 'plugin.%.instance.%'");
        if (!$res) return;

        $defaultRej = array(
            'enabled' => false,
            'label'   => '',
            'color'   => '#c0392b',
            'icon'    => 'icon-ban-circle',
            'types'   => array(),
        );
        $defaultAcl = array(
            'mode' => 'workflow',
            'restrict_to' => array('agents' => array(), 'teams' => array(), 'roles' => array()),
        );

        while ($row = db_fetch_array($res)) {
            $raw = strip_tags($row['value'] ?: '');
            $data = @json_decode($raw, true);
            if (!is_array($data) || empty($data['departments'])) continue;

            $changed = false;
            foreach ($data['departments'] as $deptId => &$deptCfg) {
                if (empty($deptCfg['steps'])) continue;
                if (!empty($deptCfg['schema_version']) && (int)$deptCfg['schema_version'] >= 7)
                    continue;

                foreach ($deptCfg['steps'] as &$step) {
                    // If a previous bad-v7 config wrapped variants into alt_steps[],
                    // un-wrap them back into flat variant root fields.
                    if (!empty($step['interruptions']['types'])) {
                        foreach ($step['interruptions']['types'] as &$type) {
                            if (empty($type['variants'])) continue;
                            foreach ($type['variants'] as &$variant) {
                                self::flattenAltStepsBackToVariant($variant, $defaultAcl);
                            }
                            unset($variant);
                        }
                        unset($type);
                    }
                    if (!empty($step['rejections']['types'])) {
                        foreach ($step['rejections']['types'] as &$type) {
                            if (empty($type['variants'])) continue;
                            foreach ($type['variants'] as &$variant) {
                                self::flattenAltStepsBackToVariant($variant, $defaultAcl);
                            }
                            unset($variant);
                        }
                        unset($type);
                    }

                    // Add empty rejections panel if absent (new v7 panel)
                    if (!isset($step['rejections']))
                        $step['rejections'] = $defaultRej;
                }
                unset($step);

                $deptCfg['schema_version'] = 7;
                $changed = true;
            }
            unset($deptCfg);

            if ($changed) {
                $json = json_encode($data, JSON_UNESCAPED_UNICODE);
                db_query(sprintf(
                    "UPDATE %s SET value = %s WHERE id = %d",
                    CONFIG_TABLE, db_input($json), (int)$row['id']
                ));
            }
        }

        // Add kind column to interruptions table (rejection-vs-pause distinction).
        // current_alt_step column kept for backward-compat but unused at runtime.
        $tableCheck = db_query("SHOW TABLES LIKE '" . TABLE_PREFIX . "quick_buttons_interruptions'");
        if ($tableCheck && db_num_rows($tableCheck) > 0) {
            $kindCheck = db_query("SHOW COLUMNS FROM `" . TABLE_PREFIX . "quick_buttons_interruptions` LIKE 'kind'");
            if (!$kindCheck || db_num_rows($kindCheck) == 0) {
                db_query("ALTER TABLE `" . TABLE_PREFIX . "quick_buttons_interruptions`
                    ADD COLUMN `kind` ENUM('pause','rejection') NOT NULL DEFAULT 'pause'");
            }
            $idxCheck = db_query("SHOW INDEX FROM `" . TABLE_PREFIX . "quick_buttons_interruptions` WHERE Key_name = 'idx_kind_ticket'");
            if (!$idxCheck || db_num_rows($idxCheck) == 0) {
                @db_query("ALTER TABLE `" . TABLE_PREFIX . "quick_buttons_interruptions`
                    ADD INDEX `idx_kind_ticket` (`kind`, `ticket_id`)");
            }
            // Expand admin-supplied IDs to VARCHAR(40) for descriptive labels.
            @db_query("ALTER TABLE `" . TABLE_PREFIX . "quick_buttons_interruptions`
                MODIFY COLUMN `type_id` VARCHAR(40) NOT NULL,
                MODIFY COLUMN `variant_id` VARCHAR(40) NOT NULL");
        }

        // Create icons table
        if (class_exists('QuickButtonsConfig') && method_exists('QuickButtonsConfig', 'ensureIconsTable')) {
            QuickButtonsConfig::ensureIconsTable();
        }
    }

    /**
     * v7.0.4: rejections panel deprecated. Each Type now carries kind=pause|rejection.
     * Migrate any existing step.rejections.types into step.interruptions.types with
     * kind=rejection stamped per type. Drop step.rejections after merge.
     * Idempotent: if step.rejections is empty/missing, no-op.
     */
    private static function migrate_704_unifyInterruptionPanels() {
        $res = db_query("SELECT id, namespace, `key`, value FROM " . CONFIG_TABLE
            . " WHERE `key` = 'widget_config'"
            . "   AND namespace LIKE 'plugin.%.instance.%'");
        if (!$res) return;

        while ($row = db_fetch_array($res)) {
            $raw = strip_tags($row['value'] ?: '');
            $data = @json_decode($raw, true);
            if (!is_array($data) || empty($data['departments'])) continue;

            $changed = false;
            foreach ($data['departments'] as $deptId => &$deptCfg) {
                if (empty($deptCfg['steps'])) continue;
                foreach ($deptCfg['steps'] as &$step) {
                    // Stamp kind=pause on existing interruption types if missing
                    if (!empty($step['interruptions']['types'])) {
                        foreach ($step['interruptions']['types'] as &$t) {
                            if (!isset($t['kind'])) {
                                $t['kind'] = 'pause';
                                $changed = true;
                            }
                        }
                        unset($t);
                    }
                    // Migrate rejections.types into interruptions.types with kind=rejection
                    if (!empty($step['rejections']['types']) && is_array($step['rejections']['types'])) {
                        if (!isset($step['interruptions']['types']) || !is_array($step['interruptions']['types']))
                            $step['interruptions']['types'] = array();
                        if (empty($step['interruptions']['enabled']))
                            $step['interruptions']['enabled'] = !empty($step['rejections']['enabled']);
                        foreach ($step['rejections']['types'] as $rt) {
                            $rt['kind'] = 'rejection';
                            $step['interruptions']['types'][] = $rt;
                        }
                        unset($step['rejections']);
                        $changed = true;
                    } elseif (isset($step['rejections'])) {
                        // Empty rejections panel — just drop it
                        unset($step['rejections']);
                        $changed = true;
                    }
                }
                unset($step);
            }
            unset($deptCfg);

            if ($changed) {
                $json = json_encode($data, JSON_UNESCAPED_UNICODE);
                db_query(sprintf(
                    "UPDATE %s SET value = %s WHERE id = %d",
                    CONFIG_TABLE, db_input($json), (int)$row['id']
                ));
            }
        }
    }

    /**
     * Reverse of the bad-v7 alt_steps wrapping: collapse $variant['alt_steps'][0]
     * back into the variant root, strip terminus/rejoin_status. Idempotent — if
     * variant has no alt_steps, returns as-is (already flat).
     */
    private static function flattenAltStepsBackToVariant(&$variant, $defaultAcl) {
        if (empty($variant['alt_steps']) || !is_array($variant['alt_steps']))
            return;

        $first = $variant['alt_steps'][0] ?? array();
        // Promote alt_steps[0] fields back into variant root if not already set
        if (!isset($variant['target_status']))
            $variant['target_status'] = $first['target_status'] ?? '';
        if (!isset($variant['assignment']))
            $variant['assignment'] = $first['assignment'] ?? 'release';
        if (!isset($variant['transfer_dept']))
            $variant['transfer_dept'] = $first['transfer_dept'] ?? '';
        if (!isset($variant['clear_team']))
            $variant['clear_team'] = !empty($first['clear_team']);
        if (!isset($variant['perf_deduction'])) {
            $pmode = $first['perf_mode'] ?? 'off';
            $variant['perf_deduction'] = ($pmode === 'fixed') ? 'fixed' : 'none';
        }
        if (!isset($variant['perf_deduction_value']))
            $variant['perf_deduction_value'] = $first['perf_value'] ?? '0';
        if (!isset($variant['access_control']) && isset($first['access_control']))
            $variant['access_control'] = $first['access_control'];

        // Strip the bad-v7 nested structure
        unset($variant['alt_steps']);
        unset($variant['terminus']);
        unset($variant['rejoin_status']);
    }

    /**
     * @deprecated v7 corrected model: no-op. Variants stay flat.
     */
    private static function migrateVariantToAltSteps(&$variant, $defaultAcl) {
        return;
    }

    /**
     * Convert a legacy flat department config to the v6.0 dynamic steps format.
     * Safe to call on already-converted configs (returns as-is).
     *
     * @param array $deptCfg  Department config (from widget_config.departments[id])
     * @return array  Normalized config with 'steps' array and 'schema_version' = 6
     */
    static function normalizeDeptConfig($deptCfg) {
        // Default per-step perf/interruption values
        $defaultStepPerf = array(
            'perf_mode'         => 'off',
            'perf_value'        => '0',
            'perf_source_field' => '',
            'perf_mappings'     => array(),
        );
        $defaultStepInt = array(
            'interruptions' => array(
                'enabled' => false,
                'label'   => '',
                'color'   => '#e67e22',
                'icon'    => 'icon-pause',
                'types'   => array(),
            ),
        );

        // Already in v6 format — ensure every step has perf/int keys
        if (!empty($deptCfg['schema_version']) && (int)$deptCfg['schema_version'] >= 6
                && isset($deptCfg['steps']) && is_array($deptCfg['steps'])) {
            foreach ($deptCfg['steps'] as &$s) {
                foreach ($defaultStepPerf as $k => $v)
                    if (!isset($s[$k])) $s[$k] = $v;
                if (!isset($s['interruptions']))
                    $s['interruptions'] = $defaultStepInt['interruptions'];
            }
            unset($s);
            return $deptCfg;
        }

        // v5 format — has steps but perf/int at dept level. Migrate to per-step.
        if (!empty($deptCfg['schema_version']) && (int)$deptCfg['schema_version'] >= 2
                && isset($deptCfg['steps']) && is_array($deptCfg['steps'])) {
            $deptPerfMode = $deptCfg['perf_mode'] ?? 'off';
            $deptPerfSrc  = $deptCfg['perf_source_field'] ?? '';
            $deptPerfMap  = $deptCfg['perf_mappings'] ?? array();
            $deptInt      = $deptCfg['interruptions'] ?? $defaultStepInt['interruptions'];

            foreach ($deptCfg['steps'] as &$s) {
                if (!isset($s['perf_mode']))         $s['perf_mode'] = $deptPerfMode;
                if (!isset($s['perf_value']))         $s['perf_value'] = '0';
                if (!isset($s['perf_source_field']))  $s['perf_source_field'] = $deptPerfSrc;
                if (!isset($s['perf_mappings']))      $s['perf_mappings'] = $deptPerfMap;
                if (!isset($s['interruptions']))      $s['interruptions'] = $deptInt;
            }
            unset($s);

            unset($deptCfg['perf_mode']);
            unset($deptCfg['perf_source_field']);
            unset($deptCfg['perf_mappings']);
            unset($deptCfg['interruptions']);
            $deptCfg['schema_version'] = 6;
            return $deptCfg;
        }

        // Legacy flat format — convert to v6
        $variant = $deptCfg['variant'] ?? 'single';
        $steps = array();
        $defaultAC = array('mode' => 'native', 'restrict_to' => array('agents' => array(), 'teams' => array(), 'roles' => array()));
        $stepBase = array_merge($defaultStepPerf, $defaultStepInt);

        if ($variant === 'twostep') {
            $steps[] = array_merge($stepBase, array(
                'trigger_status' => (string)($deptCfg['start_trigger_status'] ?? ''),
                'target_status'  => (string)($deptCfg['start_target_status'] ?? ''),
                'behavior'       => 'claim',
                'transfer_dept'  => '',
                'clear_team'     => false,
                'label'          => $deptCfg['start_label'] ?? '',
                'icon'           => '',
                'color'          => '',
                'access_control' => $defaultAC,
            ));
            $steps[] = array_merge($stepBase, array(
                'trigger_status' => (string)($deptCfg['start_target_status'] ?? ''),
                'target_status'  => (string)($deptCfg['step2_trigger_status'] ?? ''),
                'behavior'       => 'release',
                'transfer_dept'  => '',
                'clear_team'     => false,
                'label'          => $deptCfg['partial_label'] ?? '',
                'icon'           => '',
                'color'          => '',
                'access_control' => $defaultAC,
            ));
            $steps[] = array_merge($stepBase, array(
                'trigger_status' => (string)($deptCfg['step2_trigger_status'] ?? ''),
                'target_status'  => (string)($deptCfg['step2_target_status'] ?? ''),
                'behavior'       => 'claim',
                'transfer_dept'  => '',
                'clear_team'     => false,
                'label'          => $deptCfg['start2_label'] ?? '',
                'icon'           => '',
                'color'          => '',
                'access_control' => $defaultAC,
            ));
            $steps[] = array_merge($stepBase, array(
                'trigger_status' => (string)($deptCfg['step2_target_status'] ?? ''),
                'target_status'  => (string)($deptCfg['step2_stop_target_status'] ?? ''),
                'behavior'       => 'release',
                'transfer_dept'  => (string)($deptCfg['stop_transfer_dept'] ?? ''),
                'clear_team'     => !empty($deptCfg['step2_clear_team']),
                'label'          => $deptCfg['finish_label'] ?? '',
                'icon'           => '',
                'color'          => '',
                'access_control' => $defaultAC,
            ));
        } else {
            $steps[] = array_merge($stepBase, array(
                'trigger_status' => (string)($deptCfg['start_trigger_status'] ?? ''),
                'target_status'  => (string)($deptCfg['start_target_status'] ?? ''),
                'behavior'       => 'claim',
                'transfer_dept'  => '',
                'clear_team'     => false,
                'label'          => $deptCfg['start_label'] ?? '',
                'icon'           => '',
                'color'          => '',
                'access_control' => $defaultAC,
            ));
            $steps[] = array_merge($stepBase, array(
                'trigger_status' => (string)($deptCfg['start_target_status'] ?? ''),
                'target_status'  => (string)($deptCfg['stop_target_status'] ?? ''),
                'behavior'       => 'release',
                'transfer_dept'  => (string)($deptCfg['stop_transfer_dept'] ?? ''),
                'clear_team'     => !empty($deptCfg['clear_team']),
                'label'          => $deptCfg['stop_label'] ?? '',
                'icon'           => '',
                'color'          => '',
                'access_control' => $defaultAC,
            ));
        }

        return array(
            'enabled'        => !empty($deptCfg['enabled']),
            'schema_version' => 6,
            'steps'          => $steps,
        );
    }

    // ================================================================
    //  Standard plugin hooks
    // ================================================================

    static function registerTranslations() {
        if (method_exists('Plugin', 'translate')) {
            list($__, $_N) = Plugin::translate('quick-buttons');
        }
    }

    static function bootstrapStatic() {
        if (self::$bootstrapped)
            return;
        self::$bootstrapped = true;

        self::registerTranslations();

        if (!defined('STAFFINC_DIR'))
            return;

        Signal::connect('ajax.scp', array('QuickButtonsPlugin', 'registerAjaxRoutes'));
        ob_start(array('QuickButtonsPlugin', 'injectAssets'));
    }

    static function registerAjaxRoutes($dispatcher) {
        $dir = INCLUDE_DIR . 'plugins/quick-buttons/';
        $dispatcher->append(
            url('^/quick-buttons/', patterns(
                $dir . 'class.QuickButtonsAjax.php:QuickButtonsAjax',
                url('^widgets$', 'getWidgets'),
                url_post('^execute$', 'execute'),
                url_post('^undo$', 'undo'),
                url_post('^upgrade$', 'executeUpgradeAjax'),
                url_get('^check-update$', 'checkForUpdate'),
                url_post('^apply-update$', 'applyUpdate'),
                url_get('^update-status$', 'updateStatus'),
                url_post('^rollback-update$', 'rollbackUpdate'),
                url_get('^update-backups$', 'listUpdateBackups'),
                url_get('^dashboard$', 'dashboard'),
                url_get('^dashboard-page$', 'serveDashboardPage'),
                url_get('^agent-perf-page$', 'serveAgentPerfPage'),
                url_get('^workflow-builder$', 'serveWorkflowBuilder'),
                url_post('^workflow-builder-save$', 'saveWorkflowBuilder'),
                url_get ('^workflow-builder/map$', 'workflowBuilderMap'),
                url_get ('^workflow-builder/validate$', 'workflowBuilderValidate'),
                // v8.4.0 — config backup + restore
                url_get ('^workflow-builder/backups$', 'workflowBuilderBackups'),
                url_post('^workflow-builder/restore$', 'workflowBuilderRestore'),
                url_get('^assets/js$', 'serveJs'),
                url_get('^assets/css$', 'serveCss'),
                url_get('^assets/admin-js$', 'serveAdminJs'),
                url_get('^assets/admin-css$', 'serveAdminCss'),
                url_get('^dept-status-map$', 'getDeptStatusMap'),
                url_post('^dept-status-map-save$', 'saveDeptStatusMap'),
                url_get('^perf-list-fields$', 'getPerfListFields'),
                url_get('^perf-list-items/(?P<field_id>\d+)$', 'getPerfListItems'),
                url_post('^interrupt$', 'interrupt'),
                url_post('^resume$', 'resume'),
                url_post('^advance-alt-step$', 'advanceAltStep'),
                url_get('^icons/list$', 'iconList'),
                url_post('^icons/upload$', 'iconUpload'),
                url_get('^icons/(?P<id>\d+)$', 'iconServe'),
                url_get('^assets/icon-picker-js$', 'serveIconPickerJs'),
                url_get('^assets/icon-picker-css$', 'serveIconPickerCss')
            ))
        );
    }

    /**
     * v8.3.1 — return cached QB plugin id, or 0 if not yet installed.
     * Used by injectAssets() to scope admin asset injection.
     */
    private static $qbPluginIdCache = null;
    public static function getQbPluginId() {
        if (self::$qbPluginIdCache === null) {
            $p = Plugin::objects()->findFirst(array('install_path' => 'plugins/quick-buttons'));
            self::$qbPluginIdCache = $p ? (int)$p->getId() : 0;
        }
        return self::$qbPluginIdCache;
    }

    /**
     * v8.5.2 — return the QB Plugin object (or null if not installed).
     * Used by job state helpers + finalizeUpdate + rollbackUpdate.
     *
     * IMPORTANT: v8.5.0/v8.5.1 called self::findPlugin() in six places but
     * never defined this method. Every call became a PHP fatal — apply-update
     * and update-status both returned HTTP 500 with empty body in production.
     * This v8.5.2 restoration is the bug fix.
     */
    private static $qbPluginObjectCache = null;
    public static function findPlugin() {
        if (self::$qbPluginObjectCache === null) {
            $p = Plugin::objects()->findFirst(array('install_path' => 'plugins/quick-buttons'));
            self::$qbPluginObjectCache = $p ?: false;
        }
        return self::$qbPluginObjectCache ?: null;
    }

    /**
     * v8.3.1 — pure gate logic: should QB admin assets (admin-css/admin-js +
     * Updates tab) be injected for this request?
     *
     * Yes only when:
     *   - request URI contains 'plugins.php' (admin Plugins area)
     *   - URL has an explicit ?id=<N> parameter (single-plugin detail page,
     *     not the plugin list)
     *   - that N matches the QB plugin's own id (avoids contaminating other
     *     plugins' detail pages with QB's Updates tab)
     *
     * Pure — extracted for unit-testability without needing the OB callback
     * or osTicket bootstrap. See tests/QuickButtonsTest.php::testInjectAdminAssetsScope.
     */
    public static function shouldInjectAdminAssets($requestUri, $urlPluginId, $qbPluginId) {
        if ($requestUri === null || strpos($requestUri, 'plugins.php') === false) return false;
        if (!$qbPluginId) return false;
        return ((int)$urlPluginId === (int)$qbPluginId);
    }

    static function injectAssets($buffer) {
        if (!empty($_SERVER['HTTP_X_PJAX']))
            return $buffer;

        if (strpos($buffer, '</head>') === false
                || strpos($buffer, '</body>') === false)
            return $buffer;

        // Inject upgrade banner on admin pages if upgrade is pending
        $isAdminPage = (strpos($_SERVER['REQUEST_URI'] ?? '', 'admin.php') !== false
            || strpos($_SERVER['REQUEST_URI'] ?? '', 'plugins.php') !== false);
        if ($isAdminPage)
            self::injectUpgradeBanner($buffer);

        $base = ROOT_PATH . 'scp/ajax.php/quick-buttons/assets';
        $dir = dirname(__FILE__) . '/assets/';
        $v = max(
            @filemtime($dir . 'quick-buttons.js'),
            @filemtime($dir . 'quick-buttons.css'),
            @filemtime($dir . 'quick-buttons-default.css')
        ) ?: time();

        // v8.4.2: reverted v8.4.0 explicit osta/css/svg.css injection.
        // The injection brought in osta's generic `i, i[class^="icon-"]` rule
        // (width:20px, height:20px, color:#128dbe, position:relative top:4px)
        // which OVERRODE FontAwesome's content/glyph rule for icons not packaged
        // by osta (e.g. icon-play). Result: agent queue action buttons showed
        // empty / offset glyphs instead of the play arrow. Theme already loads
        // svg.css when active, so QB's duplicate inject was both unnecessary
        // and harmful.
        // The original Bug 2b symptom (icons fail after save) was a transient
        // theme-bootstrap race that affected only some reload contexts. If it
        // recurs, the fix path is to ensure the theme stylesheet loads
        // synchronously (theme issue), not to duplicate it from the plugin.
        $css = sprintf(
            '<link rel="stylesheet" type="text/css" href="%s/css?v=%s">',
            $base, $v);
        $js = sprintf(
            '<script type="text/javascript" src="%s/js?v=%s"></script>',
            $base, $v);
        $adminCss = sprintf(
            '<link rel="stylesheet" type="text/css" href="%s/admin-css?v=%s">',
            $base, $v);
        $adminJs = sprintf(
            '<script type="text/javascript" src="%s/admin-js?v=%s"></script>',
            $base, $v);

        // v8.3.1 — gate admin asset injection on this plugin's own detail page only.
        // Previously injected on every plugins.php page, causing the Updates tab to
        // appear (with QB version + QB AJAX endpoint) on UNRELATED plugin admin pages.
        $isQbPluginPage = self::shouldInjectAdminAssets(
            $_SERVER['REQUEST_URI'] ?? '',
            isset($_GET['id']) ? (int)$_GET['id'] : 0,
            self::getQbPluginId()
        );

        $headInject = $css;
        $bodyInject = $js;
        if ($isQbPluginPage) {
            $headInject .= "\n" . $adminCss;
            $bodyInject .= "\n" . $adminJs;
        }

        $buffer = str_replace('</head>', $headInject . "\n</head>", $buffer);
        $buffer = str_replace('</body>', $bodyInject . "\n</body>", $buffer);

        return $buffer;
    }
}

// Static bootstrap
if (defined('STAFFINC_DIR'))
    QuickButtonsPlugin::bootstrapStatic();