{
  "name": "my-awesome-plugin",
  "version": "1.0.0",
  "displayName": "My Awesome Plugin",
  "description": "A one-sentence description of your plugin.",
  "author": "Your Name <email@example.com>",
  "main": "main.js",
  "getssh": {
    "pluginId": "com.example.my-awesome-plugin",
    "type": "sandbox",
    "capabilities": ["lifecycle"]
  }
}

window.GETSSH = {
  /**
   * Registers a clickable icon button in the sidebar.
   * @param id      Unique ID for the button (unique within your plugin)
   * @param icon    SVG string (automatically sanitized; malicious scripts stripped)
   * @param label   Label text shown on hover
   */
  registerSidebarAction(id: string, icon: string, label: string): void;

  /**
   * Pops up a system notification (requires user permission).
   * @param title Notification title
   * @param body  Notification body
   */
  showNotification(title: string, body: string): void;

  /**
   * Synchronously reads the host app's current locale (e.g., 'zh-CN', 'en-US').
   * This is a snapshot and will not update automatically. To listen for changes, use onThemeChange.
   */
  getLocale(): string;

  /**
   * Subscribes to host app theme change events.
   * Triggered whenever the user switches between dark/light/system modes in settings.
   * @param callback Receives the new theme value: 'dark' | 'light' | 'system'
   */
  onThemeChange(callback: (theme: 'dark' | 'light' | 'system') => void): void;
}

/**
 * Handler dictionary for sidebar button click events.
 * The key MUST match the id provided in registerSidebarAction.
 */
window.__sidebarHandlers: Record<string, () => void>;

// Synchronously read locale settings on startup
const locale = window.GETSSH.getLocale();
document.getElementById('greeting').textContent =
  locale.startsWith('zh') ? '你好，世界！' : 'Hello, World!';

// Respond to theme switches in real-time
window.GETSSH.onThemeChange((theme) => {
  document.body.setAttribute('data-theme', theme);
  // Example: Update CSS variables, chart color schemes, etc.
});

window.addEventListener('message', (event) => {
  // ALWAYS verify the message type to avoid processing irrelevant messages
  if (event.data.type === 'sysmon:data') {
    // See Section 7: System Monitoring Data Stream
    const { cpus, mem, net } = event.data.payload;
  }
});

interface MainContextAPI {
  /**
   * @deprecated Please use ctx.host.notify() for new plugins.
   * Pops up a native desktop notification.
   */
  showNotification(title: string, body: string): void;

  /**
   * Encrypts a string using Electron's OS-level encryption capabilities.
   * The key is managed by the OS Keychain and is bound to the current user account.
   */
  safeStorageEncrypt(text: string): string;

  /**
   * Listens to SSH session connection events (Read-only).
   * Triggered whenever the user successfully establishes a new SSH connection.
   * @param callback sessionId is the internal GETSSH session ID, host is the target hostname
   */
  onSSHSessionConnect?(callback: (sessionId: string, host: string) => void): void;

  /**
   * Persistent Key-Value storage, providing isolated namespaces for each plugin.
   */
  storage: {
    get(key: string): Promise<any>;
    set(key: string, value: any): Promise<void>;
    delete(key: string): Promise<void>;
    clear(): Promise<void>;
  };

  /**
   * Two-way RPC communication bridge between the Backend VM and Frontend iframe plugins.
   */
  rpc: {
    /** Registers a method that the frontend can call via pluginRpcInvoke(). */
    registerMethod(method: string, handler: (payload: any) => Promise<any>): void;
    /** Proactively pushes data to the frontend, which listens via onPluginRpcMessage(). */
    sendToFrontend(payload: any): void;
  };

  /**
   * Native Host Integration APIs.
   * ♥️ All dialog invocations leave a [Plugin Host API] audit trail in the main process logs.
   */
  host: {
    /**
     * Sends an OS-native desktop notification directly from the backend plugin.
     * The notification pops up regardless of what interface the user is looking at. Ideal for server monitoring/alerting plugins.
     * @param title  Notification title
     * @param body   Notification body
     * @param type   Visual intent: 'info' (default) | 'warning' | 'error'
     */
    notify(title: string, body: string, type?: 'info' | 'warning' | 'error'): void;

    /**
     * Pops up an OS-native message/confirmation dialog.
     * Returns a Promise containing the index of the clicked button.
     * @param options.type        Dialog icon type: 'none' | 'info' | 'warning' | 'error' | 'question'
     * @param options.buttons     Array of button texts, e.g., ['OK', 'Cancel']
     * @param options.message     Main message text (displayed in bold)
     * @param options.detail      Secondary text (smaller font, optional)
     * @param options.defaultId   Index of the button to focus by default
     * @param options.cancelId    Index of the button treated as clicked when Escape is pressed
     * @param options.checkboxLabel Bottom checkbox text (optional)
     * @returns { response: number (clicked button index), checkboxChecked: boolean }
     */
    showMessageBox(options: {
      type?: 'none' | 'info' | 'warning' | 'error' | 'question';
      buttons?: string[];
      defaultId?: number;
      cancelId?: number;
      title?: string;
      message: string;
      detail?: string;
      checkboxLabel?: string;
    }): Promise<{ response: number; checkboxChecked: boolean }>;

    /**
     * Pops up an OS-native file/directory picker.
     * Security Guarantee: The plugin ONLY receives the file path strings and CANNOT read the file contents directly.
     * @param options.properties  Selection mode: 'openFile' | 'openDirectory' | 'multiSelections' | 'showHiddenFiles'
     * @param options.filters     File type filters, e.g., [{ name: 'Images', extensions: ['png', 'jpg'] }]
     * @returns { canceled: boolean, filePaths: string[] }
     */
    showOpenDialog(options: {
      title?: string;
      defaultPath?: string;
      filters?: { name: string; extensions: string[] }[];
      properties?: Array<'openFile' | 'openDirectory' | 'multiSelections' | 'showHiddenFiles'>;
    }): Promise<{ canceled: boolean; filePaths: string[] }>;

    /**
     * Pops up an OS-native file save path picker.
     * @param options.filters File type filters
     * @returns { canceled: boolean, filePath?: string }
     */
    showSaveDialog(options: {
      title?: string;
      defaultPath?: string;
      filters?: { name: string; extensions: string[] }[];
    }): Promise<{ canceled: boolean; filePath?: string }>;
  };

  /**
   * SSH I/O Communication Bridge (Requires 'ssh:read' and 'ssh:write' in capabilities).
   */
  ssh?: {
    onData(sessionId: string, callback: (chunk: string) => void): void;
    write(sessionId: string, command: string): void;
  };

  /**
   * UI Extension Points — Inject custom menu items into native context menus, or register plugin settings.
   * See Section 8 for details.
   */
  ui: {
    registerTerminalContextMenu(actionId: string, label: string, handler: (context: { sessionId: string, selectionText: string }) => void): void;
    registerSFTPContextMenu(actionId: string, label: string, handler: (context: { sessionId: string, currentPath: string, selectedFiles: string[] }) => void): void;
    
    /**
     * [MANDATORY REQUIREMENT] Register the plugin's parameter configuration Schema.
     * All backend plugins MUST call this method exactly once during activate().
     * Your plugin MUST provide at least one configuration parameter. Passing an empty array `[]` is strictly prohibited, and will be intercepted on the spot, causing the kernel to reject the plugin.
     */
    registerSettings(schema: PluginSettingsSchema[]): void;
  };
}

// ① Show a confirmation dialog and wait for user response
const result = await ctx.host.showMessageBox({
  type: 'warning',
  title: 'Action Confirmation',
  message: 'Are you sure you want to delete this configuration file?',
  detail: 'This action cannot be undone.',
  buttons: ['Delete', 'Cancel'],
  defaultId: 1,    // Focus "Cancel" by default
  cancelId: 1,
});
if (result.response === 0) {
  // User clicked "Delete" (Index 0)
}

// ② Pop up a file picker to let the user select a configuration file
const open = await ctx.host.showOpenDialog({
  title: 'Select Configuration File',
  filters: [{ name: 'JSON Config', extensions: ['json'] }],
  properties: ['openFile'],
});
if (!open.canceled) {
  const configPath = open.filePaths[0];
  // Process the path using ctx.storage or other controlled APIs...
}

// ③ Pop up a file save dialog to let the user choose an export path
const save = await ctx.host.showSaveDialog({
  title: 'Export Audit Report',
  defaultPath: 'audit-report.csv',
  filters: [{ name: 'CSV', extensions: ['csv'] }],
});
if (!save.canceled && save.filePath) {
  // save.filePath is the full local path chosen by the user
}

Declares type: "sandbox"
         │
         ▼
[PluginManager] sees the sandbox flag
         │
         ▼
The Node.js loader in the main process executes an immediate 'return',
Reading NO code and executing NO main.js code
         │
         ▼
PluginBridge traps it inside an iframe prison
(sandbox="allow-scripts", NO allow-same-origin)
         │
         ▼
It can ONLY communicate with GETSSH via postMessage
         │
         ▼
PluginBridge Whitelist Interceptor:
Any operation outside the whitelist → Dropped immediately + Security Log Alert

let pollingInterval = null;
let openFileHandle = null;

module.exports = {
  activate(ctx) {
    openFileHandle = fs.openSync('/tmp/plugin.log', 'w');
    pollingInterval = setInterval(() => {
      // Periodic operations...
    }, 1000);
  },

  deactivate() {
    // ✅ MANDATORY: Clear all timers
    if (pollingInterval) {
      clearInterval(pollingInterval);
      pollingInterval = null;
    }

    // ✅ MANDATORY: Close all file handles
    if (openFileHandle !== null) {
      fs.closeSync(openFileHandle);
      openFileHandle = null;
    }

    // ✅ MANDATORY: Disconnect all network connections
    // socket.destroy(); socket = null;

    // ✅ MANDATORY: Remove all event listeners
    // emitter.removeAllListeners();
  }
};

User selects "Restart into Safe Mode immediately" in the RASP modal
          │
          ▼
SecureCenter.handleAction('restart-safe')
          │
          ▼
① Invokes pluginTeardownFn()
          │
          ▼
② PluginManager.deactivateAll()
   ─ Iterates over all runningPlugins
   ─ Invokes deactivate() in a try/catch block for each plugin
          │
          ▼
③ Dispatches ACTION:RESTART-SAFE to the Watchdog
          │
          ▼
④ app.exit(0)

{
  "name": "my-plugin",
  "version": "1.0.0",
  "displayName": "My Backend Plugin",
  "description": "A backend plugin example.",
  "main": "main.js",
  "getssh": {
    "pluginId": "com.example.my-backend-plugin",
    "capabilities": ["lifecycle"]
  }
}

module.exports = {
  activate(ctx) {
    // ✅ MANDATORY: Provide at least one actual configuration parameter!
    ctx.ui.registerSettings([
      { id: 'debugMode', type: 'boolean', label: 'Enable Debug', default: false }
    ]);
    // If this is omitted or an empty array is passed, GETSSH will intercept the plugin startup, throw an exception, and destroy it immediately.
  },
  deactivate() {
    // Actual resource release logic
  }
}

// Listen for this message in your sandbox plugin HTML/JS:
window.addEventListener('message', (event) => {
  if (event.data.type !== 'sysmon:data') return;

  const payload: SysmonPayload = event.data.payload;
});

interface SysmonPayload {
  cpus: {
    overall: number;   // Global CPU utilization, range 0-100
    cores: number[];   // Array of independent core utilization, range 0-100
  };
  mem: {
    total: number;     // Total memory (bytes)
    used: number;      // Used memory (bytes)
    free: number;      // Free memory (bytes)
  };
  net: {
    rx: number;        // Bytes received since last tick
    tx: number;        // Bytes transmitted since last tick
  };
}

<!-- index.html -->
<div id="cpu">--</div>
<div id="mem">--</div>
<script>
window.addEventListener('message', (e) => {
  if (e.data.type !== 'sysmon:data') return;
  const { cpus, mem } = e.data.payload;
  document.getElementById('cpu').textContent =
    'CPU: ' + cpus.overall.toFixed(1) + '%';
  document.getElementById('mem').textContent =
    'MEM: ' + (mem.used / 1024 / 1024 / 1024).toFixed(1) + ' GB';
});
</script>

// Call inside activate(ctx):

// Inject a menu item into the Terminal right-click context menu
ctx.ui.registerTerminalContextMenu(
  'my-action',       // Unique ID within your plugin
  'Translate Selection', // Text displayed to the user
  (context) => {
    console.log('Session ID:', context.sessionId);
    console.log('User Selected Text:', context.selectionText);
  }
);

// Inject a menu item into the SFTP file list right-click context menu
ctx.ui.registerSFTPContextMenu(
  'preview-file',
  'Preview File',
  (context) => {
    console.log('Current Directory:', context.currentPath);
    console.log('Right-clicked Files:', context.selectedFiles); // string[]
  }
);

hello-world/
├── package.json
└── index.html

{
  "name": "hello-world-plugin",
  "version": "1.0.0",
  "displayName": "Hello World",
  "description": "A minimalist GETSSH Sandbox Plugin example.",
  "author": "Your Name",
  "main": "index.html",
  "getssh": {
    "pluginId": "com.example.hello-world",
    "type": "sandbox"
  }
}

<!DOCTYPE html>
<html>
<head><meta charset="UTF-8"></head>
<body>
<script>
// After the sandbox boots, window.GETSSH and window.__sidebarHandlers are automatically injected by GETSSH

const actionId = 'hello-btn';

// 1. Register the button click handler
window.__sidebarHandlers[actionId] = () => {
  window.GETSSH.showNotification('Hello!', 'Greetings from the sandbox plugin.');
};

// 2. Register the button in the sidebar (SVG icons are automatically sanitized)
window.GETSSH.registerSidebarAction(
  actionId,
  `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24">
    <circle cx="12" cy="12" r="10" fill="currentColor"/>
  </svg>`,
  'Say Hello'
);
</script>
</body>
</html>

ssh-auditor/
├── package.json
└── main.js

{
  "name": "ssh-auditor",
  "version": "1.0.0",
  "displayName": "SSH Audit Logger",
  "description": "Logs all SSH connection events to a local log file.",
  "author": "Your Name",
  "main": "main.js",
  "getssh": {
    "pluginId": "com.example.ssh-auditor",
    "capabilities": ["lifecycle"]
  }
}

// NOTE: Under Strict Mode (strict), the `fs` module is unavailable.
// This example requires the user to set the security mode to "Normal" or "Developer" to run.
const fs = require('fs');
const os = require('os');
const path = require('path');

const logPath = path.join(os.tmpdir(), 'getssh-audit.log');
let fileStream = null;

module.exports = {
  activate(ctx) {
    fileStream = fs.createWriteStream(logPath, { flags: 'a' });
    fileStream.write(`[${new Date().toISOString()}] SSH Audit Plugin Started\n`);

    ctx.onSSHSessionConnect?.((sessionId, host) => {
      const line = `[${new Date().toISOString()}] Connected to: ${host} (session: ${sessionId})\n`;
      fileStream?.write(line);
    });

    // ⛔ THIS HOOK IS MANDATORY: Declare the configuration parameters for this plugin
    ctx.ui.registerSettings([
      { id: 'logLevel', type: 'string', label: 'Log Level', default: 'info' }
    ]);

    ctx.showNotification('SSH Auditor', `Audit logs are now being recorded to ${logPath}`);
  },

  // ⛔ THIS HOOK IS MANDATORY; the plugin will fail to install without it
  deactivate() {
    if (fileStream) {
      fileStream.write(`[${new Date().toISOString()}] SSH Audit Plugin Stopped\n`);
      fileStream.end();    // ✅ MANDATORY: Close the file stream
      fileStream = null;
    }
  }
};

# Format A (Recommended): Directly at the root
my-plugin.zip
├── package.json
├── main.js
└── index.html

# Format B (Supported): Wrapped in a subdirectory
my-plugin.zip
└── my-plugin/
    ├── package.json
    ├── main.js
    └── index.html