adapt-authoring-contentplugin 1.7.1 → 1.8.0

package/adapt-authoring.json

@@ -1,5 +1,8 @@
 {
   "documentation": {
-    "enable": true
+    "enable": true,
+    "manualPages": {
+      "content-plugins.md": "development"
+    }
   }
 }

package/docs/content-plugins.md

@@ -0,0 +1,183 @@
+# Content plugins
+
+`adapt-authoring-contentplugin` manages the **Adapt framework plugins** that ship
+inside built courses: components, extensions, menus and themes. These are the
+packages the Adapt framework installs and bundles at build time — *not* the
+authoring tool's front-end "UI plugins" (those live in a module's `ui/plugin.js`;
+content plugins are Adapt framework packages installed into the framework copy on
+disk).
+
+The module extends `AbstractApiModule`, so it inherits standard REST CRUD plus the
+access/hook machinery, and layers on framework install/update/uninstall, schema
+registration and on-disk backups.
+
+Source: `lib/ContentPluginModule.js`, `lib/utils/*`.
+
+## The model
+
+Each installed plugin is one document in the `contentplugins` collection
+(`schemaName = 'contentplugin'`, root `contentplugins`). Schema:
+`schema/contentplugin.schema.json`.
+
+| Field | Notes |
+| --- | --- |
+| `name` | Unique plugin name, e.g. `adapt-contrib-text` (unique index) |
+| `displayName` | User-friendly name (unique index) |
+| `version` | Installed semver |
+| `framework` | Compatible framework version range |
+| `type` | Plugin type, e.g. `component` / `extension` / `menu` / `theme` (indexed) |
+| `targetAttribute` | The content attribute the plugin binds to (required at install — see `CONTENTPLUGIN_ATTR_MISSING`) |
+| `isLocalInstall` | `true` when installed from an uploaded zip rather than the registry |
+| `isEnabled` | Default `true` |
+| `isAddedByDefault` | If `true`, auto-added to every new course's `_enabledPlugins` |
+| `pluginDependencies` | Plugin-to-version map |
+| `canBeUpdated`, `latestCompatibleVersion` | Read-only; populated on demand (see below) |
+
+`required`: `framework`, `name`, `type`, `version`, `isLocalInstall`.
+
+## Where plugins come from
+
+Two sources, distinguished by `isLocalInstall`:
+
+- **Registry / source string** — `versionOrPath` is a bare version or name
+  (no directory component), resolved by `adapt-cli` from the Adapt plugin
+  registry. `processPluginFiles` returns `isLocalInstall: false`.
+- **Local zip upload** — `versionOrPath` is a filesystem path to an unzipped
+  upload. `processPluginFiles` reads `package.json` (falling back to
+  `bower.json`), copies the files into the persistent `pluginDir`, and marks
+  `isLocalInstall: true`. A zip with neither manifest throws
+  `CONTENTPLUGIN_INVALID_ZIP`.
+
+The actual framework install/uninstall/update is always delegated to `adapt-cli`
+via `this.framework.runCliCommand(...)` (`installPlugins`, `uninstallPlugins`,
+`updatePlugins`, `getPluginUpdateInfos`). `init()` forces
+`ADAPT_ALLOW_PRERELEASE=true` for the CLI if unset.
+
+## Storage & versioning
+
+- Registry installs live inside the framework copy (managed by the CLI).
+- Local installs are copied into `pluginDir` (config `pluginDir`, default
+  `$DATA/contentplugins`).
+- Before a local install overwrites an existing plugin dir, the old one is
+  renamed to `<pluginPath>-v<version>` (`backupPluginVersion`). Only the single
+  most-recent backup is kept (`cleanupOldPluginBackups`); `getMostRecentBackup`
+  sorts `<name>-v*` dirs by semver.
+- DB version is kept in step with the framework copy by `syncPluginData`, which
+  is run on init and tapped into the framework's `postInstallHook` /
+  `postUpdateHook`. If a plugin recorded in the DB is missing from disk on boot,
+  `getMissingPlugins` re-installs it (from registry, or from the most recent
+  on-disk backup for local installs).
+
+## Schemas
+
+Content-plugin schemas (`$patch` extensions to content schemas) are registered
+with the `jsonschema` module by `processPluginSchemas`. Because `jsonschema`
+resets its registry on app-ready and only re-registers schemas owned by
+`app.dependencies`, this module tracks plugin schema paths in `this.pluginSchemas`
+and re-registers them via `jsonschema.registerSchemasHook`. `serveSchema` returns
+the built schema for a plugin via `GET /api/contentplugins/schema?type=<name>`.
+
+## The `_enabledPlugins` relationship
+
+A plugin is "used" by a course through the course's **config** document:
+`config._enabledPlugins` is an array of plugin `name`s. There is no per-course
+copy of the plugin — courses reference plugins by name.
+
+- New courses: `addDefaultPlugins` taps the content module's `preInsertHook`;
+  on a `config` insert it appends every plugin with `isAddedByDefault: true`
+  to `_enabledPlugins`.
+- `getPluginUses(_id)` aggregates the `content` collection for `config` docs
+  whose `_enabledPlugins` contains the plugin name, returning the owning courses
+  (title + creator email). It gates deletion and drives the `/uses` endpoint.
+
+## Endpoints
+
+Routes are declared explicitly (`routes.json`) to omit the default `POST /` and
+`PUT /:_id` — plugins are not created/edited as plain documents. Root:
+`/api/contentplugins`.
+
+| Method & route | Handler | Permission |
+| --- | --- | --- |
+| `GET /` | `requestHandler` | `read:contentplugins` |
+| `GET /:_id` | `requestHandler` | `read:contentplugins` |
+| `PATCH /:_id` | `requestHandler` | `write:contentplugins` |
+| `DELETE /:_id` | `requestHandler` (uninstall) | `write:contentplugins` |
+| `POST /query` | `queryHandler` | `read:contentplugins` |
+| `GET /schema` | `serveSchema` | `read:schema` |
+| `GET /readme` | `readmesHandler` | `read:contentplugins` |
+| `POST /install` | `installHandler` | `install:contentplugins` |
+| `POST /:_id/update` | `updateHandler` | `update:contentplugins` |
+| `GET /:_id/uses` | `usesHandler` | `read:contentplugins` |
+| `GET /:_id/readme` | `readmeHandler` | `read:contentplugins` |
+
+### Install
+
+`POST /api/contentplugins/install` accepts either JSON (`name`, `version`,
+`force`) or a multipart zip upload (parsed by the `middleware` module's
+`fileUploadParser`; the uploaded file path becomes `versionOrPath`). Install is
+`strict: true` from the HTTP path, so failures throw.
+
+```http
+POST /api/contentplugins/install
+Content-Type: application/json
+
+{ "name": "adapt-contrib-text", "version": "7.5.1", "force": false }
+```
+
+`installPlugin` flow: resolve/process the source files → if the plugin already
+exists and the new version is `<=` existing and `force` is false, throw
+`CONTENTPLUGIN_ALREADY_EXISTS` → CLI `installPlugins` → `insertOrUpdate` the DB
+record → register its schemas. Missing `targetAttribute` throws
+`CONTENTPLUGIN_ATTR_MISSING`.
+
+### Update
+
+`GET /?includeUpdateInfo=true` enriches results with `canBeUpdated` and
+`latestCompatibleVersion` (from the CLI `getPluginUpdateInfos`).
+`POST /api/contentplugins/:_id/update` runs the CLI `updatePlugins`, updates the
+DB record and schemas, then — if any courses use the plugin — calls
+`framework.migrateCourses({ fromPlugins, toPlugins, courseIds })` to migrate
+affected course content between the old and new plugin versions.
+
+### Uninstall
+
+`DELETE /api/contentplugins/:_id`. Blocked with `CONTENTPLUGIN_IN_USE` (listing
+the offending courses) if any course's `_enabledPlugins` references it.
+Otherwise deregisters the plugin's schemas, runs CLI `uninstallPlugins`, then
+deletes the DB record.
+
+### READMEs
+
+Each plugin ships a `README.md` in its framework source directory
+(`<frameworkDir>/src/{components,extensions,menu,theme}/<name>/README.md`).
+`getReadmes(name?)` reads them via `getPluginReadmes` and returns a
+`{ <pluginName>: <markdown> }` map.
+
+- `GET /api/contentplugins/readme` returns the map for every installed plugin
+  (plugins with no `README.md` are omitted).
+- `GET /api/contentplugins/:_id/readme` looks the plugin up by `_id` and returns
+  `{ name, readme }`, throwing `NOT_FOUND` if the plugin or its README is absent.
+
+## Backup & restore
+
+Backups are created automatically around local installs (above). Restore is
+available programmatically via `restorePluginFromBackup(pluginName)` — it renames
+the most-recent `<name>-v*` backup back into place and returns its manifest, or
+throws `NOT_FOUND` if no backup exists. There is no HTTP endpoint for restore; it
+is also used implicitly by `getMissingPlugins` on boot to recover a local plugin
+whose directory has gone missing.
+
+## Config
+
+| Option | Default | Notes |
+| --- | --- | --- |
+| `pluginDir` | `$DATA/contentplugins` | Location of locally installed plugins and their version backups |
+
+## Errors
+
+Defined in `errors/errors.json`. Notable: `CONTENTPLUGIN_ALREADY_EXISTS`,
+`CONTENTPLUGIN_IN_USE`, `CONTENTPLUGIN_INVALID_ZIP`, `CONTENTPLUGIN_ATTR_MISSING`,
+`CONTENTPLUGIN_CLI_INSTALL_FAILED`, `CONTENTPLUGIN_INSTALL_FAILED`,
+`CONTENTPLUGIN_INCOMPAT_FW`. (`CONTENTPLUGIN_ATTR_CLASH`,
+`CONTENTPLUGIN_NEWER_INSTALLED` and `CONTENTPLUGIN_VERSION_MISMATCH` are declared
+but not thrown from this module's code.)

package/lib/ContentPluginModule.js

@@ -9,7 +9,8 @@ import {
   getMostRecentBackup,
   cleanupOldPluginBackups,
   restorePluginFromBackup,
-  processPluginFiles
+  processPluginFiles,
+  getPluginReadmes
 } from './utils.js'
 import semver from 'semver'
 /**
@@ -293,6 +294,15 @@ class ContentPluginModule extends AbstractApiModule {
     ])).toArray()
   }
 
+  /**
+   * Retrieves the README contents of installed content plugins
+   * @param {String} [name] Limit the result to a single named plugin
+   * @returns {Promise<Object<string,string>>} Map of plugin name to README contents
+   */
+  async getReadmes (name) {
+    return getPluginReadmes(path.join(this.framework.path, 'src'), name)
+  }
+
   /**
    * Installs new plugins
    * @param {Array[]} plugins 2D array of strings in the format [pluginName, versionOrPath]
@@ -504,6 +514,42 @@ class ContentPluginModule extends AbstractApiModule {
       return next(error)
     }
   }
+
+  /**
+   * Express request handler for retrieving the README of every content plugin
+   * @param {external:ExpressRequest} req
+   * @param {external:ExpressResponse} res
+   * @param {Function} next
+   */
+  async readmesHandler (req, res, next) {
+    try {
+      res.send(await this.getReadmes())
+    } catch (error) {
+      return next(error)
+    }
+  }
+
+  /**
+   * Express request handler for retrieving the README of a single content plugin
+   * @param {external:ExpressRequest} req
+   * @param {external:ExpressResponse} res
+   * @param {Function} next
+   */
+  async readmeHandler (req, res, next) {
+    try {
+      const plugin = await this.findOne({ _id: req.params._id }, { strict: false })
+      if (!plugin) {
+        throw this.app.errors.NOT_FOUND.setData({ type: this.schemaName, id: req.params._id })
+      }
+      const readme = (await this.getReadmes(plugin.name))[plugin.name]
+      if (readme === undefined) {
+        throw this.app.errors.NOT_FOUND.setData({ type: 'README', id: plugin.name })
+      }
+      res.send({ name: plugin.name, readme })
+    } catch (error) {
+      return next(error)
+    }
+  }
 }
 
 export default ContentPluginModule

package/lib/utils/getPluginReadmes.js

@@ -0,0 +1,21 @@
+import fs from 'node:fs/promises'
+import path from 'node:path'
+import { globAbsolute } from './globAbsolute.js'
+
+const README_PATTERN = '{components,extensions,menu,theme}/*/README.md'
+
+/**
+ * Reads the README.md of installed content plugins from the framework src directory
+ * @param {String} srcDir The framework's src directory
+ * @param {String} [name] Limit the result to a single named plugin
+ * @returns {Promise<Object<string,string>>} Map of plugin name to README contents
+ */
+export async function getPluginReadmes (srcDir, name) {
+  const pattern = name ? `{components,extensions,menu,theme}/${name}/README.md` : README_PATTERN
+  const readmePaths = await globAbsolute(pattern, srcDir)
+  const entries = await Promise.all(readmePaths.map(async p => [
+    path.basename(path.dirname(p)),
+    await fs.readFile(p, 'utf8')
+  ]))
+  return Object.fromEntries(entries)
+}

package/lib/utils.js

@@ -1,6 +1,7 @@
 export { addDefaultPlugins } from './utils/addDefaultPlugins.js'
 export { backupPluginVersion } from './utils/backupPluginVersion.js'
 export { getMostRecentBackup } from './utils/getMostRecentBackup.js'
+export { getPluginReadmes } from './utils/getPluginReadmes.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.7.1",
+  "version": "1.8.0",
   "description": "Module for managing framework plugins",
   "homepage": "https://github.com/adapt-security/adapt-authoring-contentplugin",
   "repository": "github:adapt-security/adapt-authoring-contentplugin",

package/routes.json

@@ -12,6 +12,16 @@
       "handlers": { "get": "serveSchema" },
       "permissions": { "get": ["read:schema"] }
     },
+    {
+      "route": "/readme",
+      "handlers": { "get": "readmesHandler" },
+      "permissions": { "get": ["read:${scope}"] },
+      "meta": {
+        "get": {
+          "summary": "Return the README of every content plugin, keyed by plugin name"
+        }
+      }
+    },
     {
       "route": "/:_id",
       "handlers": { "get": "requestHandler", "patch": "requestHandler", "delete": "requestHandler" },
@@ -71,6 +81,17 @@
           "parameters": [{ "name": "_id", "in": "path", "description": "Content plugin _id", "required": true }]
         }
       }
+    },
+    {
+      "route": "/:_id/readme",
+      "handlers": { "get": "readmeHandler" },
+      "permissions": { "get": ["read:${scope}"] },
+      "meta": {
+        "get": {
+          "summary": "Return the README of a single content plugin",
+          "parameters": [{ "name": "_id", "in": "path", "description": "Content plugin _id", "required": true }]
+        }
+      }
     }
   ]
 }

package/tests/utils-getPluginReadmes.spec.js

@@ -0,0 +1,58 @@
+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 { getPluginReadmes } from '../lib/utils/getPluginReadmes.js'
+
+describe('getPluginReadmes()', () => {
+  let srcDir
+
+  const writePlugin = async (category, name, readme) => {
+    const dir = path.join(srcDir, category, name)
+    await fs.mkdir(dir, { recursive: true })
+    if (readme !== undefined) await fs.writeFile(path.join(dir, 'README.md'), readme)
+  }
+
+  beforeEach(async () => {
+    srcDir = await fs.mkdtemp(path.join(os.tmpdir(), 'readme-test-'))
+    await writePlugin('components', 'adapt-contrib-text', '# Text')
+    await writePlugin('extensions', 'adapt-contrib-spoor', '# Spoor')
+    await writePlugin('menu', 'adapt-contrib-boxMenu', '# Box Menu')
+    await writePlugin('theme', 'adapt-contrib-vanilla', '# Vanilla')
+  })
+
+  afterEach(async () => {
+    await fs.rm(srcDir, { recursive: true, force: true })
+  })
+
+  it('should return every plugin README keyed by plugin name', async () => {
+    const result = await getPluginReadmes(srcDir)
+    assert.deepEqual(result, {
+      'adapt-contrib-text': '# Text',
+      'adapt-contrib-spoor': '# Spoor',
+      'adapt-contrib-boxMenu': '# Box Menu',
+      'adapt-contrib-vanilla': '# Vanilla'
+    })
+  })
+
+  it('should limit the result to a single named plugin', async () => {
+    const result = await getPluginReadmes(srcDir, 'adapt-contrib-spoor')
+    assert.deepEqual(result, { 'adapt-contrib-spoor': '# Spoor' })
+  })
+
+  it('should return an empty object for an unknown plugin', async () => {
+    assert.deepEqual(await getPluginReadmes(srcDir, 'does-not-exist'), {})
+  })
+
+  it('should ignore plugins without a README and non-plugin directories', async () => {
+    await writePlugin('components', 'adapt-no-readme')
+    await fs.mkdir(path.join(srcDir, 'core'), { recursive: true })
+    await fs.writeFile(path.join(srcDir, 'core', 'README.md'), '# Core')
+
+    const result = await getPluginReadmes(srcDir)
+    assert.ok(!('adapt-no-readme' in result))
+    assert.ok(!('core' in result))
+  })
+})