adapt-authoring-adaptframework 2.5.6 → 3.0.0

package/lib/utils/runContentMigration.js

@@ -0,0 +1,72 @@
+import fs from 'node:fs'
+import path from 'node:path'
+import { createRequire } from 'node:module'
+import { App, ensureDir } from 'adapt-authoring-core'
+import { load, migrate, Journal, Logger } from 'adapt-migrations'
+
+const require = createRequire(import.meta.url)
+
+/**
+ * Runs adapt-migrations on a content array. Shared by framework update, course import, and plugin update.
+ * @param {Object} options
+ * @param {Array} options.content Flat array of content objects (course, config, contentObjects, etc.)
+ * @param {Array<{name: String, version: String}>} options.fromPlugins Plugin versions before the update
+ * @param {Array<{name: String, version: String}>} options.toPlugins Plugin versions after the update
+ * @param {String[]} options.scripts Absolute paths to migration scripts
+ * @param {String} [options.cachePath] Optional cache path for adapt-migrations. If omitted, a unique dir under the app's tempDir is created and removed after migration — callers running concurrently MUST either omit this or pass a unique path per call, as adapt-migrations wipes the directory on entry.
+ * @returns {Promise<Array>} The migrated content array
+ */
+export async function runContentMigration ({ content, fromPlugins, toPlugins, scripts, cachePath }) {
+  const logger = Logger.getInstance()
+
+  let resolvedCachePath = cachePath
+  const usingEphemeralCache = !resolvedCachePath
+  if (usingEphemeralCache) {
+    const tempDir = App.instance.getConfig('tempDir')
+    const baseCacheDir = path.join(tempDir, 'migration-cache')
+    await ensureDir(baseCacheDir)
+    // Symlink node_modules at the base so cached migration scripts' bare
+    // `import 'adapt-migrations'` resolves via Node's upward walk. It must sit
+    // a level ABOVE the run dir, otherwise adapt-migrations's own `npm install`
+    // step (which runs in the run dir) wipes the symlink.
+    const sharedLink = path.join(baseCacheDir, 'node_modules')
+    if (!fs.existsSync(sharedLink)) {
+      const sharedNodeModules = path.dirname(path.dirname(require.resolve('adapt-migrations')))
+      try {
+        fs.symlinkSync(sharedNodeModules, sharedLink, 'dir')
+      } catch (err) {
+        if (err.code !== 'EEXIST') throw err
+      }
+    }
+    resolvedCachePath = fs.mkdtempSync(path.join(baseCacheDir, 'run-'))
+  } else {
+    await ensureDir(resolvedCachePath)
+  }
+
+  try {
+    await load({ scripts, cachePath: resolvedCachePath, logger })
+
+    const originalFromPlugins = JSON.parse(JSON.stringify(fromPlugins))
+    const journal = new Journal({
+      logger,
+      data: {
+        content,
+        fromPlugins,
+        originalFromPlugins,
+        toPlugins
+      }
+    })
+
+    await migrate({ journal, logger })
+
+    return journal.data.content
+  } finally {
+    if (usingEphemeralCache) {
+      try {
+        fs.rmSync(resolvedCachePath, { recursive: true, force: true })
+      } catch (err) {
+        logger.warn(`Failed to clean up migration cache at ${resolvedCachePath}: ${err.message}`)
+      }
+    }
+  }
+}

package/lib/utils.js

@@ -7,3 +7,11 @@ export { retrieveBuildData } from './utils/retrieveBuildData.js'
 export { getImportSummary } from './utils/getImportSummary.js'
 export { slugifyTitle } from './utils/slugifyTitle.js'
 export { copyFrameworkSource } from './utils/copyFrameworkSource.js'
+export { readFrameworkPluginVersions } from './utils/readFrameworkPluginVersions.js'
+export { collectMigrationScripts } from './utils/collectMigrationScripts.js'
+export { runContentMigration } from './utils/runContentMigration.js'
+export { migrateExistingCourses } from './utils/migrateExistingCourses.js'
+export { computePluginHash } from './utils/computePluginHash.js'
+export { prebuildCache } from './utils/prebuildCache.js'
+export { generateLanguageManifest } from './utils/generateLanguageManifest.js'
+export { applyBuildReplacements } from './utils/applyBuildReplacements.js'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "adapt-authoring-adaptframework",
-  "version": "2.5.6",
+  "version": "3.0.0",
   "description": "Adapt framework integration for the Adapt authoring tool",
   "homepage": "https://github.com/adapt-security/adapt-authoring-adaptframework",
   "license": "GPL-3.0",
@@ -11,15 +11,14 @@
     "test": "node --test --test-force-exit --experimental-test-module-mocks 'tests/**/*.spec.js'"
   },
   "dependencies": {
-    "adapt-authoring-content": "^2.0.0",
+    "adapt-authoring-content": "^3.0.0",
     "adapt-authoring-contentplugin": "^1.0.3",
-    "adapt-authoring-core": "^2.0.0",
-    "adapt-authoring-courseassets": "^1.0.3",
+    "adapt-authoring-core": "^3.0.0",
     "adapt-authoring-coursetheme": "^1.0.2",
     "adapt-authoring-mongodb": "^3.0.0",
     "adapt-authoring-spoortracking": "^1.0.2",
     "adapt-cli": "^3.3.3",
-    "adapt-octopus": "^0.1.2",
+    "adapt-migrations": "^1.4.0",
     "bytes": "^3.1.2",
     "fs-extra": "11.3.3",
     "glob": "^13.0.0",

package/tests/AdaptFrameworkImport.spec.js

@@ -150,7 +150,7 @@ describe('AdaptFrameworkImport', () => {
 
   describe('#resolveAssets()', () => {
     function makeCtx (assetMap) {
-      const ctx = { assetMap }
+      const ctx = { assetMap, statusReport: { warn: [] } }
       ctx.resolveAssets = AdaptFrameworkImport.prototype.resolveAssets.bind(ctx)
       return ctx
     }
@@ -207,14 +207,17 @@ describe('AdaptFrameworkImport', () => {
       assert.equal('src' in data._graphic, false)
     })
 
-    it('should keep value when not in assetMap', () => {
+    it('should drop unresolved asset refs and surface them in statusReport.warn', () => {
       const ctx = makeCtx({})
       const schema = makeSchema({
         img: { _backboneForms: { type: 'Asset' } }
       })
       const data = { img: 'unknown/path.png' }
       ctx.resolveAssets(schema, data)
-      assert.equal(data.img, 'unknown/path.png')
+      assert.equal('img' in data, false)
+      assert.equal(ctx.statusReport.warn.length, 1)
+      assert.equal(ctx.statusReport.warn[0].code, 'UNRESOLVED_ASSET_REF')
+      assert.equal(ctx.statusReport.warn[0].data.path, 'unknown/path.png')
     })
 
     it('should recurse into nested properties', () => {
@@ -407,7 +410,6 @@ describe('AdaptFrameworkImport', () => {
         contentplugin: null,
         assets: null,
         content: null,
-        courseassets: null,
         ...overrides
       }
     }
@@ -442,22 +444,17 @@ describe('AdaptFrameworkImport', () => {
       assert.deepEqual(deleted.sort(), ['a1', 'a2'])
     })
 
-    it('should delete course content and course assets', async () => {
+    it('should delete course content on rollback', async () => {
       const contentDeleted = []
-      const courseAssetsDeleted = []
       const ctx = makeRollbackCtx({
         content: {
           deleteMany: async (query) => contentDeleted.push(query)
         },
-        courseassets: {
-          deleteMany: async (query) => courseAssetsDeleted.push(query)
-        },
         contentJson: { course: { _id: 'oldCourseId' } },
         idMap: { oldCourseId: '507f1f77bcf86cd799439011' }
       })
       await rollback.call(ctx)
       assert.equal(contentDeleted.length, 1)
-      assert.equal(courseAssetsDeleted.length, 1)
     })
 
     it('should skip plugin uninstall when contentplugin is not available', async () => {
@@ -482,9 +479,6 @@ describe('AdaptFrameworkImport', () => {
         content: {
           deleteMany: async (query) => deleted.push(query)
         },
-        courseassets: {
-          deleteMany: async (query) => deleted.push(query)
-        },
         contentJson: { course: { _id: 'oldCourseId' } },
         idMap: {} // no mapping exists
       })

package/tests/BuildCache.spec.js

@@ -0,0 +1,107 @@
+import { before, describe, it, beforeEach, afterEach, mock } from 'node:test'
+import assert from 'node:assert/strict'
+import fs from 'node:fs/promises'
+import path from 'node:path'
+import upath from 'upath'
+import os from 'node:os'
+
+describe('BuildCache', () => {
+  let BuildCache
+  let tmpDir, cacheRoot, buildDir, cache
+
+  before(async () => {
+    mock.module('../lib/utils/log.js', {
+      namedExports: {
+        log: () => {},
+        logDir: () => {},
+        logMemory: () => {}
+      }
+    })
+    ;({ default: BuildCache } = await import('../lib/BuildCache.js'))
+  })
+
+  beforeEach(async () => {
+    tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), 'aat-cache-test-'))
+    cacheRoot = path.join(tmpDir, 'prebuilt-cache')
+    buildDir = path.join(tmpDir, 'build')
+    await fs.mkdir(buildDir, { recursive: true })
+    cache = new BuildCache(cacheRoot)
+  })
+
+  afterEach(async () => {
+    await fs.rm(tmpDir, { recursive: true, force: true })
+  })
+
+  describe('getPath()', () => {
+    it('returns one combo-keyed directory path', () => {
+      assert.equal(cache.getPath('abc123', 'vanilla', 'boxMenu'), upath.join(cacheRoot, 'abc123_vanilla_boxMenu'))
+    })
+  })
+
+  describe('has()', () => {
+    it('returns false when cache does not exist', async () => {
+      assert.equal(await cache.has('hash1', 'theme', 'menu'), false)
+    })
+
+    it('returns true when the combo dir exists', async () => {
+      await fs.mkdir(cache.getPath('hash1', 'theme', 'menu'), { recursive: true })
+      assert.equal(await cache.has('hash1', 'theme', 'menu'), true)
+    })
+  })
+
+  describe('populate()', () => {
+    it('caches all build entries except course/', async () => {
+      await fs.mkdir(path.join(buildDir, 'adapt', 'js'), { recursive: true })
+      await fs.writeFile(path.join(buildDir, 'adapt', 'js', 'adapt.min.js'), 'js-content')
+      await fs.writeFile(path.join(buildDir, 'adapt.css'), 'css-content')
+      await fs.writeFile(path.join(buildDir, 'adapt.css.map'), 'map-content')
+      await fs.mkdir(path.join(buildDir, 'fonts'), { recursive: true })
+      await fs.writeFile(path.join(buildDir, 'fonts', 'icon.woff2'), 'font-data')
+      await fs.writeFile(path.join(buildDir, 'index.html'), '<html></html>')
+      await fs.writeFile(path.join(buildDir, 'templates.js'), 'templates')
+      await fs.mkdir(path.join(buildDir, 'libraries'), { recursive: true })
+      await fs.writeFile(path.join(buildDir, 'libraries', 'modernizr.js'), 'lib')
+      // course/ should be skipped
+      await fs.mkdir(path.join(buildDir, 'course', 'en'), { recursive: true })
+      await fs.writeFile(path.join(buildDir, 'course', 'en', 'course.json'), '{}')
+
+      await cache.populate(buildDir, 'hash1', 'theme', 'menu')
+
+      const cacheDir = cache.getPath('hash1', 'theme', 'menu')
+      assert.equal(await fs.readFile(path.join(cacheDir, 'adapt', 'js', 'adapt.min.js'), 'utf8'), 'js-content')
+      assert.equal(await fs.readFile(path.join(cacheDir, 'index.html'), 'utf8'), '<html></html>')
+      assert.equal(await fs.readFile(path.join(cacheDir, 'adapt.css'), 'utf8'), 'css-content')
+      assert.equal(await fs.readFile(path.join(cacheDir, 'fonts', 'icon.woff2'), 'utf8'), 'font-data')
+      await assert.rejects(fs.access(path.join(cacheDir, 'course')), { code: 'ENOENT' })
+    })
+  })
+
+  describe('restore()', () => {
+    it('copies cached artifacts to destination', async () => {
+      const cacheDir = cache.getPath('hash1', 'theme', 'menu')
+      await fs.mkdir(path.join(cacheDir, 'adapt', 'js'), { recursive: true })
+      await fs.writeFile(path.join(cacheDir, 'adapt', 'js', 'adapt.min.js'), 'cached-js')
+      await fs.writeFile(path.join(cacheDir, 'adapt.css'), 'cached-css')
+
+      const destDir = path.join(tmpDir, 'restored')
+      await cache.restore('hash1', 'theme', 'menu', destDir)
+
+      assert.equal(await fs.readFile(path.join(destDir, 'adapt', 'js', 'adapt.min.js'), 'utf8'), 'cached-js')
+      assert.equal(await fs.readFile(path.join(destDir, 'adapt.css'), 'utf8'), 'cached-css')
+    })
+  })
+
+  describe('invalidate()', () => {
+    it('removes the cache directory', async () => {
+      await fs.mkdir(cacheRoot, { recursive: true })
+      await fs.writeFile(path.join(cacheRoot, 'test'), 'data')
+      await cache.invalidate()
+      await assert.rejects(fs.access(cacheRoot), { code: 'ENOENT' })
+    })
+
+    it('does not throw when cache does not exist', async () => {
+      const missing = new BuildCache(path.join(tmpDir, 'nonexistent'))
+      await assert.doesNotReject(missing.invalidate())
+    })
+  })
+})

package/tests/utils-applyBuildReplacements.spec.js

@@ -0,0 +1,57 @@
+import { describe, it, beforeEach, afterEach } from 'node:test'
+import assert from 'node:assert/strict'
+import fs from 'node:fs/promises'
+import path from 'node:path'
+import os from 'node:os'
+
+import { applyBuildReplacements } from '../lib/utils/applyBuildReplacements.js'
+
+describe('applyBuildReplacements()', () => {
+  let tmpDir
+
+  beforeEach(async () => {
+    tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), 'aat-replace-test-'))
+  })
+
+  afterEach(async () => {
+    await fs.rm(tmpDir, { recursive: true, force: true })
+  })
+
+  it('should replace all @@placeholders in index.html', async () => {
+    const template = [
+      '<html lang="@@config._defaultLanguage" dir="@@config._defaultDirection">',
+      '<meta name="build.type" content="@@build.type">',
+      '<meta name="build.timestamp" content="@@build.timestamp">'
+    ].join('\n')
+    await fs.writeFile(path.join(tmpDir, 'index.html'), template)
+
+    await applyBuildReplacements(tmpDir, {
+      defaultLanguage: 'fr',
+      defaultDirection: 'rtl',
+      buildType: 'development',
+      timestamp: 1234567890
+    })
+
+    const result = await fs.readFile(path.join(tmpDir, 'index.html'), 'utf8')
+    assert.ok(result.includes('lang="fr"'))
+    assert.ok(result.includes('dir="rtl"'))
+    assert.ok(result.includes('content="development"'))
+    assert.ok(result.includes('content="1234567890"'))
+    assert.ok(!result.includes('@@'))
+  })
+
+  it('should handle multiple occurrences of the same placeholder', async () => {
+    const template = '@@config._defaultLanguage @@config._defaultLanguage'
+    await fs.writeFile(path.join(tmpDir, 'index.html'), template)
+
+    await applyBuildReplacements(tmpDir, {
+      defaultLanguage: 'de',
+      defaultDirection: 'ltr',
+      buildType: 'production',
+      timestamp: 0
+    })
+
+    const result = await fs.readFile(path.join(tmpDir, 'index.html'), 'utf8')
+    assert.equal(result, 'de de')
+  })
+})

package/tests/utils-collectMigrationScripts.spec.js

@@ -0,0 +1,45 @@
+import { describe, it, beforeEach, afterEach } from 'node:test'
+import assert from 'node:assert/strict'
+import fs from 'node:fs/promises'
+import path from 'node:path'
+import os from 'node:os'
+
+import { collectMigrationScripts } from '../lib/utils/collectMigrationScripts.js'
+
+describe('collectMigrationScripts()', () => {
+  let tmpDir
+
+  beforeEach(async () => {
+    tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), 'fw-mig-'))
+    const srcDir = path.join(tmpDir, 'src')
+    await fs.mkdir(path.join(srcDir, 'core', 'migrations'), { recursive: true })
+    await fs.mkdir(path.join(srcDir, 'components', 'adapt-contrib-text', 'migrations'), { recursive: true })
+
+    await fs.writeFile(path.join(srcDir, 'core', 'migrations', '6.24.2.js'), '// core migration')
+    await fs.writeFile(path.join(srcDir, 'components', 'adapt-contrib-text', 'migrations', '5.0.1.js'), '// text migration')
+  })
+
+  afterEach(async () => {
+    await fs.rm(tmpDir, { recursive: true })
+  })
+
+  it('should find core and plugin migration scripts', async () => {
+    const scripts = await collectMigrationScripts(tmpDir)
+    assert.equal(scripts.length, 2)
+    assert.ok(scripts.some(s => s.includes('core/migrations/6.24.2.js')))
+    assert.ok(scripts.some(s => s.includes('adapt-contrib-text/migrations/5.0.1.js')))
+  })
+
+  it('should return absolute paths', async () => {
+    const scripts = await collectMigrationScripts(tmpDir)
+    scripts.forEach(s => assert.ok(path.isAbsolute(s)))
+  })
+
+  it('should return empty array when no migration scripts exist', async () => {
+    const emptyDir = await fs.mkdtemp(path.join(os.tmpdir(), 'fw-nomig-'))
+    await fs.mkdir(path.join(emptyDir, 'src'), { recursive: true })
+    const scripts = await collectMigrationScripts(emptyDir)
+    assert.deepEqual(scripts, [])
+    await fs.rm(emptyDir, { recursive: true })
+  })
+})

package/tests/utils-computePluginHash.spec.js

@@ -0,0 +1,40 @@
+import { before, describe, it, mock } from 'node:test'
+import assert from 'node:assert/strict'
+
+describe('computePluginHash()', () => {
+  let computePluginHash
+
+  before(async () => {
+    mock.module('adapt-cli/lib/integration/Project.js', {
+      defaultExport: class MockProject {
+        constructor ({ cwd }) { this.cwd = cwd }
+        async getInstalledDependencies () {
+          return {
+            'adapt-contrib-text': '1.0.0',
+            'adapt-contrib-narrative': '2.0.0',
+            'adapt-contrib-core': '3.0.0'
+          }
+        }
+      }
+    })
+    ;({ computePluginHash } = await import('../lib/utils/computePluginHash.js'))
+  })
+
+  it('should return a 16-character hex string', async () => {
+    const hash = await computePluginHash('/fake/framework')
+    assert.match(hash, /^[0-9a-f]{16}$/)
+  })
+
+  it('should return the same hash for the same plugin set', async () => {
+    const hash1 = await computePluginHash('/fake/framework')
+    const hash2 = await computePluginHash('/fake/framework')
+    assert.equal(hash1, hash2)
+  })
+
+  it('should produce a deterministic hash regardless of insertion order', async () => {
+    // The mock always returns the same deps — verify stability
+    const hash1 = await computePluginHash('/path/a')
+    const hash2 = await computePluginHash('/path/b')
+    assert.equal(hash1, hash2)
+  })
+})

package/tests/utils-generateLanguageManifest.spec.js

@@ -0,0 +1,27 @@
+import { describe, it } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { generateLanguageManifest } from '../lib/utils/generateLanguageManifest.js'
+
+describe('generateLanguageManifest()', () => {
+  it('should return all filenames except the manifest and assets.json', () => {
+    const input = ['course.json', 'contentObjects.json', 'articles.json', 'language_data_manifest.js', 'assets.json']
+    const result = generateLanguageManifest(input)
+    assert.deepEqual(result, ['course.json', 'contentObjects.json', 'articles.json'])
+  })
+
+  it('should return an empty array when only excluded files are present', () => {
+    const result = generateLanguageManifest(['language_data_manifest.js', 'assets.json'])
+    assert.deepEqual(result, [])
+  })
+
+  it('should return all filenames when no exclusions apply', () => {
+    const input = ['course.json', 'blocks.json']
+    const result = generateLanguageManifest(input)
+    assert.deepEqual(result, ['course.json', 'blocks.json'])
+  })
+
+  it('should handle an empty input array', () => {
+    assert.deepEqual(generateLanguageManifest([]), [])
+  })
+})

package/tests/utils-migrateExistingCourses.spec.js

@@ -0,0 +1,163 @@
+import { describe, it, mock } from 'node:test'
+import assert from 'node:assert/strict'
+
+const mockContentModule = {
+  find: mock.fn(async () => [
+    { _id: 'course1', _type: 'course', title: 'Course 1' }
+  ]),
+  findOne: mock.fn(async ({ _id, _type, _courseId }) => {
+    if (_type === 'config') return { _id: 'cfg1', _type: 'config', _courseId }
+    return { _id, _type: 'course', title: 'Course 1' }
+  }),
+  update: mock.fn(async () => {})
+}
+
+mock.module('adapt-authoring-core', {
+  namedExports: {
+    App: {
+      instance: {
+        waitForModule: mock.fn(async () => mockContentModule)
+      }
+    }
+  }
+})
+
+const mockCollectMigrationScripts = mock.fn(async () => ['/path/to/script.js'])
+mock.module('../lib/utils/collectMigrationScripts.js', {
+  namedExports: {
+    collectMigrationScripts: mockCollectMigrationScripts
+  }
+})
+
+const mockRunContentMigration = mock.fn(async ({ content }) => {
+  return content.map(item => ({
+    ...item,
+    title: item.title ? item.title + ' (migrated)' : item.title
+  }))
+})
+mock.module('../lib/utils/runContentMigration.js', {
+  namedExports: {
+    runContentMigration: mockRunContentMigration
+  }
+})
+
+mock.module('../lib/utils/log.js', {
+  namedExports: {
+    log: () => {}
+  }
+})
+
+const { migrateExistingCourses } = await import('../lib/utils/migrateExistingCourses.js')
+
+describe('migrateExistingCourses()', () => {
+  it('should collect migration scripts from frameworkDir', async () => {
+    mockCollectMigrationScripts.mock.resetCalls()
+    await migrateExistingCourses({
+      fromPlugins: [{ name: 'core', version: '1.0.0' }],
+      toPlugins: [{ name: 'core', version: '2.0.0' }],
+      frameworkDir: '/fw'
+    })
+    assert.equal(mockCollectMigrationScripts.mock.calls.length, 1)
+    assert.equal(mockCollectMigrationScripts.mock.calls[0].arguments[0], '/fw')
+  })
+
+  it('should query all courses when no courseIds provided', async () => {
+    mockContentModule.find.mock.resetCalls()
+    await migrateExistingCourses({
+      fromPlugins: [],
+      toPlugins: [],
+      frameworkDir: '/fw'
+    })
+    const findCalls = mockContentModule.find.mock.calls
+    assert.ok(findCalls.some(c =>
+      JSON.stringify(c.arguments[0]) === JSON.stringify({ _type: 'course' })
+    ))
+  })
+
+  it('should return migration result counts', async () => {
+    mockContentModule.find.mock.resetCalls()
+    mockContentModule.update.mock.resetCalls()
+    mockRunContentMigration.mock.resetCalls()
+    mockRunContentMigration.mock.mockImplementation(async ({ content }) => {
+      return content.map(item => ({
+        ...item,
+        title: item.title ? item.title + ' (migrated)' : item.title
+      }))
+    })
+    const result = await migrateExistingCourses({
+      fromPlugins: [{ name: 'core', version: '1.0.0' }],
+      toPlugins: [{ name: 'core', version: '2.0.0' }],
+      frameworkDir: '/fw'
+    })
+    assert.equal(result.migrated, 1)
+    assert.equal(result.failed, 0)
+    assert.deepEqual(result.errors, [])
+  })
+
+  it('should only update changed items in DB', async () => {
+    mockContentModule.update.mock.resetCalls()
+    mockRunContentMigration.mock.mockImplementation(async ({ content }) => {
+      return content.map(item => ({
+        ...item,
+        title: item.title ? item.title + ' (migrated)' : item.title
+      }))
+    })
+    await migrateExistingCourses({
+      fromPlugins: [],
+      toPlugins: [],
+      frameworkDir: '/fw'
+    })
+    assert.ok(mockContentModule.update.mock.calls.length > 0)
+  })
+
+  it('should skip DB writes when content is unchanged', async () => {
+    mockContentModule.update.mock.resetCalls()
+    mockRunContentMigration.mock.mockImplementation(async ({ content }) => content)
+    await migrateExistingCourses({
+      fromPlugins: [],
+      toPlugins: [],
+      frameworkDir: '/fw'
+    })
+    assert.equal(mockContentModule.update.mock.calls.length, 0)
+  })
+
+  it('should return early with zero counts when no scripts found', async () => {
+    mockCollectMigrationScripts.mock.mockImplementation(async () => [])
+    const result = await migrateExistingCourses({
+      fromPlugins: [],
+      toPlugins: [],
+      frameworkDir: '/fw'
+    })
+    assert.equal(result.migrated, 0)
+    assert.equal(result.failed, 0)
+    // restore
+    mockCollectMigrationScripts.mock.mockImplementation(async () => ['/path/to/script.js'])
+  })
+
+  it('should isolate per-course errors and continue', async () => {
+    mockContentModule.find.mock.mockImplementation(async (query) => {
+      if (query._type === 'course') {
+        return [
+          { _id: 'course1', _type: 'course', title: 'OK' },
+          { _id: 'course2', _type: 'course', title: 'Fails' }
+        ]
+      }
+      return []
+    })
+    let callCount = 0
+    mockRunContentMigration.mock.mockImplementation(async ({ content }) => {
+      callCount++
+      if (callCount === 2) throw new Error('migration error')
+      return content.map(item => ({ ...item, title: item.title + ' (migrated)' }))
+    })
+    const result = await migrateExistingCourses({
+      fromPlugins: [],
+      toPlugins: [],
+      frameworkDir: '/fw'
+    })
+    assert.equal(result.migrated, 1)
+    assert.equal(result.failed, 1)
+    assert.equal(result.errors.length, 1)
+    assert.equal(result.errors[0].courseId, 'course2')
+  })
+})

package/tests/utils-readFrameworkPluginVersions.spec.js

@@ -0,0 +1,48 @@
+import { describe, it, beforeEach, afterEach } from 'node:test'
+import assert from 'node:assert/strict'
+import fs from 'node:fs/promises'
+import path from 'node:path'
+import os from 'node:os'
+
+import { readFrameworkPluginVersions } from '../lib/utils/readFrameworkPluginVersions.js'
+
+describe('readFrameworkPluginVersions()', () => {
+  let tmpDir
+
+  beforeEach(async () => {
+    tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), 'fw-test-'))
+    const srcDir = path.join(tmpDir, 'src')
+    await fs.mkdir(path.join(srcDir, 'core'), { recursive: true })
+    await fs.mkdir(path.join(srcDir, 'components', 'adapt-contrib-text'), { recursive: true })
+    await fs.mkdir(path.join(srcDir, 'extensions', 'adapt-contrib-trickle'), { recursive: true })
+
+    await fs.writeFile(path.join(srcDir, 'core', 'bower.json'), JSON.stringify({ name: 'adapt-contrib-core', version: '6.24.1' }))
+    await fs.writeFile(path.join(srcDir, 'components', 'adapt-contrib-text', 'bower.json'), JSON.stringify({ name: 'adapt-contrib-text', version: '5.0.0' }))
+    await fs.writeFile(path.join(srcDir, 'extensions', 'adapt-contrib-trickle', 'bower.json'), JSON.stringify({ name: 'adapt-contrib-trickle', version: '4.2.1' }))
+  })
+
+  afterEach(async () => {
+    await fs.rm(tmpDir, { recursive: true })
+  })
+
+  it('should return plugin names and versions from bower.json files', async () => {
+    const plugins = await readFrameworkPluginVersions(tmpDir)
+    assert.equal(plugins.length, 3)
+    const names = plugins.map(p => p.name).sort()
+    assert.deepEqual(names, ['adapt-contrib-core', 'adapt-contrib-text', 'adapt-contrib-trickle'])
+  })
+
+  it('should return name and version for each plugin', async () => {
+    const plugins = await readFrameworkPluginVersions(tmpDir)
+    const core = plugins.find(p => p.name === 'adapt-contrib-core')
+    assert.equal(core.version, '6.24.1')
+  })
+
+  it('should return empty array when src dir has no bower files', async () => {
+    const emptyDir = await fs.mkdtemp(path.join(os.tmpdir(), 'fw-empty-'))
+    await fs.mkdir(path.join(emptyDir, 'src'), { recursive: true })
+    const plugins = await readFrameworkPluginVersions(emptyDir)
+    assert.deepEqual(plugins, [])
+    await fs.rm(emptyDir, { recursive: true })
+  })
+})