nodebb-plugin-safe-updater 0.0.0-stage → 1.1.0

package/README.md

@@ -1,3 +1,96 @@
-# Temporary Holding Version
+# NodeBB Safe Updater
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A conservative utility that keeps a NodeBB forum up to date safely.
+
+This repository now includes both:
+- a CLI update tool
+- a NodeBB plugin-style integration that exposes a one-click update action from the admin area
+
+## Features
+- Validates that the target directory is a Git repository
+- Refuses to run on a dirty working tree unless explicitly allowed
+- Creates a backup before updating
+- Fetches and fast-forwards the selected branch
+- Runs `npm install`, `yarn install`, or `pnpm install` when a project uses dependencies
+- Exposes an admin route and an API endpoint suitable for a NodeBB plugin integration
+
+## Install as a NodeBB plugin
+
+1. Copy the repository contents into your NodeBB plugin directory, for example:
+
+```bash
+plugins/nodebb-safe-updater/
+```
+
+2. Make sure the NodeBB server has environment variables configured, for example:
+
+```bash
+export NODEBB_DIRECTORY=/srv/nodebb
+export NODEBB_BRANCH=main
+export NODEBB_REMOTE=origin
+export NODEBB_ALLOW_DIRTY=false
+export NODEBB_SKIP_INSTALL=false
+```
+
+3. Restart NodeBB.
+
+4. Open the admin area and use the new "NodeBB Safe Updater" item.
+
+5. Trigger the update from the browser by clicking the button in the plugin page.
+
+## Browser update flow
+
+The plugin registers:
+- `/admin/plugins/nodebb-safe-updater` as the admin page
+- `/api/v3/plugins/nodebb-safe-updater/update` as the POST endpoint used by the button
+
+The page executes a safe update using the configured repo directory and then prints the JSON result.
+
+## CLI usage
+
+Update the current directory:
+
+```bash
+node src/index.js
+```
+
+Update a specific installation:
+
+```bash
+node src/index.js --directory /srv/nodebb --branch main --remote origin
+```
+
+Allow dirty working trees:
+
+```bash
+node src/index.js --directory /srv/nodebb --allow-dirty
+```
+
+Skip post-update install:
+
+```bash
+node src/index.js --directory /srv/nodebb --skip-install
+```
+
+## Safety checks
+
+This updater intentionally prefers a cautious workflow:
+- it aborts if the repo is dirty,
+- it creates a backup before the change,
+- it uses a fast-forward pull strategy,
+- and it keeps the update process explicit and inspectable.
+
+## Example response
+
+```json
+{
+  "ok": true,
+  "result": {
+    "directory": "/srv/nodebb",
+    "branch": "main",
+    "remote": "origin",
+    "backupDir": "/tmp/nodebb-safe-updater/nodebb-backup-2026-10-24T12-00-00.000Z",
+    "statusAfter": ""
+  }
+}
+```

package/package.json

@@ -1,6 +1,38 @@
 {
   "name": "nodebb-plugin-safe-updater",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.1.0",
+  "description": "Safe NodeBB updater plugin with a one-click update endpoint and CLI fallback.",
+  "license": "MIT",
+  "homepage": "https://github.com/amer-raba/nodebb-plugin-safe-updater",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/amer-raba/nodebb-plugin-safe-updater.git"
+  },
+  "bugs": {
+    "url": "https://github.com/amer-raba/nodebb-plugin-safe-updater/issues"
+  },
+  "keywords": [
+    "nodebb",
+    "plugin",
+    "updater",
+    "admin",
+    "safe-update"
+  ],
+  "main": "src/nodebbPlugin.js",
+  "bin": {
+    "nodebb-safe-updater": "src/index.js"
+  },
+  "files": [
+    "src",
+    "plugin.json",
+    "README.md"
+  ],
+  "scripts": {
+    "start": "node src/webUpdater.js",
+    "update": "node src/index.js",
+    "test": "node --test"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}

package/plugin.json

@@ -0,0 +1,19 @@
+{
+  "id": "nodebb-safe-updater",
+  "name": "NodeBB Safe Updater",
+  "description": "Adds a safe one-click update flow for a NodeBB installation.",
+  "library": "./src/nodebbPlugin.js",
+  "hooks": [
+    {
+      "hook": "static:app.load",
+      "method": "init"
+    },
+    {
+      "hook": "filter:admin.header.build",
+      "method": "addAdminNavigation"
+    }
+  ],
+  "staticDirs": {
+    "public": "public"
+  }
+}

package/src/index.js

@@ -0,0 +1,22 @@
+#!/usr/bin/env node
+
+const { safeUpdate, parseArgs } = require('./safeUpdater');
+
+function main() {
+  try {
+    const options = parseArgs(process.argv.slice(2));
+
+    if (options.help) {
+      console.log('Usage: nodebb-safe-updater [--directory /path/to/nodebb] [--branch main] [--remote origin] [--allow-dirty] [--skip-install]');
+      process.exit(0);
+    }
+
+    const result = safeUpdate(options);
+    console.log(JSON.stringify(result, null, 2));
+  } catch (error) {
+    console.error(error.message || error);
+    process.exit(1);
+  }
+}
+
+main();

package/src/nodebbPlugin.js

@@ -0,0 +1,51 @@
+'use strict';
+
+const { safeUpdate } = require('./safeUpdater');
+
+const plugin = {
+  async init(params) {
+    const { router, middleware } = params;
+
+    const adminRoute = '/admin/plugins/nodebb-safe-updater';
+    const apiRoute = '/api/v3/plugins/nodebb-safe-updater/update';
+
+    router.get(adminRoute, middleware.admin.build, async (req, res) => {
+      const context = {
+        title: 'NodeBB Safe Updater',
+        directory: process.env.NODEBB_DIRECTORY || process.cwd(),
+        branch: process.env.NODEBB_BRANCH || 'main',
+        remote: process.env.NODEBB_REMOTE || 'origin'
+      };
+
+      res.render('admin/plugins/nodebb-safe-updater', context);
+    });
+
+    router.post(apiRoute, middleware.ensureLoggedIn, async (req, res) => {
+      try {
+        const result = safeUpdate({
+          directory: process.env.NODEBB_DIRECTORY || process.cwd(),
+          branch: process.env.NODEBB_BRANCH || 'main',
+          remote: process.env.NODEBB_REMOTE || 'origin',
+          allowDirty: Boolean(process.env.NODEBB_ALLOW_DIRTY === 'true'),
+          skipInstall: Boolean(process.env.NODEBB_SKIP_INSTALL === 'true')
+        });
+
+        res.json({ ok: true, result });
+      } catch (error) {
+        res.status(500).json({ ok: false, error: error.message || String(error) });
+      }
+    });
+  },
+
+  addAdminNavigation(header, callback) {
+    header.plugins.push({
+      route: '/admin/plugins/nodebb-safe-updater',
+      icon: 'fa-rocket',
+      name: 'NodeBB Safe Updater'
+    });
+
+    callback(null, header);
+  }
+};
+
+module.exports = plugin;

package/src/safeUpdater.js

@@ -0,0 +1,200 @@
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+function runCommand(command, args, options = {}) {
+  const result = spawnSync(command, args, {
+    cwd: options.cwd || process.cwd(),
+    encoding: 'utf8',
+    stdio: ['inherit', 'pipe', 'pipe']
+  });
+
+  if (result.error) {
+    throw new Error(`${command} ${args.join(' ')} failed: ${result.error.message}`);
+  }
+
+  if (result.status !== 0) {
+    const output = [result.stdout, result.stderr].filter(Boolean).join('\n').trim();
+    throw new Error(`${command} ${args.join(' ')} failed with exit code ${result.status}. ${output}`);
+  }
+
+  return (result.stdout || '').trim();
+}
+
+function ensureGitRepository(directory) {
+  const gitDir = path.join(directory, '.git');
+  if (!fs.existsSync(directory)) {
+    throw new Error(`Directory does not exist: ${directory}`);
+  }
+
+  if (!fs.existsSync(gitDir)) {
+    throw new Error(`Not a git repository: ${directory}`);
+  }
+}
+
+function getGitStatus(directory) {
+  return runCommand('git', ['-C', directory, 'status', '--porcelain']);
+}
+
+function createBackup(directory, backupRoot) {
+  const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
+  const backupDir = path.join(backupRoot, `nodebb-backup-${timestamp}`);
+
+  fs.mkdirSync(backupDir, { recursive: true });
+
+  const entries = fs.readdirSync(directory);
+  for (const entry of entries) {
+    if (['.git', 'node_modules', '.cache', 'tmp'].includes(entry)) {
+      continue;
+    }
+
+    const sourcePath = path.join(directory, entry);
+    const targetPath = path.join(backupDir, entry);
+
+    if (fs.existsSync(sourcePath)) {
+      fs.cpSync(sourcePath, targetPath, { recursive: true, force: true });
+    }
+  }
+
+  return backupDir;
+}
+
+function detectPackageManager(directory) {
+  if (fs.existsSync(path.join(directory, 'pnpm-lock.yaml'))) {
+    return 'pnpm';
+  }
+
+  if (fs.existsSync(path.join(directory, 'yarn.lock'))) {
+    return 'yarn';
+  }
+
+  return 'npm';
+}
+
+function parseArgs(argv = []) {
+  const options = {
+    directory: process.cwd(),
+    branch: 'main',
+    remote: 'origin',
+    allowDirty: false,
+    skipInstall: false,
+    backupRoot: path.join(os.tmpdir(), 'nodebb-safe-updater')
+  };
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+
+    if (arg === '--directory' || arg === '-d') {
+      options.directory = argv[index + 1];
+      index += 1;
+      continue;
+    }
+
+    if (arg === '--branch' || arg === '-b') {
+      options.branch = argv[index + 1];
+      index += 1;
+      continue;
+    }
+
+    if (arg === '--remote' || arg === '-r') {
+      options.remote = argv[index + 1];
+      index += 1;
+      continue;
+    }
+
+    if (arg === '--backup-root') {
+      options.backupRoot = argv[index + 1];
+      index += 1;
+      continue;
+    }
+
+    if (arg === '--allow-dirty') {
+      options.allowDirty = true;
+      continue;
+    }
+
+    if (arg === '--skip-install') {
+      options.skipInstall = true;
+      continue;
+    }
+
+    if (arg === '--help' || arg === '-h') {
+      options.help = true;
+      continue;
+    }
+
+    if (arg.startsWith('-')) {
+      throw new Error(`Unknown option: ${arg}`);
+    }
+
+    if (!options.directory || options.directory === process.cwd()) {
+      options.directory = arg;
+    }
+  }
+
+  if (options.directory && options.directory !== process.cwd() && !path.isAbsolute(options.directory)) {
+    options.directory = path.resolve(options.directory);
+  }
+
+  return options;
+}
+
+function safeUpdate(options = {}) {
+  const finalOptions = {
+    directory: options.directory || process.cwd(),
+    branch: options.branch || 'main',
+    remote: options.remote || 'origin',
+    allowDirty: Boolean(options.allowDirty),
+    skipInstall: Boolean(options.skipInstall),
+    backupRoot: options.backupRoot || path.join(os.tmpdir(), 'nodebb-safe-updater')
+  };
+
+  ensureGitRepository(finalOptions.directory);
+
+  const statusBefore = getGitStatus(finalOptions.directory);
+  if (statusBefore && !finalOptions.allowDirty) {
+    throw new Error(`Working tree is not clean. Commit or stash your changes before updating, or use --allow-dirty.\n${statusBefore}`);
+  }
+
+  fs.mkdirSync(finalOptions.backupRoot, { recursive: true });
+  const backupDir = createBackup(finalOptions.directory, finalOptions.backupRoot);
+
+  runCommand('git', ['-C', finalOptions.directory, 'fetch', finalOptions.remote, finalOptions.branch]);
+  runCommand('git', ['-C', finalOptions.directory, 'checkout', finalOptions.branch]);
+  runCommand('git', ['-C', finalOptions.directory, 'pull', '--ff-only', finalOptions.remote, finalOptions.branch]);
+
+  if (!finalOptions.skipInstall && fs.existsSync(path.join(finalOptions.directory, 'package.json'))) {
+    const packageManager = detectPackageManager(finalOptions.directory);
+    const installCommand =
+      packageManager === 'pnpm'
+        ? ['pnpm', 'install']
+        : packageManager === 'yarn'
+          ? ['yarn', 'install']
+          : ['npm', 'install'];
+
+    runCommand(installCommand[0], installCommand.slice(1), { cwd: finalOptions.directory });
+  }
+
+  const statusAfter = getGitStatus(finalOptions.directory);
+
+  return {
+    ok: true,
+    directory: finalOptions.directory,
+    branch: finalOptions.branch,
+    remote: finalOptions.remote,
+    backupDir,
+    statusBefore,
+    statusAfter,
+    packageManager: fs.existsSync(path.join(finalOptions.directory, 'package.json')) ? detectPackageManager(finalOptions.directory) : null
+  };
+}
+
+module.exports = {
+  parseArgs,
+  safeUpdate,
+  createBackup,
+  ensureGitRepository,
+  getGitStatus,
+  runCommand
+};

package/src/webUpdater.js

@@ -0,0 +1,162 @@
+const { safeUpdate, parseArgs } = require('./safeUpdater');
+const http = require('node:http');
+const fs = require('node:fs');
+const path = require('node:path');
+
+const HTML_PAGE = `<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>NodeBB Safe Updater</title>
+    <style>
+      body {
+        font-family: system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif;
+        background: #0f172a;
+        color: #e2e8f0;
+        display: grid;
+        place-items: center;
+        min-height: 100vh;
+        margin: 0;
+      }
+
+      .panel {
+        width: min(520px, 90vw);
+        background: rgba(15, 23, 42, 0.8);
+        border: 1px solid rgba(148, 163, 184, 0.25);
+        border-radius: 14px;
+        padding: 28px;
+        box-shadow: 0 20px 45px rgba(15, 23, 42, 0.5);
+      }
+
+      h1 {
+        margin-top: 0;
+        font-size: 1.8rem;
+      }
+
+      button {
+        background: #22c55e;
+        color: #052e16;
+        border: none;
+        border-radius: 10px;
+        padding: 14px 22px;
+        font-size: 1rem;
+        font-weight: 700;
+        cursor: pointer;
+        transition: transform 0.15s ease;
+      }
+
+      button:hover {
+        transform: translateY(-1px);
+      }
+
+      button:disabled {
+        opacity: 0.6;
+        cursor: wait;
+      }
+
+      #result {
+        margin-top: 20px;
+        min-height: 80px;
+        background: rgba(15, 118, 110, 0.1);
+        border: 1px solid rgba(45, 212, 191, 0.2);
+        border-radius: 10px;
+        padding: 12px 14px;
+        white-space: pre-wrap;
+        word-break: break-word;
+      }
+    </style>
+  </head>
+  <body>
+    <div class="panel">
+      <h1>NodeBB Safe Updater</h1>
+      <p>Click the button below to update the forum to the latest version safely.</p>
+      <button id="updateButton">Update to latest version</button>
+      <div id="result">Waiting for action...</div>
+    </div>
+
+    <script>
+      const button = document.getElementById('updateButton');
+      const result = document.getElementById('result');
+
+      button.addEventListener('click', async () => {
+        button.disabled = true;
+        result.textContent = 'Updating...';
+
+        try {
+          const response = await fetch('/api/update', { method: 'POST' });
+          const data = await response.json();
+
+          if (!response.ok) {
+            throw new Error(data.error || 'Update failed');
+          }
+
+          result.textContent = JSON.stringify(data, null, 2);
+        } catch (error) {
+          result.textContent = 'ERROR: ' + (error.message || String(error));
+        } finally {
+          button.disabled = false;
+        }
+      });
+    </script>
+  </body>
+</html>`;
+
+function parseOptionsFromEnv() {
+  return {
+    directory: process.env.NODEBB_DIRECTORY || process.cwd(),
+    branch: process.env.NODEBB_BRANCH || 'main',
+    remote: process.env.NODEBB_REMOTE || 'origin',
+    allowDirty: (process.env.NODEBB_ALLOW_DIRTY || '').toLowerCase() === 'true',
+    skipInstall: (process.env.NODEBB_SKIP_INSTALL || '').toLowerCase() === 'true',
+    port: Number(process.env.NODEBB_UPDATER_PORT || 3000),
+    backupRoot: process.env.NODEBB_BACKUP_ROOT || path.join(process.cwd(), '.nodebb-safe-updater-backups')
+  };
+}
+
+function createServer(options) {
+  const server = http.createServer(async (req, res) => {
+    if (req.method === 'GET' && req.url === '/') {
+      res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8' });
+      res.end(HTML_PAGE);
+      return;
+    }
+
+    if (req.method === 'POST' && req.url === '/api/update') {
+      try {
+        const result = safeUpdate(options);
+        res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+        res.end(JSON.stringify({ ok: true, result }, null, 2));
+      } catch (error) {
+        res.writeHead(500, { 'Content-Type': 'application/json; charset=utf-8' });
+        res.end(JSON.stringify({ ok: false, error: error.message || String(error) }, null, 2));
+      }
+      return;
+    }
+
+    res.writeHead(404, { 'Content-Type': 'application/json; charset=utf-8' });
+    res.end(JSON.stringify({ ok: false, error: 'Not found' }, null, 2));
+  });
+
+  return server;
+}
+
+function main() {
+  const options = parseOptionsFromEnv();
+  const server = createServer(options);
+
+  server.listen(options.port, () => {
+    console.log(JSON.stringify({
+      status: 'ready',
+      port: options.port,
+      directory: options.directory,
+      endpoint: `http://localhost:${options.port}/`
+    }, null, 2));
+  });
+}
+
+if (require.main === module) {
+  main();
+}
+
+module.exports = { parseOptionsFromEnv, createServer, main };