adapt-authoring-contentplugin 1.2.3 → 1.3.0

package/lib/ContentPluginModule.js

@@ -3,6 +3,14 @@ import apidefs from './apidefs.js'
 import fs from 'fs/promises'
 import { glob } from 'glob'
 import path from 'path'
+import { readJson } from 'adapt-authoring-core'
+import {
+  backupPluginVersion,
+  getMostRecentBackup,
+  cleanupOldPluginBackups,
+  restorePluginFromBackup,
+  processPluginFiles
+} from './utils.js'
 import semver from 'semver'
 /**
  * Abstract module which handles framework plugins
@@ -107,7 +115,7 @@ class ContentPluginModule extends AbstractApiModule {
   }
 
   async readJson (filepath) {
-    return JSON.parse(await fs.readFile(filepath))
+    return readJson(filepath)
   }
 
   /**
@@ -360,30 +368,7 @@ class ContentPluginModule extends AbstractApiModule {
    * @returns {Promise<String|null>} Path to the backup directory, or null if no backup was created
    */
   async backupPluginVersion (pluginPath, pluginName) {
-    try {
-      await fs.access(pluginPath)
-    } catch (e) { // No plugin, no backup needed
-      return null
-    }
-    let existingVersion
-    try {
-      const pkgPath = path.join(pluginPath, 'package.json')
-      const pkg = await this.readJson(pkgPath)
-      existingVersion = pkg.version
-    } catch (e) {
-      try {
-        const bowerPath = path.join(pluginPath, 'bower.json')
-        const bower = await this.readJson(bowerPath)
-        existingVersion = bower.version
-      } catch (e2) {
-        this.log('warn', `Could not read version for backup of ${pluginName}`)
-        existingVersion = `unknown-${Date.now()}`
-      }
-    }
-    const backupDir = `${pluginPath}-v${existingVersion}`
-    await fs.rename(pluginPath, backupDir)
-    this.log('info', `Backed up ${pluginName}@${existingVersion}`)
-    return backupDir
+    return backupPluginVersion(pluginPath, pluginName, this.log.bind(this))
   }
 
   /**
@@ -393,54 +378,11 @@ class ContentPluginModule extends AbstractApiModule {
    * @returns {Promise<String|null>} Path to the most recent backup, or null if none found
    */
   async getMostRecentBackup (pluginDir, pluginName) {
-    const pattern = `${pluginName}-v*`
-    const backups = await glob(pattern, { cwd: pluginDir, absolute: true })
-
-    if (backups.length === 0) {
-      return null
-    }
-
-    // Sort by version (newest first)
-    // Extract version from backup path (format: pluginName-vX.Y.Z)
-    backups.sort((a, b) => {
-      const versionA = path.basename(a).replace(`${pluginName}-v`, '')
-      const versionB = path.basename(b).replace(`${pluginName}-v`, '')
-
-      // Try to compare as semver versions
-      if (semver.valid(versionA) && semver.valid(versionB)) {
-        return semver.rcompare(versionA, versionB) // descending order
-      }
-
-      // Fall back to alphabetical comparison for non-semver versions (e.g., unknown-timestamp)
-      return b.localeCompare(a)
-    })
-
-    return backups[0]
+    return getMostRecentBackup(pluginDir, pluginName)
   }
 
-  /**
-   * Cleans up old plugin version backups, keeping only the most recent one
-   * @param {String} pluginDir Base directory containing plugins
-   * @param {String} pluginName Name of the plugin
-   * @returns {Promise<void>}
-   */
   async cleanupOldPluginBackups (pluginDir, pluginName) {
-    const pattern = `${pluginName}-v*`
-    const backups = await glob(pattern, { cwd: pluginDir, absolute: true })
-
-    if (backups.length <= 1) {
-      return
-    }
-
-    // Get the most recent backup using the helper
-    const mostRecent = await this.getMostRecentBackup(pluginDir, pluginName)
-
-    // Remove all backups except the most recent
-    const backupsToRemove = backups.filter(backup => backup !== mostRecent)
-    for (const backup of backupsToRemove) {
-      await fs.rm(backup, { recursive: true })
-      this.log('info', `Removed old backup: ${backup}`)
-    }
+    return cleanupOldPluginBackups(pluginDir, pluginName, this.log.bind(this))
   }
 
   /**
@@ -450,77 +392,23 @@ class ContentPluginModule extends AbstractApiModule {
    */
   async restorePluginFromBackup (pluginName) {
     const pluginDir = this.getConfig('pluginDir')
-    const pluginPath = path.join(pluginDir, pluginName)
-    const mostRecentBackup = await this.getMostRecentBackup(pluginDir, pluginName)
-
-    if (!mostRecentBackup) {
+    const result = await restorePluginFromBackup(pluginDir, pluginName, this.log.bind(this))
+    if (!result) {
       throw this.app.errors.NOT_FOUND
         .setData({ type: 'backup', id: pluginName })
     }
-    // Remove current version if it exists
-    try {
-      await fs.access(pluginPath)
-      await fs.rm(pluginPath, { recursive: true })
-    } catch (e) {
-      // Current version doesn't exist, that's fine
-    }
-    // Restore the backup
-    await fs.rename(mostRecentBackup, pluginPath)
-    this.log('info', `Restored ${pluginName} from backup`)
-    let pkg
-    try {
-      pkg = await this.readJson(path.join(pluginPath, 'package.json'))
-    } catch (e) {
-      try {
-        pkg = await this.readJson(path.join(pluginPath, 'bower.json'))
-      } catch (e2) {
-        throw this.app.errors.CONTENTPLUGIN_INVALID_ZIP
-          .setData({ pluginName, message: 'Could not read package.json or bower.json from backup' })
-      }
-    }
-    return pkg
+    return result
   }
 
-  /**
-   * Ensures local plugin source files are stored in the correct location and structured in an expected way
-   * @param {Object} pluginData Plugin metadata
-   * @param {String} sourcePath The path to the plugin source files
-   * @returns Resolves with package data
-   */
   async processPluginFiles (pluginData) {
-    let sourcePath = pluginData.sourcePath
-    if (sourcePath === path.basename(sourcePath)) { // no local files
-      return { name: pluginData.name, version: sourcePath, isLocalInstall: false }
-    }
-    const contents = await fs.readdir(sourcePath)
-    if (contents.length === 1) { // deal with a nested root folder
-      sourcePath = path.join(pluginData.sourcePath, contents[0])
-    }
-    let pkg
-    try { // load package data, with fall-back to bower
-      try {
-        pkg = await this.readJson(path.join(sourcePath, 'package.json'))
-      } catch (e) {
-        pkg = await this.readJson(path.join(sourcePath, 'bower.json'))
-      }
-      pkg.sourcePath = path.join(this.getConfig('pluginDir'), pkg.name)
-      pkg.isLocalInstall = true
+    try {
+      return await processPluginFiles(pluginData, this.getConfig('pluginDir'), this.log.bind(this))
     } catch (e) {
-      throw this.app.errors.CONTENTPLUGIN_INVALID_ZIP
+      if (e.message?.startsWith('Invalid plugin zip')) {
+        throw this.app.errors.CONTENTPLUGIN_INVALID_ZIP
+      }
+      throw e
     }
-
-    const pluginDir = this.getConfig('pluginDir')
-
-    // Back up the existing version if it exists
-    await this.backupPluginVersion(pkg.sourcePath, pkg.name)
-
-    // Clean up old backups (keep only 1 previous version)
-    await this.cleanupOldPluginBackups(pluginDir, pkg.name)
-
-    // move the files into the persistent location
-    await fs.cp(sourcePath, pkg.sourcePath, { recursive: true })
-    await fs.rm(sourcePath, { recursive: true })
-    return pkg
   }
 
   /**

package/lib/utils/backupPluginVersion.js

@@ -0,0 +1,43 @@
+import fs from 'fs/promises'
+import path from 'path'
+import { readJson } from 'adapt-authoring-core'
+
+/**
+ * Creates a versioned backup of an existing plugin directory.
+ *
+ * Reads the plugin version from package.json (or bower.json as fallback),
+ * removes any stale backup at the target path, then renames the plugin
+ * directory to `<pluginPath>-v<version>`.
+ *
+ * @param {string} pluginPath - Absolute path to the plugin directory
+ * @param {string} pluginName - Human-readable plugin name (for logging)
+ * @param {Function} [log] - Optional logging callback `(level, msg) => void`
+ * @returns {Promise<string|null>} Path to the backup directory, or null if no backup was needed
+ */
+export async function backupPluginVersion (pluginPath, pluginName, log) {
+  try {
+    await fs.access(pluginPath)
+  } catch (e) { // No plugin, no backup needed
+    return null
+  }
+  let existingVersion
+  try {
+    const pkg = await readJson(path.join(pluginPath, 'package.json'))
+    existingVersion = pkg.version
+  } catch (e) {
+    try {
+      const bower = await readJson(path.join(pluginPath, 'bower.json'))
+      existingVersion = bower.version
+    } catch (e2) {
+      if (log) log('warn', `Could not read version for backup of ${pluginName}`)
+      existingVersion = `unknown-${Date.now()}`
+    }
+  }
+  const backupDir = `${pluginPath}-v${existingVersion}`
+  try {
+    await fs.rm(backupDir, { recursive: true, force: true })
+  } catch (e) {} // ignore if doesn't exist
+  await fs.rename(pluginPath, backupDir)
+  if (log) log('info', `Backed up ${pluginName}@${existingVersion}`)
+  return backupDir
+}

package/lib/utils/cleanupOldPluginBackups.js

@@ -0,0 +1,28 @@
+import fs from 'fs/promises'
+import { glob } from 'glob'
+import { getMostRecentBackup } from './getMostRecentBackup.js'
+
+/**
+ * Cleans up old plugin version backups, keeping only the most recent one.
+ *
+ * @param {string} pluginDir - Base directory containing plugins
+ * @param {string} pluginName - Name of the plugin
+ * @param {Function} [log] - Optional logging callback `(level, msg) => void`
+ * @returns {Promise<void>}
+ */
+export async function cleanupOldPluginBackups (pluginDir, pluginName, log) {
+  const pattern = `${pluginName}-v*`
+  const backups = await glob(pattern, { cwd: pluginDir, absolute: true })
+
+  if (backups.length <= 1) {
+    return
+  }
+
+  const mostRecent = await getMostRecentBackup(pluginDir, pluginName)
+
+  const backupsToRemove = backups.filter(backup => backup !== mostRecent)
+  for (const backup of backupsToRemove) {
+    await fs.rm(backup, { recursive: true })
+    if (log) log('info', `Removed old backup: ${backup}`)
+  }
+}

package/lib/utils/getMostRecentBackup.js

@@ -0,0 +1,37 @@
+import { glob } from 'glob'
+import path from 'path'
+import semver from 'semver'
+
+/**
+ * Gets the most recent backup for a plugin based on version sorting.
+ *
+ * Scans for directories matching `<pluginName>-v*` in the given directory,
+ * sorts by semver (falling back to alphabetical for non-semver), and
+ * returns the most recent.
+ *
+ * @param {string} pluginDir - Base directory containing plugins
+ * @param {string} pluginName - Name of the plugin
+ * @returns {Promise<string|null>} Absolute path to the most recent backup, or null if none found
+ */
+export async function getMostRecentBackup (pluginDir, pluginName) {
+  const pattern = `${pluginName}-v*`
+  const backups = await glob(pattern, { cwd: pluginDir, absolute: true })
+
+  if (backups.length === 0) {
+    return null
+  }
+
+  // Sort by version (newest first)
+  backups.sort((a, b) => {
+    const versionA = path.basename(a).replace(`${pluginName}-v`, '')
+    const versionB = path.basename(b).replace(`${pluginName}-v`, '')
+
+    if (semver.valid(versionA) && semver.valid(versionB)) {
+      return semver.rcompare(versionA, versionB)
+    }
+
+    return b.localeCompare(a)
+  })
+
+  return backups[0]
+}

package/lib/utils/processPluginFiles.js

@@ -0,0 +1,53 @@
+import fs from 'fs/promises'
+import path from 'path'
+import { readJson } from 'adapt-authoring-core'
+import { backupPluginVersion } from './backupPluginVersion.js'
+import { cleanupOldPluginBackups } from './cleanupOldPluginBackups.js'
+
+/**
+ * Processes local plugin source files for installation.
+ *
+ * If `sourcePath` is just a filename (no directory component), returns a
+ * non-local install descriptor.  Otherwise reads the package metadata from
+ * the source, backs up any existing version, cleans old backups, and copies
+ * the source files into their persistent location under `pluginDir`.
+ *
+ * @param {Object} pluginData - Plugin metadata (must include `name` and `sourcePath`)
+ * @param {string} pluginDir - Persistent plugin storage directory
+ * @param {Function} [log] - Optional logging callback `(level, msg) => void`
+ * @returns {Promise<Object>} Package metadata with `sourcePath` and `isLocalInstall` fields
+ * @throws {Error} If the source contains no valid package.json or bower.json
+ */
+export async function processPluginFiles (pluginData, pluginDir, log) {
+  let sourcePath = pluginData.sourcePath
+  if (sourcePath === path.basename(sourcePath)) { // no local files
+    return { name: pluginData.name, version: sourcePath, isLocalInstall: false }
+  }
+  const contents = await fs.readdir(sourcePath)
+  if (contents.length === 1) { // deal with a nested root folder
+    sourcePath = path.join(pluginData.sourcePath, contents[0])
+  }
+  let pkg
+  try {
+    try {
+      pkg = await readJson(path.join(sourcePath, 'package.json'))
+    } catch (e) {
+      pkg = await readJson(path.join(sourcePath, 'bower.json'))
+    }
+    pkg.sourcePath = path.join(pluginDir, pkg.name)
+    pkg.isLocalInstall = true
+  } catch (e) {
+    throw new Error(`Invalid plugin zip: no package.json or bower.json found in ${sourcePath}`)
+  }
+
+  // Back up the existing version if it exists
+  await backupPluginVersion(pkg.sourcePath, pkg.name, log)
+
+  // Clean up old backups (keep only 1 previous version)
+  await cleanupOldPluginBackups(pluginDir, pkg.name, log)
+
+  // move the files into the persistent location
+  await fs.cp(sourcePath, pkg.sourcePath, { recursive: true })
+  await fs.rm(sourcePath, { recursive: true })
+  return pkg
+}

package/lib/utils/restorePluginFromBackup.js

@@ -0,0 +1,45 @@
+import fs from 'fs/promises'
+import path from 'path'
+import { getMostRecentBackup } from './getMostRecentBackup.js'
+import { readJson } from 'adapt-authoring-core'
+
+/**
+ * Restores a plugin from its most recent versioned backup.
+ *
+ * Finds the newest backup directory, removes the current plugin directory
+ * (if present), renames the backup into place, and reads the package metadata.
+ *
+ * @param {string} pluginDir - Base directory containing plugins
+ * @param {string} pluginName - Name of the plugin to restore
+ * @param {Function} [log] - Optional logging callback `(level, msg) => void`
+ * @returns {Promise<Object|null>} Package metadata from the restored backup,
+ *   or null if no backup was found
+ * @throws {Error} If the restored backup contains no package.json or bower.json
+ */
+export async function restorePluginFromBackup (pluginDir, pluginName, log) {
+  const pluginPath = path.join(pluginDir, pluginName)
+  const mostRecentBackup = await getMostRecentBackup(pluginDir, pluginName)
+
+  if (!mostRecentBackup) {
+    return null
+  }
+  // Remove current version if it exists
+  try {
+    await fs.access(pluginPath)
+    await fs.rm(pluginPath, { recursive: true })
+  } catch (e) {
+    // Current version doesn't exist, that's fine
+  }
+  // Restore the backup
+  await fs.rename(mostRecentBackup, pluginPath)
+  if (log) log('info', `Restored ${pluginName} from backup`)
+  try {
+    return await readJson(path.join(pluginPath, 'package.json'))
+  } catch (e) {
+    try {
+      return await readJson(path.join(pluginPath, 'bower.json'))
+    } catch (e2) {
+      throw new Error(`Could not read package.json or bower.json from backup of ${pluginName}`)
+    }
+  }
+}

package/lib/utils.js

@@ -0,0 +1,5 @@
+export { backupPluginVersion } from './utils/backupPluginVersion.js'
+export { getMostRecentBackup } from './utils/getMostRecentBackup.js'
+export { cleanupOldPluginBackups } from './utils/cleanupOldPluginBackups.js'
+export { restorePluginFromBackup } from './utils/restorePluginFromBackup.js'
+export { processPluginFiles } from './utils/processPluginFiles.js'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "adapt-authoring-contentplugin",
-  "version": "1.2.3",
+  "version": "1.3.0",
   "description": "Module for managing framework plugins",
   "homepage": "https://github.com/adapt-security/adapt-authoring-contentplugin",
   "repository": "github:adapt-security/adapt-authoring-contentplugin",
@@ -10,17 +10,17 @@
   "main": "index.js",
   "type": "module",
   "dependencies": {
+    "adapt-authoring-core": "^2.0.0",
     "adapt-cli": "^3.3.3",
     "glob": "^13.0.0",
     "semver": "^7.6.0"
   },
   "peerDependencies": {
-    "adapt-authoring-adaptframework": "^1.9.3",
-    "adapt-authoring-content": "^1.2.3",
-    "adapt-authoring-core": "^1.7.0",
+    "adapt-authoring-adaptframework": "^2.0.0",
+    "adapt-authoring-content": "^2.0.0",
     "adapt-authoring-jsonschema": "^1.2.0",
     "adapt-authoring-middleware": "^1.0.2",
-    "adapt-authoring-mongodb": "^1.1.3"
+    "adapt-authoring-mongodb": "^2.0.0"
   },
   "devDependencies": {
     "@semantic-release/git": "^10.0.1",

package/tests/ContentPluginUtils.spec.js

@@ -0,0 +1,513 @@
+import { describe, it, beforeEach, afterEach, mock } from 'node:test'
+import assert from 'node:assert/strict'
+import fs from 'fs/promises'
+import path from 'path'
+import os from 'os'
+
+import { readJson } from 'adapt-authoring-core'
+import {
+  backupPluginVersion,
+  getMostRecentBackup,
+  cleanupOldPluginBackups,
+  restorePluginFromBackup,
+  processPluginFiles
+} from '../lib/utils.js'
+
+// ---------------------------------------------------------------------------
+// readJson
+// ---------------------------------------------------------------------------
+describe('readJson()', () => {
+  let tmpDir
+
+  beforeEach(async () => {
+    tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), 'cpu-test-'))
+  })
+
+  afterEach(async () => {
+    await fs.rm(tmpDir, { recursive: true, force: true })
+  })
+
+  it('should parse a valid JSON file', async () => {
+    const filePath = path.join(tmpDir, 'data.json')
+    await fs.writeFile(filePath, JSON.stringify({ name: 'test', version: '1.0.0' }))
+    const result = await readJson(filePath)
+    assert.deepEqual(result, { name: 'test', version: '1.0.0' })
+  })
+
+  it('should throw on invalid JSON', async () => {
+    const filePath = path.join(tmpDir, 'bad.json')
+    await fs.writeFile(filePath, '{ not valid }')
+    await assert.rejects(() => readJson(filePath), SyntaxError)
+  })
+
+  it('should throw ENOENT when file does not exist', async () => {
+    await assert.rejects(
+      () => readJson(path.join(tmpDir, 'nope.json')),
+      (err) => err.code === 'ENOENT'
+    )
+  })
+})
+
+// ---------------------------------------------------------------------------
+// backupPluginVersion
+// ---------------------------------------------------------------------------
+describe('backupPluginVersion()', () => {
+  let tmpDir
+  let log
+
+  beforeEach(async () => {
+    tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), 'cpu-test-'))
+    log = mock.fn()
+  })
+
+  afterEach(async () => {
+    await fs.rm(tmpDir, { recursive: true, force: true })
+  })
+
+  /**
+   * Helper: create a fake plugin directory with a package.json.
+   */
+  async function createPlugin (name, version, { useBower = false } = {}) {
+    const pluginPath = path.join(tmpDir, name)
+    await fs.mkdir(pluginPath, { recursive: true })
+    const filename = useBower ? 'bower.json' : 'package.json'
+    await fs.writeFile(
+      path.join(pluginPath, filename),
+      JSON.stringify({ name, version })
+    )
+    return pluginPath
+  }
+
+  it('should return null when the plugin directory does not exist', async () => {
+    const result = await backupPluginVersion(
+      path.join(tmpDir, 'nonexistent'),
+      'nonexistent',
+      log
+    )
+    assert.equal(result, null)
+    assert.equal(log.mock.callCount(), 0)
+  })
+
+  it('should rename the plugin directory to a versioned backup', async () => {
+    const pluginPath = await createPlugin('adapt-hotgrid', '4.3.5')
+
+    const result = await backupPluginVersion(pluginPath, 'adapt-hotgrid', log)
+
+    const expectedBackup = `${pluginPath}-v4.3.5`
+    assert.equal(result, expectedBackup)
+
+    // Original should be gone, backup should exist
+    await assert.rejects(() => fs.access(pluginPath), { code: 'ENOENT' })
+    await fs.access(expectedBackup) // should not throw
+  })
+
+  it('should read version from bower.json when package.json is absent', async () => {
+    const pluginPath = await createPlugin('adapt-vanilla', '2.1.0', { useBower: true })
+
+    const result = await backupPluginVersion(pluginPath, 'adapt-vanilla', log)
+
+    assert.equal(result, `${pluginPath}-v2.1.0`)
+  })
+
+  it('should use unknown-<timestamp> when neither package.json nor bower.json exist', async () => {
+    const pluginPath = path.join(tmpDir, 'adapt-empty')
+    await fs.mkdir(pluginPath)
+
+    const result = await backupPluginVersion(pluginPath, 'adapt-empty', log)
+
+    assert.ok(result.startsWith(`${pluginPath}-vunknown-`))
+    // Should have logged a warning
+    const warns = log.mock.calls.filter(c => c.arguments[0] === 'warn')
+    assert.equal(warns.length, 1)
+  })
+
+  it('should succeed when a backup directory already exists (bug #2 regression)', async () => {
+    const pluginPath = await createPlugin('adapt-hotgrid', '4.3.5')
+    const backupDir = `${pluginPath}-v4.3.5`
+
+    // Pre-create a stale backup with content (simulates previous test run)
+    await fs.mkdir(backupDir, { recursive: true })
+    await fs.writeFile(path.join(backupDir, 'stale-file.txt'), 'old data')
+
+    // This would fail with ENOTEMPTY before the fix
+    const result = await backupPluginVersion(pluginPath, 'adapt-hotgrid', log)
+
+    assert.equal(result, backupDir)
+    // Original should be gone
+    await assert.rejects(() => fs.access(pluginPath), { code: 'ENOENT' })
+    // Backup should exist and contain the new package.json, not the stale file
+    const pkg = JSON.parse(await fs.readFile(path.join(backupDir, 'package.json'), 'utf8'))
+    assert.equal(pkg.version, '4.3.5')
+    await assert.rejects(
+      () => fs.access(path.join(backupDir, 'stale-file.txt')),
+      { code: 'ENOENT' }
+    )
+  })
+
+  it('should log an info message on success', async () => {
+    const pluginPath = await createPlugin('adapt-text', '1.0.0')
+
+    await backupPluginVersion(pluginPath, 'adapt-text', log)
+
+    const infoCalls = log.mock.calls.filter(c => c.arguments[0] === 'info')
+    assert.equal(infoCalls.length, 1)
+    assert.ok(infoCalls[0].arguments[1].includes('adapt-text'))
+  })
+
+  it('should work without a log callback', async () => {
+    const pluginPath = await createPlugin('adapt-nolog', '1.0.0')
+
+    // Should not throw even though log is undefined
+    const result = await backupPluginVersion(pluginPath, 'adapt-nolog')
+
+    assert.equal(result, `${pluginPath}-v1.0.0`)
+  })
+})
+
+// ---------------------------------------------------------------------------
+// getMostRecentBackup
+// ---------------------------------------------------------------------------
+describe('getMostRecentBackup()', () => {
+  let tmpDir
+
+  beforeEach(async () => {
+    tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), 'cpu-test-'))
+  })
+
+  afterEach(async () => {
+    await fs.rm(tmpDir, { recursive: true, force: true })
+  })
+
+  it('should return null when no backups exist', async () => {
+    const result = await getMostRecentBackup(tmpDir, 'adapt-hotgrid')
+    assert.equal(result, null)
+  })
+
+  it('should return the only backup when there is one', async () => {
+    await fs.mkdir(path.join(tmpDir, 'adapt-hotgrid-v1.0.0'))
+
+    const result = await getMostRecentBackup(tmpDir, 'adapt-hotgrid')
+
+    assert.equal(result, path.join(tmpDir, 'adapt-hotgrid-v1.0.0'))
+  })
+
+  it('should return the highest semver version', async () => {
+    await fs.mkdir(path.join(tmpDir, 'adapt-hotgrid-v1.0.0'))
+    await fs.mkdir(path.join(tmpDir, 'adapt-hotgrid-v2.3.1'))
+    await fs.mkdir(path.join(tmpDir, 'adapt-hotgrid-v1.9.9'))
+
+    const result = await getMostRecentBackup(tmpDir, 'adapt-hotgrid')
+
+    assert.equal(result, path.join(tmpDir, 'adapt-hotgrid-v2.3.1'))
+  })
+
+  it('should handle non-semver versions with alphabetical fallback', async () => {
+    await fs.mkdir(path.join(tmpDir, 'adapt-hotgrid-vunknown-100'))
+    await fs.mkdir(path.join(tmpDir, 'adapt-hotgrid-vunknown-200'))
+
+    const result = await getMostRecentBackup(tmpDir, 'adapt-hotgrid')
+
+    assert.equal(result, path.join(tmpDir, 'adapt-hotgrid-vunknown-200'))
+  })
+
+  it('should not match backups for other plugins', async () => {
+    await fs.mkdir(path.join(tmpDir, 'adapt-text-v1.0.0'))
+
+    const result = await getMostRecentBackup(tmpDir, 'adapt-hotgrid')
+
+    assert.equal(result, null)
+  })
+})
+
+// ---------------------------------------------------------------------------
+// cleanupOldPluginBackups
+// ---------------------------------------------------------------------------
+describe('cleanupOldPluginBackups()', () => {
+  let tmpDir
+  let log
+
+  beforeEach(async () => {
+    tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), 'cpu-test-'))
+    log = mock.fn()
+  })
+
+  afterEach(async () => {
+    await fs.rm(tmpDir, { recursive: true, force: true })
+  })
+
+  it('should do nothing when no backups exist', async () => {
+    await cleanupOldPluginBackups(tmpDir, 'adapt-hotgrid', log)
+    assert.equal(log.mock.callCount(), 0)
+  })
+
+  it('should do nothing when only one backup exists', async () => {
+    await fs.mkdir(path.join(tmpDir, 'adapt-hotgrid-v1.0.0'))
+
+    await cleanupOldPluginBackups(tmpDir, 'adapt-hotgrid', log)
+
+    // Backup should still exist
+    await fs.access(path.join(tmpDir, 'adapt-hotgrid-v1.0.0'))
+    assert.equal(log.mock.callCount(), 0)
+  })
+
+  it('should remove all but the most recent backup', async () => {
+    await fs.mkdir(path.join(tmpDir, 'adapt-hotgrid-v1.0.0'))
+    await fs.mkdir(path.join(tmpDir, 'adapt-hotgrid-v2.0.0'))
+    await fs.mkdir(path.join(tmpDir, 'adapt-hotgrid-v3.0.0'))
+
+    await cleanupOldPluginBackups(tmpDir, 'adapt-hotgrid', log)
+
+    // v3.0.0 should survive, the others should be gone
+    await fs.access(path.join(tmpDir, 'adapt-hotgrid-v3.0.0'))
+    await assert.rejects(() => fs.access(path.join(tmpDir, 'adapt-hotgrid-v1.0.0')), { code: 'ENOENT' })
+    await assert.rejects(() => fs.access(path.join(tmpDir, 'adapt-hotgrid-v2.0.0')), { code: 'ENOENT' })
+  })
+
+  it('should log info for each removed backup', async () => {
+    await fs.mkdir(path.join(tmpDir, 'adapt-hotgrid-v1.0.0'))
+    await fs.mkdir(path.join(tmpDir, 'adapt-hotgrid-v2.0.0'))
+
+    await cleanupOldPluginBackups(tmpDir, 'adapt-hotgrid', log)
+
+    const infoCalls = log.mock.calls.filter(c => c.arguments[0] === 'info')
+    assert.equal(infoCalls.length, 1)
+  })
+
+  it('should not affect backups from other plugins', async () => {
+    await fs.mkdir(path.join(tmpDir, 'adapt-hotgrid-v1.0.0'))
+    await fs.mkdir(path.join(tmpDir, 'adapt-hotgrid-v2.0.0'))
+    await fs.mkdir(path.join(tmpDir, 'adapt-text-v1.0.0'))
+
+    await cleanupOldPluginBackups(tmpDir, 'adapt-hotgrid', log)
+
+    // adapt-text backup should be untouched
+    await fs.access(path.join(tmpDir, 'adapt-text-v1.0.0'))
+  })
+})
+
+// ---------------------------------------------------------------------------
+// restorePluginFromBackup
+// ---------------------------------------------------------------------------
+describe('restorePluginFromBackup()', () => {
+  let tmpDir
+  let log
+
+  beforeEach(async () => {
+    tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), 'cpu-test-'))
+    log = mock.fn()
+  })
+
+  afterEach(async () => {
+    await fs.rm(tmpDir, { recursive: true, force: true })
+  })
+
+  it('should return null when no backup exists', async () => {
+    const result = await restorePluginFromBackup(tmpDir, 'adapt-hotgrid', log)
+    assert.equal(result, null)
+  })
+
+  it('should restore the most recent backup into the plugin directory', async () => {
+    const backupDir = path.join(tmpDir, 'adapt-hotgrid-v2.0.0')
+    await fs.mkdir(backupDir)
+    await fs.writeFile(path.join(backupDir, 'package.json'), JSON.stringify({ name: 'adapt-hotgrid', version: '2.0.0' }))
+
+    const result = await restorePluginFromBackup(tmpDir, 'adapt-hotgrid', log)
+
+    assert.equal(result.name, 'adapt-hotgrid')
+    assert.equal(result.version, '2.0.0')
+    // Plugin dir should now exist, backup dir should be gone
+    await fs.access(path.join(tmpDir, 'adapt-hotgrid'))
+    await assert.rejects(() => fs.access(backupDir), { code: 'ENOENT' })
+  })
+
+  it('should remove the current plugin directory before restoring', async () => {
+    // Create current version
+    const pluginPath = path.join(tmpDir, 'adapt-hotgrid')
+    await fs.mkdir(pluginPath)
+    await fs.writeFile(path.join(pluginPath, 'package.json'), JSON.stringify({ name: 'adapt-hotgrid', version: '3.0.0' }))
+    // Create backup
+    const backupDir = path.join(tmpDir, 'adapt-hotgrid-v2.0.0')
+    await fs.mkdir(backupDir)
+    await fs.writeFile(path.join(backupDir, 'package.json'), JSON.stringify({ name: 'adapt-hotgrid', version: '2.0.0' }))
+
+    const result = await restorePluginFromBackup(tmpDir, 'adapt-hotgrid', log)
+
+    assert.equal(result.version, '2.0.0')
+  })
+
+  it('should read version from bower.json if no package.json', async () => {
+    const backupDir = path.join(tmpDir, 'adapt-hotgrid-v1.0.0')
+    await fs.mkdir(backupDir)
+    await fs.writeFile(path.join(backupDir, 'bower.json'), JSON.stringify({ name: 'adapt-hotgrid', version: '1.0.0' }))
+
+    const result = await restorePluginFromBackup(tmpDir, 'adapt-hotgrid', log)
+
+    assert.equal(result.version, '1.0.0')
+  })
+
+  it('should throw when backup has neither package.json nor bower.json', async () => {
+    const backupDir = path.join(tmpDir, 'adapt-hotgrid-v1.0.0')
+    await fs.mkdir(backupDir)
+    await fs.writeFile(path.join(backupDir, 'readme.txt'), 'no metadata')
+
+    await assert.rejects(
+      () => restorePluginFromBackup(tmpDir, 'adapt-hotgrid', log),
+      (err) => err.message.includes('Could not read package.json or bower.json')
+    )
+  })
+
+  it('should log an info message on success', async () => {
+    const backupDir = path.join(tmpDir, 'adapt-hotgrid-v1.0.0')
+    await fs.mkdir(backupDir)
+    await fs.writeFile(path.join(backupDir, 'package.json'), JSON.stringify({ name: 'adapt-hotgrid', version: '1.0.0' }))
+
+    await restorePluginFromBackup(tmpDir, 'adapt-hotgrid', log)
+
+    const infoCalls = log.mock.calls.filter(c => c.arguments[0] === 'info')
+    assert.equal(infoCalls.length, 1)
+    assert.ok(infoCalls[0].arguments[1].includes('adapt-hotgrid'))
+  })
+})
+
+// ---------------------------------------------------------------------------
+// processPluginFiles
+// ---------------------------------------------------------------------------
+describe('processPluginFiles()', () => {
+  let tmpDir
+  let pluginDir
+  let log
+
+  beforeEach(async () => {
+    tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), 'cpu-test-'))
+    pluginDir = path.join(tmpDir, 'plugins')
+    await fs.mkdir(pluginDir)
+    log = mock.fn()
+  })
+
+  afterEach(async () => {
+    await fs.rm(tmpDir, { recursive: true, force: true })
+  })
+
+  it('should return a non-local install when sourcePath has no directory component', async () => {
+    const result = await processPluginFiles(
+      { name: 'adapt-hotgrid', sourcePath: '4.3.5' },
+      pluginDir,
+      log
+    )
+    assert.deepEqual(result, { name: 'adapt-hotgrid', version: '4.3.5', isLocalInstall: false })
+  })
+
+  it('should read package.json and copy source to pluginDir', async () => {
+    // Create source directory with plugin files
+    const sourcePath = path.join(tmpDir, 'source', 'adapt-hotgrid')
+    await fs.mkdir(sourcePath, { recursive: true })
+    await fs.writeFile(
+      path.join(sourcePath, 'package.json'),
+      JSON.stringify({ name: 'adapt-hotgrid', version: '4.3.5' })
+    )
+    await fs.writeFile(path.join(sourcePath, 'index.js'), 'module.exports = {}')
+
+    const result = await processPluginFiles(
+      { name: 'adapt-hotgrid', sourcePath },
+      pluginDir,
+      log
+    )
+
+    assert.equal(result.name, 'adapt-hotgrid')
+    assert.equal(result.version, '4.3.5')
+    assert.equal(result.isLocalInstall, true)
+    assert.equal(result.sourcePath, path.join(pluginDir, 'adapt-hotgrid'))
+
+    // Plugin should now be in pluginDir
+    const copiedPkg = await readJson(path.join(pluginDir, 'adapt-hotgrid', 'package.json'))
+    assert.equal(copiedPkg.version, '4.3.5')
+
+    // Source should be removed
+    await assert.rejects(() => fs.access(sourcePath), { code: 'ENOENT' })
+  })
+
+  it('should fall back to bower.json when package.json is absent', async () => {
+    const sourcePath = path.join(tmpDir, 'source', 'adapt-vanilla')
+    await fs.mkdir(sourcePath, { recursive: true })
+    await fs.writeFile(
+      path.join(sourcePath, 'bower.json'),
+      JSON.stringify({ name: 'adapt-vanilla', version: '2.0.0' })
+    )
+    await fs.writeFile(path.join(sourcePath, 'index.js'), '')
+
+    const result = await processPluginFiles(
+      { name: 'adapt-vanilla', sourcePath },
+      pluginDir,
+      log
+    )
+
+    assert.equal(result.name, 'adapt-vanilla')
+    assert.equal(result.isLocalInstall, true)
+  })
+
+  it('should handle a nested root folder in the source', async () => {
+    // Source has a single subfolder containing the actual plugin
+    const sourcePath = path.join(tmpDir, 'source')
+    await fs.mkdir(path.join(sourcePath, 'adapt-hotgrid'), { recursive: true })
+    await fs.writeFile(
+      path.join(sourcePath, 'adapt-hotgrid', 'package.json'),
+      JSON.stringify({ name: 'adapt-hotgrid', version: '1.0.0' })
+    )
+
+    const result = await processPluginFiles(
+      { name: 'adapt-hotgrid', sourcePath },
+      pluginDir,
+      log
+    )
+
+    assert.equal(result.name, 'adapt-hotgrid')
+    assert.equal(result.isLocalInstall, true)
+  })
+
+  it('should throw when source has no package.json or bower.json', async () => {
+    const sourcePath = path.join(tmpDir, 'source', 'bad-plugin')
+    await fs.mkdir(sourcePath, { recursive: true })
+    await fs.writeFile(path.join(sourcePath, 'readme.txt'), 'no metadata')
+
+    await assert.rejects(
+      () => processPluginFiles(
+        { name: 'bad-plugin', sourcePath },
+        pluginDir,
+        log
+      ),
+      (err) => err.message.startsWith('Invalid plugin zip')
+    )
+  })
+
+  it('should back up existing plugin before copying new version', async () => {
+    // Pre-existing plugin in pluginDir
+    const existingPath = path.join(pluginDir, 'adapt-hotgrid')
+    await fs.mkdir(existingPath)
+    await fs.writeFile(
+      path.join(existingPath, 'package.json'),
+      JSON.stringify({ name: 'adapt-hotgrid', version: '3.0.0' })
+    )
+
+    // New source
+    const sourcePath = path.join(tmpDir, 'source', 'adapt-hotgrid')
+    await fs.mkdir(sourcePath, { recursive: true })
+    await fs.writeFile(
+      path.join(sourcePath, 'package.json'),
+      JSON.stringify({ name: 'adapt-hotgrid', version: '4.0.0' })
+    )
+    await fs.writeFile(path.join(sourcePath, 'index.js'), '')
+
+    const result = await processPluginFiles(
+      { name: 'adapt-hotgrid', sourcePath },
+      pluginDir,
+      log
+    )
+
+    assert.equal(result.version, '4.0.0')
+    // Backup should exist
+    await fs.access(path.join(pluginDir, 'adapt-hotgrid-v3.0.0'))
+    // New version should be in place
+    const pkg = await readJson(path.join(pluginDir, 'adapt-hotgrid', 'package.json'))
+    assert.equal(pkg.version, '4.0.0')
+  })
+})