adapt-authoring-adaptframework 1.12.0 → 2.0.0

package/lib/utils/copyFrameworkSource.js

@@ -0,0 +1,35 @@
+import { App } from 'adapt-authoring-core'
+import fs from 'fs/promises'
+import path from 'upath'
+
+/**
+ * Copies the framework source directory
+ * @param {Object} options
+ * @param {String} options.destDir The destination directory path
+ * @param {Array<String>} options.enabledPlugins List of plugins to include
+ * @param {Boolean} options.copyNodeModules Whether to physically copy node_modules
+ * @param {Boolean} options.linkNodeModules Whether to symlink node_modules
+ * @return {Promise}
+ */
+export async function copyFrameworkSource (options) {
+  const { path: fwPath } = await App.instance.waitForModule('adaptframework')
+  const BLACKLIST = ['.git', '.DS_Store', 'thumbs.db', 'course', 'migrations']
+  if (options.copyNodeModules !== true) BLACKLIST.push('node_modules')
+
+  const srcDir = path.join(fwPath, 'src')
+  const enabledPlugins = options.enabledPlugins ?? []
+  await fs.cp(fwPath, options.destDir, {
+    recursive: true,
+    filter: f => {
+      f = path.normalize(f)
+      const [type, name] = path.relative(srcDir, f).split('/')
+      const isPlugin = f.startsWith(srcDir) && type && type !== 'core' && !!name
+
+      if (isPlugin && !enabledPlugins.includes(name)) {
+        return false
+      }
+      return !BLACKLIST.includes(path.basename(f))
+    }
+  })
+  if (options.linkNodeModules !== false) await fs.symlink(`${fwPath}/node_modules`, `${options.destDir}/node_modules`, 'junction')
+}

package/lib/utils/getImportContentCounts.js

@@ -0,0 +1,13 @@
+/**
+ * Returns a map of content types and their instance count in the content JSON
+ * @param {Object} content Course content
+ * @returns {Object}
+ */
+export function getImportContentCounts (content) {
+  return Object.values(content).reduce((m, c) => {
+    const items = c._type ? [c] : Object.values(c)
+    return items.reduce((m, { _type }) => {
+      return { ...m, [_type]: m[_type] !== undefined ? m[_type] + 1 : 1 }
+    }, m)
+  }, {})
+}

package/lib/utils/getImportSummary.js

@@ -0,0 +1,55 @@
+import { App } from 'adapt-authoring-core'
+import { getPluginUpdateStatus } from './getPluginUpdateStatus.js'
+import { getImportContentCounts } from './getImportContentCounts.js'
+
+/**
+ * @typedef {AdaptFrameworkImportSummary}
+ * @property {String} title Course title
+ * @property {String} courseId Course _id
+ * @property {Object} statusReport Status report
+ * @property {Object<String>} statusReport.info Information messages
+ * @property {Array<String>} statusReport.warn Warning messages
+ * @property {Object} content Object mapping content types to the number of items of that type found in the imported course
+ * @property {Object} versions A map of plugins used in the imported course and their versions
+ *
+ * @param {AdaptFrameworkImport} importer The import instance
+ * @return {AdaptFrameworkImportSummary} Object mapping all import versions to server installed versions
+ * @example
+ * {
+ *   adapt_framework: [1.0.0, 2.0.0],
+ *   adapt-contrib-vanilla: [1.0.0, 2.0.0]
+ * }
+ */
+export async function getImportSummary (importer) {
+  const [framework, contentplugin] = await App.instance.waitForModule('adaptframework', 'contentplugin')
+  const installedPlugins = await contentplugin.find()
+  const {
+    pkg: { name: fwName, version: fwVersion },
+    idMap: { course: courseId },
+    contentJson,
+    usedContentPlugins: usedPlugins,
+    newContentPlugins: newPlugins,
+    statusReport,
+    settings: { updatePlugins }
+  } = importer
+  const versions = [
+    { name: fwName, versions: [framework.version, fwVersion] },
+    ...Object.values(usedPlugins),
+    ...Object.values(newPlugins)
+  ].map(meta => {
+    const p = installedPlugins.find(p => p.name === meta.name)
+    const versions = meta.versions ?? [p?.version, meta.version]
+    return {
+      name: meta.name,
+      status: getPluginUpdateStatus(versions, p?.isLocalInstall, updatePlugins),
+      versions
+    }
+  })
+  return {
+    title: contentJson.course.displayTitle || contentJson.course.title,
+    courseId,
+    statusReport,
+    content: getImportContentCounts(contentJson),
+    versions
+  }
+}

package/lib/utils/getPluginUpdateStatus.js

@@ -0,0 +1,20 @@
+import semver from 'semver'
+
+/**
+ * Determines the update status code for a plugin based on version comparison
+ * @param {Array} versions Tuple of [installedVersion, importVersion]
+ * @param {Boolean} isLocalInstall Whether the plugin is a local install
+ * @param {Boolean} updatePlugins Whether plugin updates are enabled
+ * @returns {String} The update status code
+ */
+export function getPluginUpdateStatus (versions, isLocalInstall, updatePlugins) {
+  const [installedVersion, importVersion] = versions
+  if (!semver.valid(importVersion)) return 'INVALID'
+  if (!installedVersion) return 'INSTALLED'
+  if (semver.lt(importVersion, installedVersion)) return 'OLDER'
+  if (semver.gt(importVersion, installedVersion)) {
+    if (!updatePlugins && !isLocalInstall) return 'UPDATE_BLOCKED'
+    return 'UPDATED'
+  }
+  return 'NO_CHANGE'
+}

package/lib/utils/inferBuildAction.js

@@ -0,0 +1,9 @@
+/**
+ * Infers the framework action to be executed from a given request URL
+ * @param {external:ExpressRequest} req
+ * @return {String}
+ */
+export function inferBuildAction (req) {
+  const end = req.url.indexOf('/', 1)
+  return req.url.slice(1, end === -1 ? undefined : end)
+}

package/lib/utils/log.js

@@ -0,0 +1,37 @@
+import { App } from 'adapt-authoring-core'
+import bytes from 'bytes'
+import fsSync from 'fs'
+import path from 'upath'
+
+let fw
+
+/**
+ * Logs a message using the framework module
+ * @param {...*} args Arguments to be logged
+ */
+export async function log (...args) {
+  if (!fw) fw = await App.instance.waitForModule('adaptframework')
+  return fw.log(...args)
+}
+
+/**
+ * Logs directory path and file mode information
+ * @param {string} label Label for the directory
+ * @param {string} dir Directory path
+ */
+export function logDir (label, dir) {
+  try {
+    const resolved = dir ? path.resolve(dir) : undefined
+    log('verbose', 'DIR', label, resolved)
+    if (resolved) log('verbose', 'DIR_MODE', label, fsSync.statSync(resolved).mode)
+  } catch (e) {
+    log('warn', `failed to log dir ${label} (${dir}), ${e.code}`)
+  }
+}
+
+/**
+ * Logs current memory usage statistics
+ */
+export function logMemory () {
+  log('verbose', 'MEMORY', Object.entries(process.memoryUsage()).reduce((m, [k, v]) => Object.assign(m, { [k]: bytes.parse(v) }), {}))
+}

package/lib/utils/retrieveBuildData.js

@@ -0,0 +1,18 @@
+import { App } from 'adapt-authoring-core'
+
+/** @ignore */ const buildCache = {}
+
+/**
+ * Retrieves metadata for a build attempt
+ * @param {String} id ID of build document
+ * @return {Promise}
+ */
+export async function retrieveBuildData (id) {
+  if (buildCache[id]) {
+    return buildCache[id]
+  }
+  const mdb = await App.instance.waitForModule('mongodb')
+  const [data] = await mdb.find('adaptbuilds', { _id: id })
+  buildCache[id] = data
+  return data
+}

package/lib/utils/runCliCommand.js

@@ -0,0 +1,24 @@
+import AdaptCli from 'adapt-cli'
+import { App } from 'adapt-authoring-core'
+
+/**
+ * Wrapper for running adapt-cli commands
+ * @param {string} command Command to run
+ * @param {object} opts Extra options
+ */
+export async function runCliCommand (command, opts = {}) {
+  if (typeof AdaptCli[command] !== 'function') {
+    throw App.instance.errors.FW_CLI_UNKNOWN_CMD.setData({ command })
+  }
+  const debugLog = (...args) => App.instance.logger.log('debug', 'adapt-cli', ...args)
+
+  App.instance.logger.log('verbose', 'adapt-cli', 'CMD_START', command, opts)
+  const res = await AdaptCli[command]({
+    cwd: App.instance.config.get('adapt-authoring-adaptframework.frameworkDir'),
+    repository: App.instance.config.get('adapt-authoring-adaptframework.frameworkRepository'),
+    logger: { log: debugLog, logProgress: debugLog, write: debugLog },
+    ...opts
+  })
+  App.instance.logger.log('verbose', 'adapt-cli', 'CMD_END', command, opts)
+  return res
+}

package/lib/utils/slugifyTitle.js

@@ -0,0 +1,18 @@
+import { App } from 'adapt-authoring-core'
+
+/**
+ * Returns a 'slugified' version of the course title appropriate for a filename
+ * @param {Object} buildData The course build data
+ * @returns {string} The slugified title
+ */
+export async function slugifyTitle (buildData) {
+  const content = await App.instance.waitForModule('content')
+  const [course] = await content.find({ _id: buildData.courseId })
+  const sanitisedTitle = course.title
+    .toLowerCase()
+    .trim()
+    .replace(/[^a-z0-9 -]/g, '') // remove non-alphanumeric
+    .replace(/\s+/g, '-') // replace spaces with hyphens
+    .replace(/-+/g, '-') // remove duplicate hyphens
+  return `${sanitisedTitle}${buildData.action === 'export' ? '-export' : ''}`
+}

package/lib/utils.js

@@ -0,0 +1,9 @@
+export { inferBuildAction } from './utils/inferBuildAction.js'
+export { getPluginUpdateStatus } from './utils/getPluginUpdateStatus.js'
+export { getImportContentCounts } from './utils/getImportContentCounts.js'
+export { log, logDir, logMemory } from './utils/log.js'
+export { runCliCommand } from './utils/runCliCommand.js'
+export { retrieveBuildData } from './utils/retrieveBuildData.js'
+export { getImportSummary } from './utils/getImportSummary.js'
+export { slugifyTitle } from './utils/slugifyTitle.js'
+export { copyFrameworkSource } from './utils/copyFrameworkSource.js'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "adapt-authoring-adaptframework",
-  "version": "1.12.0",
+  "version": "2.0.0",
   "description": "Adapt framework integration for the Adapt authoring tool",
   "homepage": "https://github.com/adapt-security/adapt-authoring-adaptframework",
   "license": "GPL-3.0",
@@ -14,7 +14,7 @@
     "adapt-authoring-browserslist": "^1.2.1",
     "adapt-authoring-content": "^1.2.3",
     "adapt-authoring-contentplugin": "^1.0.3",
-    "adapt-authoring-core": "^1.7.0",
+    "adapt-authoring-core": "^2.0.0",
     "adapt-authoring-courseassets": "^1.0.3",
     "adapt-authoring-coursetheme": "^1.0.2",
     "adapt-authoring-spoortracking": "^1.0.2",

package/tests/AdaptFrameworkBuild.spec.js

@@ -1,9 +1,10 @@
-import { describe, it, before, after } from 'node:test'
+import { describe, it, after } from 'node:test'
 import assert from 'node:assert/strict'
 import _ from 'lodash'
 import fs from 'fs/promises'
 import path from 'path'
 import { fileURLToPath } from 'url'
+import { ensureDir } from 'adapt-authoring-core'
 import AdaptFrameworkBuild from '../lib/AdaptFrameworkBuild.js'
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url))
@@ -113,26 +114,21 @@ describe('AdaptFrameworkBuild', () => {
     })
   })
 
-  describe('#ensureDir()', () => {
+  describe('ensureDir() (from core)', () => {
     const testDir = path.join(__dirname, 'data', 'ensure-dir-test')
-    let build
-
-    before(() => {
-      build = new AdaptFrameworkBuild({ action: 'preview', courseId: 'c1', userId: 'u1' })
-    })
 
     after(async () => {
       await fs.rm(testDir, { recursive: true, force: true })
     })
 
     it('should create a directory that does not exist', async () => {
-      await build.ensureDir(testDir)
+      await ensureDir(testDir)
       const stat = await fs.stat(testDir)
       assert.ok(stat.isDirectory())
     })
 
     it('should not throw when the directory already exists', async () => {
-      await build.ensureDir(testDir)
+      await ensureDir(testDir)
       const stat = await fs.stat(testDir)
       assert.ok(stat.isDirectory())
     })

package/tests/utils-getImportContentCounts.spec.js

@@ -0,0 +1,30 @@
+import { describe, it } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { getImportContentCounts } from '../lib/utils/getImportContentCounts.js'
+
+describe('getImportContentCounts()', () => {
+  it('should count single items by _type', () => {
+    const content = {
+      course: { _type: 'course' },
+      config: { _type: 'config' }
+    }
+    assert.deepEqual(getImportContentCounts(content), { course: 1, config: 1 })
+  })
+
+  it('should count arrays of items by _type', () => {
+    const content = {
+      course: { _type: 'course' },
+      contentObjects: {
+        co1: { _type: 'page' },
+        co2: { _type: 'page' },
+        co3: { _type: 'menu' }
+      }
+    }
+    assert.deepEqual(getImportContentCounts(content), { course: 1, page: 2, menu: 1 })
+  })
+
+  it('should return empty object for empty content', () => {
+    assert.deepEqual(getImportContentCounts({}), {})
+  })
+})

package/tests/utils-getPluginUpdateStatus.spec.js

@@ -0,0 +1,34 @@
+import { describe, it } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { getPluginUpdateStatus } from '../lib/utils/getPluginUpdateStatus.js'
+
+describe('getPluginUpdateStatus()', () => {
+  it('should return "INVALID" for an invalid import version', () => {
+    assert.equal(getPluginUpdateStatus(['1.0.0', 'not-valid'], false, false), 'INVALID')
+  })
+
+  it('should return "INSTALLED" when no installed version exists', () => {
+    assert.equal(getPluginUpdateStatus([undefined, '1.0.0'], false, false), 'INSTALLED')
+  })
+
+  it('should return "OLDER" when import version is older', () => {
+    assert.equal(getPluginUpdateStatus(['2.0.0', '1.0.0'], false, false), 'OLDER')
+  })
+
+  it('should return "NO_CHANGE" when versions are equal', () => {
+    assert.equal(getPluginUpdateStatus(['1.0.0', '1.0.0'], false, false), 'NO_CHANGE')
+  })
+
+  it('should return "UPDATE_BLOCKED" when import is newer but updates not enabled and not local', () => {
+    assert.equal(getPluginUpdateStatus(['1.0.0', '2.0.0'], false, false), 'UPDATE_BLOCKED')
+  })
+
+  it('should return "UPDATED" when import is newer and updates are enabled', () => {
+    assert.equal(getPluginUpdateStatus(['1.0.0', '2.0.0'], false, true), 'UPDATED')
+  })
+
+  it('should return "UPDATED" when import is newer and is a local install', () => {
+    assert.equal(getPluginUpdateStatus(['1.0.0', '2.0.0'], true, false), 'UPDATED')
+  })
+})

package/tests/utils-inferBuildAction.spec.js

@@ -0,0 +1,21 @@
+import { describe, it } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { inferBuildAction } from '../lib/utils/inferBuildAction.js'
+
+describe('inferBuildAction()', () => {
+  const cases = [
+    { url: '/preview/abc123', expected: 'preview' },
+    { url: '/publish/abc123', expected: 'publish' },
+    { url: '/export/abc123', expected: 'export' }
+  ]
+  cases.forEach(({ url, expected }) => {
+    it(`should return "${expected}" for URL "${url}"`, () => {
+      assert.equal(inferBuildAction({ url }), expected)
+    })
+  })
+
+  it('should return full action for URLs without trailing slash', () => {
+    assert.equal(inferBuildAction({ url: '/import' }), 'import')
+  })
+})