openclaw-plugin-vt-sentinel 0.7.0 → 0.8.1

package/dist/index.d.ts

@@ -39,11 +39,38 @@ interface PluginApi {
     registerHook?: (events: string | string[], handler: (event: any) => Promise<any>, opts?: object) => void;
     onToolResult?: (handler: (event: any) => Promise<any>) => void;
 }
+/**
+ * Read current plugin version from package.json.
+ */
+declare function getCurrentVersion(): string;
 /**
  * Simple semver comparison: returns true if `latest` is newer than `current`.
  * Only handles x.y.z format (no pre-release tags).
  */
 export declare function isNewerVersion(latest: string, current: string): boolean;
+/**
+ * Fetch latest version string from npm registry. Returns null on error.
+ * Single source of truth — used by checkForUpdates() and vt_sentinel_update.
+ */
+declare function fetchLatestVersion(): Promise<string | null>;
+/**
+ * Get the OpenClaw state directory (respects OPENCLAW_STATE_DIR env var).
+ */
+declare function getStateDir(): string;
+/**
+ * Generate update instructions or preview. Pure function — all inputs are arguments.
+ * Returns text for the agent/user.
+ */
+declare function generateUpdateCommands(opts: {
+    currentVersion: string;
+    latestVersion: string;
+    confirm: boolean;
+    stateDir: string;
+}): string;
 export declare function isSelfPath(filePath: string): boolean;
 export default function vtSentinelPlugin(api: PluginApi): void;
+export declare const _generateUpdateCommands: typeof generateUpdateCommands;
+export declare const _fetchLatestVersion: typeof fetchLatestVersion;
+export declare const _getCurrentVersion: typeof getCurrentVersion;
+export declare const _getStateDir: typeof getStateDir;
 export {};

package/dist/index.js

@@ -36,6 +36,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports._getStateDir = exports._getCurrentVersion = exports._fetchLatestVersion = exports._generateUpdateCommands = void 0;
 exports.isNewerVersion = isNewerVersion;
 exports.isSelfPath = isSelfPath;
 exports.default = vtSentinelPlugin;
@@ -78,6 +79,17 @@ function textResponse(text) {
 // --- Update Check ---
 const PACKAGE_NAME = 'openclaw-plugin-vt-sentinel';
 const NPM_REGISTRY_URL = `https://registry.npmjs.org/${PACKAGE_NAME}/latest`;
+/**
+ * Read current plugin version from package.json.
+ */
+function getCurrentVersion() {
+    try {
+        return JSON.parse(fs.readFileSync(path.resolve(__dirname, '..', 'package.json'), 'utf-8')).version || '0.0.0';
+    }
+    catch {
+        return '0.0.0';
+    }
+}
 /**
  * Simple semver comparison: returns true if `latest` is newer than `current`.
  * Only handles x.y.z format (no pre-release tags).
@@ -94,21 +106,98 @@ function isNewerVersion(latest, current) {
     return false;
 }
 /**
- * Check npm registry for a newer version. Fire-and-forget, never throws.
+ * Fetch latest version string from npm registry. Returns null on error.
+ * Single source of truth — used by checkForUpdates() and vt_sentinel_update.
  */
-async function checkForUpdates(logger) {
+async function fetchLatestVersion() {
     try {
-        const pkgPath = path.resolve(__dirname, '..', 'package.json');
-        const currentVersion = JSON.parse(fs.readFileSync(pkgPath, 'utf-8')).version;
         const resp = await axios_1.default.get(NPM_REGISTRY_URL, { timeout: 5000 });
-        const latestVersion = resp.data?.version;
-        if (latestVersion && isNewerVersion(latestVersion, currentVersion)) {
+        return resp.data?.version || null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Get the OpenClaw state directory (respects OPENCLAW_STATE_DIR env var).
+ */
+function getStateDir() {
+    return process.env.OPENCLAW_STATE_DIR || path.join(os.homedir(), '.openclaw');
+}
+/**
+ * Generate update instructions or preview. Pure function — all inputs are arguments.
+ * Returns text for the agent/user.
+ */
+function generateUpdateCommands(opts) {
+    if (!isNewerVersion(opts.latestVersion, opts.currentVersion)) {
+        return `VT Sentinel v${opts.currentVersion} is already the latest version.`;
+    }
+    if (!opts.confirm) {
+        const lines = [];
+        lines.push(`Update available: v${opts.currentVersion} → v${opts.latestVersion}`);
+        lines.push('');
+        lines.push('What will happen:');
+        lines.push('  - The plugin will be updated to the latest version');
+        lines.push('  - Your configuration, audit logs, and VTAI credentials are preserved');
+        lines.push('  - The gateway will need to be restarted');
+        lines.push('');
+        lines.push('Call vt_sentinel_update with confirm: true to get the upgrade commands.');
+        return lines.join('\n');
+    }
+    const stateDir = opts.stateDir;
+    const quotedExtDir = `"${path.join(stateDir, 'extensions', PACKAGE_NAME)}"`;
+    const configPath = path.join(stateDir, 'openclaw.json');
+    const lines = [];
+    lines.push(`Upgrade: v${opts.currentVersion} → v${opts.latestVersion}`);
+    lines.push('');
+    lines.push('Run these commands in a separate terminal (stopping the gateway will end this chat session):');
+    lines.push('');
+    lines.push('  1. openclaw gateway stop');
+    lines.push(`  2. openclaw plugins update ${PACKAGE_NAME}`);
+    lines.push('  3. openclaw gateway start');
+    lines.push('');
+    lines.push('Your configuration, audit logs, and credentials are preserved.');
+    lines.push('After restart, use vt_sentinel_status to verify the new version.');
+    lines.push('');
+    lines.push('---');
+    lines.push('If step 2 reports "already at X.Y.Z", the install spec may be version-pinned.');
+    lines.push('In that case, replace step 2 with:');
+    lines.push('');
+    lines.push(`  2a. Remove the extension directory:`);
+    lines.push(`      rm -rf ${quotedExtDir}    (Linux/macOS)`);
+    lines.push(`      rmdir /s /q ${quotedExtDir.replace(/\//g, '\\\\')}   (Windows)`);
+    lines.push('');
+    lines.push(`  2b. Back up and clean the config entry:`);
+    // Generate a safe node -e script for config cleanup
+    const cleanupScript = `node -e "const fs=require('fs'),p='${configPath.replace(/\\/g, '\\\\').replace(/'/g, "\\'")}';try{const b=fs.readFileSync(p,'utf8');fs.writeFileSync(p+'.bak',b);const c=JSON.parse(b);if(c.plugins){delete(c.plugins.entries||{})['${PACKAGE_NAME}'];delete(c.plugins.installs||{})['${PACKAGE_NAME}'];}fs.writeFileSync(p,JSON.stringify(c,null,2));console.log('Config cleaned (backup: '+p+'.bak)')}catch(e){console.error('Failed: '+e.message);process.exit(1)}"`;
+    lines.push(`      ${cleanupScript}`);
+    lines.push('');
+    lines.push(`  2c. Reinstall:`);
+    lines.push(`      openclaw plugins install ${PACKAGE_NAME}`);
+    return lines.join('\n');
+}
+/**
+ * Check npm registry for a newer version. Fire-and-forget, never throws.
+ */
+async function checkForUpdates(logger, callbacks) {
+    try {
+        const currentVersion = getCurrentVersion();
+        const latestVersion = await fetchLatestVersion();
+        if (!latestVersion) {
+            callbacks?.onError();
+            return;
+        }
+        if (isNewerVersion(latestVersion, currentVersion)) {
             logger.info(`[VT-Sentinel] Update available: ${currentVersion} → ${latestVersion}. ` +
-                `Run: openclaw plugins install ${PACKAGE_NAME}`);
+                `Use vt_sentinel_update to check upgrade instructions.`);
+            callbacks?.onNewer(latestVersion);
+        }
+        else {
+            callbacks?.onUpToDate();
         }
     }
     catch {
-        // Best-effort — silently ignore network/parse errors
+        callbacks?.onError();
     }
 }
 // --- Self-exclusion: never scan/quarantine our own plugin files ---
@@ -138,6 +227,9 @@ function vtSentinelPlugin(api) {
     let scanner = null;
     /** Tracks root directories passed to chokidar. Never use getWatched() for diffs. */
     const watchRoots = new Set();
+    // Update check state (closure-scoped, not module-level)
+    let latestKnownVersion = null;
+    let updateCheckFailed = false;
     const getConfig = () => {
         const entry = api.config?.plugins?.entries?.['openclaw-plugin-vt-sentinel'];
         return entry?.config ?? null;
@@ -701,15 +793,6 @@ function vtSentinelPlugin(api) {
             }
         },
     });
-    // --- Helper: get current plugin version ---
-    const getCurrentVersion = () => {
-        try {
-            return JSON.parse(fs.readFileSync(path.resolve(__dirname, '..', 'package.json'), 'utf-8')).version || '0.0.0';
-        }
-        catch {
-            return '0.0.0';
-        }
-    };
     // --- Helper: apply config changes to scanner and watcher ---
     const applyConfigChange = (diff, newConfig) => {
         if (diff.scannerNeedsRebuild && scanner) {
@@ -782,6 +865,9 @@ function vtSentinelPlugin(api) {
                 blockedFileCount: blocklist.size,
                 runtimeOverrideCount: Object.keys(configManager.getRuntimeOverrides()).length,
                 presetName: eff.configPreset,
+                updateAvailable: latestKnownVersion != null && !updateCheckFailed,
+                latestVersion: latestKnownVersion || undefined,
+                updateCheckFailed,
             }));
         },
     });
@@ -930,6 +1016,48 @@ function vtSentinelPlugin(api) {
             return textResponse((0, status_renderer_1.renderHelp)());
         },
     });
+    // --- Tool: vt_sentinel_update ---
+    api.registerTool({
+        name: 'vt_sentinel_update',
+        description: 'Check for VT Sentinel updates and get upgrade instructions. Call with confirm: true to generate the exact commands to run in a separate terminal.',
+        parameters: {
+            type: 'object',
+            properties: {
+                confirm: {
+                    type: 'boolean',
+                    description: 'Set true to generate upgrade commands (default: just checks for updates)',
+                },
+            },
+            required: [],
+        },
+        execute: async (_ctx, rawParams) => {
+            const params = rawParams || {};
+            // Strict validation: reject non-boolean confirm
+            if ('confirm' in params && typeof params.confirm !== 'boolean') {
+                return textResponse('Error: confirm must be true or false');
+            }
+            const latestVersion = await fetchLatestVersion();
+            if (!latestVersion) {
+                updateCheckFailed = true;
+                return textResponse('Error: Could not reach npm registry. Check internet connectivity and try again.');
+            }
+            const currentVersion = getCurrentVersion();
+            if (isNewerVersion(latestVersion, currentVersion)) {
+                latestKnownVersion = latestVersion;
+                updateCheckFailed = false;
+            }
+            else {
+                latestKnownVersion = null;
+                updateCheckFailed = false;
+            }
+            return textResponse(generateUpdateCommands({
+                currentVersion,
+                latestVersion,
+                confirm: params.confirm === true,
+                stateDir: getStateDir(),
+            }));
+        },
+    });
     // --- Hook: auto-scan tool results ---
     const handleToolResult = async (event) => {
         const s = await ensureScanner();
@@ -946,10 +1074,8 @@ function vtSentinelPlugin(api) {
             };
             if (!stateStore.isFirstRunShown(scope)) {
                 try {
-                    const pkgPath = path.resolve(__dirname, '..', 'package.json');
-                    const version = JSON.parse(fs.readFileSync(pkgPath, 'utf-8')).version || '0.0.0';
                     const onboardingText = (0, status_renderer_1.renderOnboarding)({
-                        version,
+                        version: getCurrentVersion(),
                         apiMode: process.env.VIRUSTOTAL_API_KEY === 'vtai-active' ? 'vtai' : 'user_key',
                         watchDirs: [...watchRoots],
                         effectiveConfig: configManager.getEffective(),
@@ -957,6 +1083,7 @@ function vtSentinelPlugin(api) {
                             'vt_scan_file', 'vt_check_hash', 'vt_upload_consent',
                             'vt_sentinel_status', 'vt_sentinel_configure',
                             'vt_sentinel_reset_policy', 'vt_sentinel_help',
+                            'vt_sentinel_update',
                         ],
                     });
                     const injected = injectOnboarding(event, onboardingText);
@@ -1171,9 +1298,13 @@ function vtSentinelPlugin(api) {
     vtSentinelPlugin._computeAutoWatchDirs = computeAutoWatchDirs;
     vtSentinelPlugin._handleWatcherFile = handleWatcherFile;
     vtSentinelPlugin._enrichFromContext = enrichFromContext;
-    api.logger.info('[VT-Sentinel] Plugin loaded — 7 tools + active protection hooks registered (VTAI auto-registration enabled)');
+    api.logger.info('[VT-Sentinel] Plugin loaded — 8 tools + active protection hooks registered (VTAI auto-registration enabled)');
     // Non-blocking update check (fire-and-forget)
-    checkForUpdates(api.logger);
+    checkForUpdates(api.logger, {
+        onNewer: (v) => { latestKnownVersion = v; updateCheckFailed = false; },
+        onUpToDate: () => { latestKnownVersion = null; updateCheckFailed = false; },
+        onError: () => { updateCheckFailed = true; },
+    });
 }
 // --- Hook helpers ---
 function extractResultText(event) {
@@ -1228,3 +1359,9 @@ function injectWarning(event, result) {
         event.toolResult._vtSentinelWarning = warning;
     }
 }
+// --- Test exports ---
+// Exported for unit testing only. Not part of the public API.
+exports._generateUpdateCommands = generateUpdateCommands;
+exports._fetchLatestVersion = fetchLatestVersion;
+exports._getCurrentVersion = getCurrentVersion;
+exports._getStateDir = getStateDir;

package/dist/status-renderer.d.ts

@@ -14,6 +14,9 @@ export declare function renderStatus(opts: {
     blockedFileCount: number;
     runtimeOverrideCount: number;
     presetName: string;
+    updateAvailable?: boolean;
+    latestVersion?: string;
+    updateCheckFailed?: boolean;
 }): string;
 export declare function renderPolicyMatrix(config: FullConfig): string;
 export declare function renderHelp(): string;

package/dist/status-renderer.js

@@ -38,6 +38,12 @@ function renderStatus(opts) {
     const lines = [];
     const cfg = opts.effectiveConfig;
     lines.push(`VT Sentinel v${opts.version} — Status`);
+    if (opts.updateAvailable && opts.latestVersion) {
+        lines.push(`  Update available: v${opts.version} → v${opts.latestVersion} — use vt_sentinel_update for upgrade instructions`);
+    }
+    else if (opts.updateCheckFailed) {
+        lines.push('  Update check: last check failed (network error). Use vt_sentinel_update to retry.');
+    }
     lines.push('');
     // Config
     lines.push('Effective Configuration:');
@@ -138,6 +144,9 @@ function renderHelp() {
     lines.push('  vt_sentinel_help {}');
     lines.push('    Show this guide');
     lines.push('');
+    lines.push('  vt_sentinel_update { confirm: true }');
+    lines.push('    Check for updates and get upgrade instructions');
+    lines.push('');
     lines.push('PRESETS:');
     lines.push('  balanced (default)');
     lines.push('    Ask before uploading sensitive files. Quarantine malicious. Log all scans.');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openclaw-plugin-vt-sentinel",
-  "version": "0.7.0",
+  "version": "0.8.1",
   "description": "VirusTotal Sentinel for OpenClaw - Malware detection and AI-powered code analysis",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/skills/vt-sentinel/SKILL.md

@@ -140,6 +140,14 @@ Shows usage examples, privacy explanation, and available presets.
 vt_sentinel_help {}
 ```
 
+### `vt_sentinel_update` — Check for Updates
+Checks npm for a newer version and generates upgrade instructions.
+
+```
+vt_sentinel_update {}
+vt_sentinel_update { "confirm": true }
+```
+
 ## Active Protection
 
 VT Sentinel automatically protects the system in real-time: