adapt-authoring-content 2.0.3 → 2.0.4

package/.github/workflows/releases.yml

@@ -25,7 +25,7 @@ jobs:
       - name: Update npm
         run: npm install -g npm@latest
       - name: Install dependencies
-        run: npm install --legacy-peer-deps
+        run: npm install
       - name: Release
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

package/.github/workflows/standardjs.yml

@@ -8,5 +8,5 @@ jobs:
       - uses: actions/setup-node@master
         with:
           node-version: 'lts/*'
-      - run: npm install --legacy-peer-deps
+      - run: npm install
       - run: npx standard

package/.github/workflows/tests.yml

@@ -10,5 +10,5 @@ jobs:
       - uses: actions/setup-node@v4
         with:
           node-version: 'lts/*'
-      - run: npm install --legacy-peer-deps
+      - run: npm install
       - run: npm test

package/lib/ContentModule.js

@@ -71,7 +71,7 @@ class ContentModule extends AbstractApiModule {
     if (_type !== 'component') {
       return _type === 'page' || _type === 'menu' ? 'contentobject' : _type
     }
-    const [component] = await contentplugin.find({ name: _component }, { validate: false })
+    const component = await contentplugin.findOne({ name: _component }, { validate: false, strict: false })
     return component ? `${component.targetAttribute.slice(1)}-component` : defaultSchemaName
   }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "adapt-authoring-content",
-  "version": "2.0.3",
+  "version": "2.0.4",
   "description": "Module for managing Adapt content",
   "homepage": "https://github.com/adapt-security/adapt-authoring-content",
   "license": "GPL-3.0",
@@ -18,26 +18,9 @@
     "adapt-authoring-authored": "^1.1.1",
     "adapt-authoring-contentplugin": "^1.0.6",
     "adapt-authoring-jsonschema": "^1.2.0",
-    "adapt-authoring-mongodb": "^2.0.0",
+    "adapt-authoring-mongodb": "^1.1.3",
     "adapt-authoring-tags": "^1.0.2"
   },
-  "peerDependenciesMeta": {
-    "adapt-authoring-authored": {
-      "optional": true
-    },
-    "adapt-authoring-contentplugin": {
-      "optional": true
-    },
-    "adapt-authoring-jsonschema": {
-      "optional": true
-    },
-    "adapt-authoring-mongodb": {
-      "optional": true
-    },
-    "adapt-authoring-tags": {
-      "optional": true
-    }
-  },
   "devDependencies": {
     "@semantic-release/git": "^10.0.1",
     "conventional-changelog-eslint": "^6.0.0",

package/tests/ContentModule.spec.js

@@ -234,9 +234,8 @@ describe('ContentModule', () => {
 
     it('should look up a component plugin schema for _type "component"', async () => {
       const contentplugin = {
-        find: mock.fn(async () => [{
-          targetAttribute: '_myPlugin'
-        }])
+        find: mock.fn(async () => [{ targetAttribute: '_myPlugin' }]),
+        findOne: mock.fn(async () => ({ targetAttribute: '_myPlugin' }))
       }
       const getSchemaName = ContentModule.prototype.getSchemaName.bind({
         ...inst,
@@ -256,7 +255,8 @@ describe('ContentModule', () => {
 
     it('should fall back to default if component plugin is not found', async () => {
       const contentplugin = {
-        find: mock.fn(async () => [])
+        find: mock.fn(async () => []),
+        findOne: mock.fn(async () => undefined)
       }
       const getSchemaName = ContentModule.prototype.getSchemaName.bind({
         ...inst,

package/AUDIT.md

@@ -1,205 +0,0 @@
-# ContentModule.js Audit — General Improvements
-
-Date: 2026-02-19
-
-## Performance
-
-### 1. `updateSortOrder()` fires on every insert and update (Lines 117, 127)
-Each call fetches all siblings, then issues an `update` for every sibling whose sort order changed. On an article with 20 blocks, that's 20+ DB calls per insert/update.
-
-**Suggestion:** Only update sort order when `_sortOrder` or `_parentId` has actually changed in the update data. Currently line 127 always calls it regardless. Additionally, the missing `return` on line 299 means the `super.update` promises are not awaited — see bug #1 below.
-
-### 2. `updateEnabledPlugins()` fires on every insert and update unconditionally (Lines 118, 128)
-This method fetches the `contentplugin` module, all content items for the course, all extensions, and potentially updates every content item of affected types. This is heavy for routine edits that don't change components.
-
-**Suggestion:** Two changes: (1) Guard with a check — only run on insert/delete of components or when `_component`, `_menu`, `_theme`, or `_enabledPlugins` fields are being modified. (2) Accept an optional `ContentTree` parameter so callers that already have a tree (e.g. `delete`, `clone`) don't trigger a redundant full-course fetch.
-
-### 3. `getSchemaName()` awaits `waitForModule('contentplugin')` on every call (Line 56)
-`waitForModule` is called every time, even though the module reference never changes after init.
-
-**Suggestion:** Cache the module references obtained in `init()` as instance properties (e.g. `this.contentplugin`, `this.jsonschema`, etc.) and reuse them throughout the class. This applies to all the `waitForModule` calls scattered across methods (lines 56, 79, 83, 104, 311).
-
-### 4. `getSchema()` disables cache (`useCache: false`) on every call (Line 95)
-This forces re-computation of the schema on every request.
-
-**Suggestion:** Investigate whether caching can be enabled for schemas within a course context (keyed by `schemaName + courseId + enabledPlugins hash`).
-
-### 5. `getSchema()` may fetch the same document twice (Lines 81, 84-85)
-`getSchemaName(data)` at line 81 may call `this.find({ _id })` internally (line 61), and then line 84-85 may call `this.find({ _id: data._id })` again if `_courseId` is missing.
-
-**Suggestion:** Pass the document fetched in `getSchemaName` back through the call chain to avoid the redundant query.
-
-### 6. `enabledPluginSchemas` uses quadratic `.reduce` with spread (Line 91)
-```js
-pluginList.reduce((m, p) => [...m, ...contentplugin.getPluginSchemas(p)], [])
-```
-This creates a new array on every iteration via spread, giving O(n²) behavior.
-
-**Suggestion:** Use `flatMap`:
-```js
-pluginList.flatMap(p => contentplugin.getPluginSchemas(p))
-```
-
-## Bugs / Correctness
-
-### 1. Missing `return` in `updateSortOrder` — promises not awaited (Line 299)
-```js
-if (s._sortOrder !== _sortOrder) super.update({ _id: s._id }, { _sortOrder })
-```
-The `super.update()` call is missing a `return`. The `async` map callback resolves immediately with `undefined`, and the updates run as fire-and-forget. If any update fails, the error is silently swallowed as an unhandled rejection.
-
-**Fix:** Add `return` before `super.update(...)`.
-
-### 2. `clone()` accesses `._type` on a null document (Line 241)
-```js
-if (!originalDoc) {
-  throw this.app.errors.NOT_FOUND.setData({ type: originalDoc?._type, id: _id })
-}
-```
-If `originalDoc` is falsy, `originalDoc?._type` evaluates to `undefined`, so the error data will always have `type: undefined`. This isn't a crash (thanks to optional chaining), but the error message is unhelpful.
-
-**Fix:** Provide a meaningful fallback: `{ type: 'content', id: _id }`.
-
-### 3. `delete()` calls `this.setDefaultOptions(options)` but `options` may be `undefined` (Line 135)
-Unlike other overrides, `delete()` doesn't default `options` to `{}` in its signature. If called internally without options, `this.setDefaultOptions(undefined)` could behave unexpectedly (Lodash `_.defaults` on `undefined` returns `undefined`).
-
-**Fix:** Add `options = {}` default parameter, consistent with the parent class.
-
-### 4. `insertRecursive` doesn't handle missing parent gracefully (Line 203)
-```js
-parent = (await this.find({ _id: rootId }))[0]
-```
-If `rootId` is provided but no document is found, `parent` is `undefined`. The code continues into the `for` loop where `parent._type` (line 207) will throw an untyped `TypeError` rather than a proper API error.
-
-**Fix:** Add a check after the find: `if (!parent) throw this.app.errors.NOT_FOUND.setData(...)`.
-
-### 5. `updateSortOrder` splice logic may be incorrect for new items (Line 294)
-```js
-const newSO = item._sortOrder - 1 > -1 ? item._sortOrder - 1 : siblings.length
-```
-For a newly inserted item, `item._sortOrder` may be `undefined` (not yet set), making `undefined - 1 > -1` evaluate to `false`, which defaults to `siblings.length`. This works by accident (appends to end), but is fragile and unclear.
-
-**Fix:** Explicitly handle the `undefined` case: `const newSO = item._sortOrder != null ? item._sortOrder - 1 : siblings.length`.
-
-### 6. `INVALID_PARENT` error uses HTTP 500 (errors.json line 7)
-A missing or invalid parent ID is a client error, not a server error.
-
-**Fix:** Change `statusCode` to `400` (Bad Request).
-
-## Reliability / Error Handling
-
-### 7. `clone()` has no rollback on failure (Lines 237-279)
-Unlike `insertRecursive` (which has a try/catch with cleanup), `clone()` has no rollback. If cloning fails partway through a recursive tree, orphaned partially-cloned documents are left in the database.
-
-**Suggestion:** Wrap the clone operation in a try/catch that cleans up any documents created during the operation, similar to the pattern in `insertRecursive`.
-
-### 8. Silent error swallowing in `getSchema` (Lines 82, 92)
-```js
-try { schemaName = await this.getSchemaName(data) } catch (e) {}
-```
-and
-```js
-try { ... } catch (e) {}
-```
-These silently swallow all errors, including genuine failures (DB connection issues, permission errors). A schema resolution failure will silently fall back to a less specific schema, potentially allowing invalid data through validation.
-
-**Suggestion:** At minimum, log the error. Better: only catch expected error types.
-
-### 9. `clone()` course workaround is fragile (Lines 262-270)
-The comment explains that config doesn't exist when the course is created, so schema validation strips plugin data, and a second update restores it. This double-write pattern means:
-- If the second `update` fails, the course is left with stripped configuration
-- The `payload` object is mutated (`delete payload._id`, `delete payload._courseId`) after being passed to `insert`, which could cause subtle issues if `insert` stored a reference
-
-**Suggestion:** Consider inserting the config first (or in the same transaction), then creating the course with full data. Or use `{ validate: false }` for the initial course insert to preserve all fields.
-
-### 10. No input validation on `handleClone` body (Line 377)
-The `_id` and `_parentId` are destructured directly from `req.body` with no validation that `_id` is present or is a valid ObjectId.
-
-**Suggestion:** Validate required fields before proceeding.
-
-## Code Quality
-
-### 11. Inconsistent use of `this.find` vs `super.find` vs `this.findOne`
-- `handleClone` uses `this.findOne` (line 378), but `clone` uses `this.find` and destructures (line 238)
-- `updateEnabledPlugins` uses `super.find` (line 349) while other methods use `this.find`
-- The distinction matters: `this.find` goes through schema validation/access checks; `super.find` bypasses them
-
-**Suggestion:** Document the intent clearly, and be consistent about when validation/hooks should be bypassed.
-
-### 12. `clone()` line 265 mutates `payload` after `insert`
-`delete payload._id` and `delete payload._courseId` mutate the object after it was already used as insert data. While likely harmless, mutation of shared objects is error-prone.
-
-**Suggestion:** Create a separate object for the update: `const updatePayload = { ...payload }; delete updatePayload._id; ...`
-
-### 13. Missing `UNKNOWN_SCHEMA_NAME` usage
-The error is defined in `errors.json` but never thrown anywhere in the code.
-
-**Suggestion:** Either use it where appropriate (e.g., in `getSchemaName` when no schema is resolved) or remove it.
-
-## Summary — Priority Order
-
-| Priority | Issue | Category |
-|----------|-------|----------|
-| **High** | Missing `return` in `updateSortOrder` — fire-and-forget DB writes | Bug |
-| **High** | No rollback in `clone()` leaves orphaned data on failure | Reliability |
-| **High** | Silent error swallowing in `getSchema` | Reliability |
-| **Medium** | `updateSortOrder`/`updateEnabledPlugins` fire unconditionally | Performance |
-| **Medium** | `delete()` missing default `options = {}` parameter | Bug |
-| **Medium** | `insertRecursive` no check for missing parent | Bug |
-| **Medium** | `INVALID_PARENT` should be 400 not 500 | Correctness |
-| **Medium** | `waitForModule` called repeatedly instead of caching refs | Performance |
-| **Low** | Quadratic `.reduce` with spread in `getSchema` | Performance |
-| **Low** | `clone()` error message has `type: undefined` | Correctness |
-| **Low** | No input validation on `handleClone` body | Reliability |
-| **Low** | Unused `UNKNOWN_SCHEMA_NAME` error definition | Code quality |
-
----
-
-## MongoDB Projections
-
-### Infrastructure
-
-Projections are fully supported through the existing stack. The `mongoOptions` (third argument) to `find`/`findOne` is passed through `AbstractApiModule` → `DataCache` → `MongoDBModule` → native MongoDB driver unchanged. The `projection` key is a standard MongoDB `FindOptions` field.
-
-Usage pattern:
-```js
-this.find({ _id }, { validate: false }, { projection: { _type: 1, _component: 1 } })
-```
-
-There is one existing use in the codebase (`RolesModule`) confirming this works in practice. The `DataCache` key includes `mongoOptions` in its hash, so projected and non-projected results are cached separately.
-
-### Call-site analysis
-
-| Line | Method | Fields returned | Fields used | Minimal projection | Safe? | Impact |
-|------|--------|----------------|-------------|-------------------|-------|--------|
-| 61 | `getSchemaName` | ~30+ | `_type`, `_component` | `{ _type: 1, _component: 1 }` | Yes | High — called on every write |
-| 85 | `getSchema` | ~30+ | `_courseId` | `{ _courseId: 1 }` | Yes | High — called on every write |
-| 89 | `getSchema` (config) | ~30+ | `_enabledPlugins` | `{ _enabledPlugins: 1 }` | Yes | High — config docs are large |
-| 137 | `delete` | ~30+ | All (HTTP response) | None | N/A | Cannot project |
-| 160 | `getDescendants` | ~30+ | All (HTTP response) | None | N/A | Cannot project (results returned to caller) |
-| 238 | `clone` (original) | ~30+ | All (spread into clone) | None | N/A | Cannot project |
-| 245 | `clone` (parent) | ~30+ | `_id`, `_type`, `_courseId` | `{ _id: 1, _type: 1, _courseId: 1 }` | Yes | Medium |
-| 263 | `clone` (config) | ~30+ | `_id` only | `{ _id: 1 }` | Yes | High — config is large, re-fetched in recursive call |
-| 272 | `clone` (children) | ~30+ | `_id` only | `{ _id: 1 }` | Yes | High — called per tree level, full docs wasted |
-| 292 | `updateSortOrder` | ~30+ | `_id`, `_sortOrder` | `{ _id: 1, _sortOrder: 1 }` | Yes | High — called on every insert/update |
-| 312 | `updateEnabledPlugins` | ~30+ | `_id`, `_type`, `_component`, `_enabledPlugins`, `_menu`, `_theme` | `{ _id:1, _type:1, _component:1, _enabledPlugins:1, _menu:1, _theme:1 }` | Yes | **Highest** — fetches entire course on every insert/update |
-| 318 | `contentplugin.find` | ~15+ | `name` | `{ _id: 0, name: 1 }` | Yes | High — called on every insert/update |
-| 349 | `super.find` (types to update) | ~30+ | `_id` only | `{ _id: 1 }` | Yes | High — `super.update` re-fetches internally |
-
-### Hook safety
-
-None of the projectable call sites pass their results to hooks. All hook observers (`authored`, `multilang`, `spoortracking`, `defaultplugins`, `courseassets`) receive documents from separate internal fetches within `super.insert`/`super.update`/`super.delete`, which always fetch full documents. Applying projections to the call sites above will not break any hook contract.
-
-### Highest-impact projections
-
-**1. `updateEnabledPlugins` line 312** — fetches every content item in the course to extract component names and config plugin list. Only 6 fields needed from each document. For a 100-item course, this could reduce data transfer from ~200KB to ~10KB. Called on every single insert and update.
-
-**2. `updateSortOrder` line 292** — fetches all siblings to compare `_sortOrder` values. Only needs `_id` and `_sortOrder`. Called on every insert and update.
-
-**3. `getSchema` lines 61, 85, 89** — called on every write request. Three separate finds that each return full documents when only 1-2 fields are needed.
-
-**4. `clone` children query line 272** — fetches full documents for all children at each tree level, but only uses `_id` to pass to the next recursive call. With `ContentTree`, this is eliminated entirely; without it, a projection to `{ _id: 1 }` would still help significantly.
-
-### Recommendation
-
-Apply projections to all "Safe: Yes" call sites above. The changes are mechanical — adding a third argument to each `find` call — and carry zero risk since no hooks or return values are affected. The `updateEnabledPlugins` projection alone would meaningfully reduce the data flowing through the most frequently executed code path.

package/CONTENT_TREE_PROPOSAL.md

@@ -1,506 +0,0 @@
-# ContentTree Proposal
-
-Date: 2026-02-19
-
-## Related Audit Issues
-
-These issues from the ContentModule.js audit are directly addressed or enabled by the ContentTree abstraction.
-
-### `getDescendants()` full course fetch and O(n²) traversal (Lines 160-166)
-`getDescendants()` calls `this.find({ _courseId })` which loads every content item in the course into memory, then walks the tree using nested `reduce`/`filter` with spread — O(n²) for both the scan and array allocation.
-
-**Suggestion:** Replace the body with `ContentTree` (see proposal below). The full-course fetch is still needed, but the in-memory traversal drops from O(n²) to O(n) via the `byParent` Map. The `ContentTree` instance can also be shared with callers (`delete`, `clone`) to avoid redundant fetches.
-
-### `delete()` issues N+1 individual delete calls (Lines 144-146)
-Each descendant is deleted with a separate `super.delete({ _id })` call, each of which internally does a `find` then a `delete` in MongoDB. For a course with 200 items, that's ~400 DB round-trips.
-
-**Suggestion:** Use `super.deleteMany({ _id: { $in: ids } })` if hook invocation per item isn't needed, or at minimum batch the MongoDB operations. A `ContentTree` built once in `delete()` can provide the full descendant ID list for `deleteMany`, and the same tree instance can be passed to `updateEnabledPlugins` and `updateSortOrder` to avoid their own fetches.
-
-### `clone()` issues N+1 DB queries and double-fetches the source document (Lines 238, 272, 378)
-`handleClone` calls `this.findOne({ _id })` for access checking (line 378), then `clone()` calls `this.find({ _id })` again (line 238). The recursive clone loop then issues one `find({ _parentId })` query per tree depth level (line 272).
-
-**Suggestion:** Refactor `clone` to accept a pre-built `ContentTree`. The handler fetches the full course once, performs the access check against it, and the recursive loop uses `tree.getChildren(id)` instead of DB queries. This eliminates both the double-fetch and the N+1 pattern in a single change.
-
-### Priority summary
-
-| Priority | Issue | Category |
-|----------|-------|----------|
-| **High** | `delete()` N+1 individual deletes — O(n) DB round-trips | Performance |
-| **High** | `clone()` N+1 queries + double-fetch | Performance |
-| **Medium** | `getDescendants` O(n²) traversal | Performance |
-
----
-
-## Deep Dive: Clone Operation
-
-### DB query count for a typical course clone
-
-Tested against a representative course structure: 1 course + 1 config + 2 pages + 4 articles + 8 blocks + 16 components = **32 items**.
-
-Every `this.find()` hits MongoDB directly — the content module's `DataCache` is disabled (`enableCache` is not set in config).
-
-#### What happens per cloned item
-
-Each item cloned through `this.insert()` triggers a cascade of operations:
-
-| Operation | DB reads | DB writes | Notes |
-|-----------|----------|-----------|-------|
-| `super.insert` → `mongodb.insert` | 0 | 1 | The actual write |
-| `super.insert` → `validate` → `getSchema` | 1-2 | 0 | Fetches config for `_enabledPlugins`; components also fetch `contentplugin` for schema name |
-| `preInsertHook` → authored `updateCourseTimestamp` | 1 | 1 | Reads config, writes `updatedAt` to it — **every single insert** |
-| `preInsertHook` → spoor `insertTrackingId` | 0-1 | 0 | 1 read for blocks only (finds max `_trackingId`) |
-| `preInsertHook` → defaultplugins | 0-1 | 0 | 1 read for config only |
-| `postInsertHook` → multilang lookup | 1 | 0 | Checks multilang collection, exits for non-multilang courses |
-| `updateSortOrder` | 1 | 0 | Reads siblings; 0 writes during clone (sort order preserved from original) |
-| `updateEnabledPlugins` | 2 | 0 | Reads all course content + all extensions; early-exits when plugin list unchanged |
-| `postCloneHook` → multilang lookup | 1 | 0 | Same as postInsertHook |
-| **Total per non-course, non-config item** | **~10-12** | **~2** | |
-
-Additional overhead for the course item itself: `this.update({ _id, _courseId })` to self-assign `_courseId` (adds ~7 reads, 2 writes). After config clone, another `this.update` restores plugin config data (~6 reads, 2 writes).
-
-#### Total DB operations for a 32-item course clone
-
-| Phase | Reads | Writes |
-|-------|-------|--------|
-| `handleClone`: access check `findOne` | 1 | 0 |
-| Course clone: find + insert + self-update | 8 | 2 |
-| Config clone: find + insert + hooks | 9 | 1 |
-| Course update to restore plugin config | 6 | 2 |
-| Find children at each level (5 levels) | 5 | 0 |
-| 2 pages × ~10 reads, 2 writes | 20 | 4 |
-| 4 articles × ~10 reads, 2 writes | 40 | 8 |
-| 8 blocks × ~11 reads, 2 writes | 88 | 16 |
-| 16 components × ~12 reads, 2 writes | 192 | 32 |
-| **Total** | **~369** | **~65** |
-
-**~434 total DB operations to clone a 32-item course.**
-
-For a realistic production course (100-200 items), this scales to **1,000-3,000 DB operations**.
-
-### Optimisation opportunities
-
-Listed in order of estimated impact:
-
-#### 1. Disable `updateEnabledPlugins` during clone — save ~62 reads
-
-`ContentModule.insert` already has the option infrastructure:
-```js
-options.updateEnabledPlugins !== false && this.updateEnabledPlugins(doc)
-```
-The clone method just needs to pass the option:
-```js
-const newData = await this.insert(payload, { schemaName, updateEnabledPlugins: false })
-```
-Then run `updateEnabledPlugins` once at the end of the top-level clone. **Two-line fix.**
-
-#### 2. Disable `updateSortOrder` during clone — save ~30 reads
-
-Same pattern:
-```js
-const newData = await this.insert(payload, { schemaName, updateSortOrder: false })
-```
-Cloned items already carry the correct `_sortOrder` from the original. No recalculation needed.
-
-#### 3. Pass parent doc through recursion — save ~30 reads
-
-Currently each recursive `clone()` call does `this.find({ _id: _parentId })` just to read `_type` and `_courseId`. The parent is already known at the call site:
-```js
-// Current (line 273-275)
-for (let i = 0; i < children.length; i++) {
-  await this.clone(userId, children[i]._id, newData._id)
-}
-
-// Proposed: pass newData as parent
-for (let i = 0; i < children.length; i++) {
-  await this.clone(userId, children[i]._id, newData._id, {}, { parent: newData })
-}
-```
-
-#### 4. Use ContentTree to eliminate per-level child queries — save ~5 reads per level
-
-Pre-fetch the entire source course once, build a tree, and use `tree.getChildren(originalId)` instead of `this.find({ _parentId })` at each recursion level. Combined with passing parent docs (#3), this eliminates all read-only `find` calls within the recursive loop.
-
-#### 5. Parallelise sibling clones — ~4-5x wall-clock improvement
-
-The sequential `for` loop (line 273) can safely be replaced with `Promise.all`:
-```js
-const children = tree.getChildren(_id)
-await Promise.all(children.map(child =>
-  this.clone(userId, child._id, newData._id, {}, { parent: newData, tree })
-))
-```
-
-Sibling subtrees are independent — they write to different documents with different `_id` values. The only shared state is `updateEnabledPlugins` (which writes to config), but with that disabled during clone (#1 above), there are no write conflicts.
-
-For a 5-level course, this changes wall-clock time from O(N × depth) to O(depth), as all siblings at each level clone in parallel.
-
-#### 6. Skip schema validation during clone — save ~32 reads + CPU
-
-Every `super.insert` runs `this.validate()` → `getSchema()` → fetches config for `_enabledPlugins` filtering. The data being cloned was already valid in the original course.
-
-Pass `{ validate: false }` to the insert options during clone. This saves 1-2 DB reads per item (the config and contentplugin lookups in `getSchema`) and all the CPU cost of schema compilation with `useCache: false`.
-
-**Risk:** If `customData` is passed to `clone()` (e.g. from the API handler), skipping validation could allow bad data through. Mitigate by only skipping validation for recursive child clones (not the root item).
-
-#### 7. Batch or skip `updateCourseTimestamp` during clone — save ~60 reads + 60 writes
-
-The authored module's `preInsertHook` updates the course config's `updatedAt` on every single insert. During a 32-item clone, the config timestamp is written 32 times to values ~1ms apart — 31 are wasted.
-
-Options:
-- Add an `options.skipTimestamp` flag to the authored module
-- Or set the timestamp once at the end of the top-level clone
-- Or accept it as an architectural cost of the hook system (least disruptive)
-
-#### 8. Use projections for read-only lookups during clone — save ~30-50% data transfer
-
-Several `find` calls in the clone path return full documents when only a few fields are needed. See the MongoDB Projections section in the general audit for specific call sites. The highest-impact projection during clone is the children query (line 272): currently fetches full documents but only uses `_id`.
-
-### Projected savings summary
-
-| Optimisation | Reads saved | Writes saved | Complexity |
-|-------------|-------------|-------------|------------|
-| Disable `updateEnabledPlugins` during clone | ~62 | 0 | Two-line fix |
-| Disable `updateSortOrder` during clone | ~30 | 0 | Two-line fix |
-| Pass parent doc through recursion | ~30 | 0 | Signature change |
-| ContentTree for child lookups | ~5 | 0 | Moderate refactor |
-| Parallelise sibling clones | 0 (wall-clock only) | 0 | Small refactor |
-| Skip validation for child clones | ~32 | 0 | Option pass-through |
-| Batch/skip `updateCourseTimestamp` | ~30 | ~30 | Cross-module change |
-| **Total** | **~189** | **~30** | |
-
-**Current: ~434 DB ops. After all optimisations: ~215 DB ops (~50% reduction) with ~4-5x wall-clock improvement from parallelism.**
-
-The theoretical minimum (one bulk read + N inserts + one config update) is ~34 ops, but reaching that would require bypassing the hook system entirely, which would break authored timestamps, multilang, spoor tracking, and courseassets.
-
----
-
-## Proposal: ContentTree Abstraction
-
-### Problem
-
-The content hierarchy (course -> page/menu -> article -> block -> component, plus config) is stored as a flat MongoDB collection with `_parentId` references. Multiple operations need to traverse or query this tree, but there is no shared abstraction — each caller re-implements tree walking with ad-hoc loops, filters, and repeated DB fetches.
-
-Key pain points across the codebase:
-
-| Operation | Current approach | DB cost |
-|-----------|-----------------|---------|
-| `getDescendants` (delete) | Full course fetch, BFS in JS with O(n²) filter loop | 1 full-course query, quadratic in-memory scan |
-| `clone` recursion | One `find({ _parentId })` per tree level, sequential | N+1 queries (one per depth level) |
-| `updateEnabledPlugins` | Full course fetch to scan component types | 1 full-course query per insert/update/delete |
-| `AdaptFrameworkBuild.sortContentItems` | Walks `_parentId` chain per item to build sort string | 0 extra (already loaded), but O(n×d) where d=depth |
-| `AdaptFrameworkImport.getSortedData` | Builds adjacency list, BFS level-sort | 0 extra (already loaded) |
-| Frontend `useProjectContent` + `buildTree` | Bulk fetch all content, build tree client-side with Map | 0 (client-side after initial load) |
-
-The import module (`AdaptFrameworkImport.getSortedData`) is the only place in the codebase that constructs a proper adjacency-list tree structure. Everywhere else, the tree is walked by scanning flat arrays.
-
-### Proposal
-
-Introduce a `ContentTree` utility class that takes a flat array of content items (from a single course) and provides efficient tree operations. This would be a pure data structure — no DB access — so it can be used both after a single `find({ _courseId })` call on the backend and potentially on the frontend too.
-
-```js
-class ContentTree {
-  constructor (items) {
-    this.items = items
-    this.byId = new Map()            // _id -> item
-    this.byParent = new Map()        // _parentId -> [children]
-    this.byType = new Map()          // _type -> [items]
-    this.course = null
-    this.config = null
-
-    for (const item of items) {
-      const id = item._id.toString()
-      this.byId.set(id, item)
-
-      const parentId = item._parentId?.toString()
-      if (parentId) {
-        if (!this.byParent.has(parentId)) this.byParent.set(parentId, [])
-        this.byParent.get(parentId).push(item)
-      }
-
-      const type = item._type
-      if (!this.byType.has(type)) this.byType.set(type, [])
-      this.byType.get(type).push(item)
-
-      if (type === 'course') this.course = item
-      if (type === 'config') this.config = item
-    }
-  }
-
-  // O(1) lookup
-  getById (id) {
-    return this.byId.get(id.toString())
-  }
-
-  // O(1) children lookup (already sorted by _sortOrder if source was sorted)
-  getChildren (parentId) {
-    return this.byParent.get(parentId.toString()) ?? []
-  }
-
-  // O(1) type lookup
-  getByType (type) {
-    return this.byType.get(type) ?? []
-  }
-
-  // O(n) where n = number of descendants (not total course size)
-  getDescendants (rootId) {
-    const descendants = []
-    const queue = [rootId.toString()]
-    while (queue.length) {
-      const children = this.byParent.get(queue.shift()) ?? []
-      for (const child of children) {
-        descendants.push(child)
-        queue.push(child._id.toString())
-      }
-    }
-    return descendants
-  }
-
-  // O(d) where d = depth
-  getAncestors (itemId) {
-    const ancestors = []
-    let current = this.byId.get(itemId.toString())
-    while (current?._parentId) {
-      current = this.byId.get(current._parentId.toString())
-      if (current) ancestors.push(current)
-    }
-    return ancestors
-  }
-
-  // O(1)
-  getSiblings (itemId) {
-    const item = this.byId.get(itemId.toString())
-    if (!item?._parentId) return []
-    return this.getChildren(item._parentId).filter(c => c._id.toString() !== itemId.toString())
-  }
-
-  // O(1) — all components across the course
-  getComponentNames () {
-    return [...new Set(this.getByType('component').map(c => c._component))]
-  }
-}
-```
-
-### Impact on existing code
-
-**`getDescendants` (ContentModule.js:159-173)** — currently fetches the full course and does O(n²) BFS. Would become:
-```js
-async getDescendants (rootItem) {
-  const items = await this.find({ _courseId: rootItem._courseId })
-  const tree = new ContentTree(items)
-  const descendants = tree.getDescendants(rootItem._id)
-  if (rootItem._type === 'course' && tree.config) {
-    descendants.push(tree.config)
-  }
-  return descendants
-}
-```
-Still one full-course fetch, but the in-memory traversal drops from O(n²) to O(n).
-
-**`clone` (ContentModule.js:237-279)** — currently issues one `find({ _parentId })` query per depth level. Could pre-fetch the subtree once:
-```js
-const items = await this.find({ _courseId: originalDoc._courseId })
-const tree = new ContentTree(items)
-// then use tree.getChildren(id) in the recursive loop instead of this.find({ _parentId })
-```
-This eliminates N+1 DB queries down to 1.
-
-**`updateEnabledPlugins` (ContentModule.js:310-352)** — currently fetches the full course to scan for component types. Could accept a pre-built tree or build one:
-```js
-const tree = new ContentTree(await this.find({ _courseId }))
-const componentNames = tree.getComponentNames()
-const config = tree.config
-```
-Same DB cost but cleaner code, and the tree could be passed from the caller if already available.
-
-**`delete` (ContentModule.js:134-152)** — the biggest win from tree sharing. Currently `getDescendants`, `updateEnabledPlugins`, and `updateSortOrder` each fetch data independently. With a tree:
-```js
-async delete (query, options = {}, mongoOptions) {
-  this.setDefaultOptions(options)
-  const [targetDoc] = await this.find(query)
-  if (!targetDoc) {
-    throw this.app.errors.NOT_FOUND.setData({ type: options.schemaName, id: JSON.stringify(query) })
-  }
-  const items = await this.find({ _courseId: targetDoc._courseId })
-  const tree = new ContentTree(items)
-  const descendants = tree.getDescendants(targetDoc._id)
-  if (targetDoc._type === 'course' && tree.config) descendants.push(tree.config)
-  // single deleteMany instead of N individual deletes
-  await super.deleteMany({ _id: { $in: [...descendants, targetDoc].map(d => d._id) } })
-  // pass tree to avoid redundant fetches
-  await Promise.all([
-    this.updateEnabledPlugins(targetDoc, { tree }),
-    this.updateSortOrder(targetDoc)
-  ])
-  return [targetDoc, ...descendants]
-}
-```
-This reduces the delete path from ~2N+2 DB queries to ~3 (find target, find course, deleteMany).
-
-**`AdaptFrameworkBuild.sortContentItems` (AdaptFrameworkBuild.js:335-354)** — currently builds a sort-order string by walking `_parentId` chain per item. Could use `tree.getAncestors()` for clarity, though the performance difference is marginal since it's already in-memory.
-
-**`AdaptFrameworkImport.getSortedData` (AdaptFrameworkImport.js:734-753)** — already builds its own adjacency list. Could be replaced by `ContentTree` directly, consolidating the only existing tree-building code.
-
-### What this does NOT replace
-
-- DB queries themselves — `ContentTree` is a post-query optimisation, not a cache layer
-- Schema resolution logic — that has its own concerns beyond tree structure
-
-Note: the frontend (adapt-authoring-ui2) already implements its own `buildTree()` function in `useProjectContent.js` that constructs a nearly identical data structure (Map + nested children arrays) from the flat API response. A shared `ContentTree` class could potentially be used on both sides, or the server could return the tree pre-built via a dedicated endpoint (see Tree API Endpoint below).
-
-### Trade-offs
-
-**For:**
-- Eliminates the N+1 query pattern in `clone` (biggest performance win)
-- Replaces O(n²) in-memory scans with O(n) lookups via Maps
-- Single place to encode tree semantics (parent-child, type hierarchy, config special-casing)
-- Reusable across `delete`, `clone`, `updateEnabledPlugins`, and framework build/import
-- Pure data structure with no side effects — easy to test
-- Enables tree sharing within a single request (e.g. `delete` builds the tree once and passes it to `updateEnabledPlugins`, eliminating 1-2 redundant full-course fetches per operation)
-
-**Against:**
-- Adds a new abstraction to a small module (currently just 2 files in `lib/`)
-- The tree is a snapshot — it goes stale if content is modified between construction and use (relevant during `clone` which inserts as it traverses)
-- Some operations (like `updateSortOrder`) only need siblings, not the full tree — fetching the full course to build a tree may be overkill for targeted queries
-- Risk of over-engineering if the module doesn't grow further
-
-### Recommendation
-
-**Worth implementing**, primarily for the `clone` N+1 elimination and `getDescendants` O(n²) fix. These are the two highest-impact changes and both become straightforward with a tree abstraction. The class itself is ~50 lines with no dependencies, so the abstraction cost is low.
-
-Start with `getDescendants` and `clone` as the first consumers. Extend to `delete` (for tree sharing with `updateEnabledPlugins`) and the framework build/import only if those methods are being refactored anyway.
-
----
-
-## Tree API Endpoint
-
-### Current frontend architecture (adapt-authoring-ui2)
-
-The frontend is a React 19 SPA using TanStack React Query v5 for data fetching/caching, MUI v7 for components, and React Router DOM v7 for routing. There is no Redux or other global state — React Query is the exclusive server-state layer.
-
-The `useProjectContent(courseId)` hook loads **all content for a course** in a single bulk `POST /api/content/query` with `{ _courseId }`. Every field of every document is returned — there is no field projection. The flat array is then transformed client-side by `buildTree()` into a nested tree structure:
-
-```js
-// useProjectContent.js — buildTree()
-function buildTree(data) {
-  const flatMap = new Map()
-  data.forEach(item => flatMap.set(item._id, { ...item, children: [] }))
-  const roots = []
-  flatMap.forEach(item => {
-    if (isRootType(item._type)) roots.push(item)
-    else if (item._parentId && flatMap.has(item._parentId))
-      flatMap.get(item._parentId).children.push(item)
-  })
-  // sort children by _sortOrder at each level
-  roots.forEach(sortChildren)
-  return { tree: roots, flatMap }
-}
-```
-
-The hook returns both `tree` (nested roots with `.children` arrays) and `flatMap` (`Map<_id, item>` for O(1) lookup). This is rebuilt via `useMemo` on every data change.
-
-**Staleness and refresh:** React Query's `staleTime` is 5 minutes, `cacheTime` is 30 minutes, `refetchOnWindowFocus` is false. After any mutation (add, edit, delete, move), `useApiMutation` calls `queryClient.invalidateQueries({ queryKey: ['content'] })`, which triggers a **full re-fetch of all content** for the course. There are no optimistic updates or partial invalidation.
-
-### What the frontend actually uses for tree operations
-
-| Operation | Fields needed |
-|-----------|--------------|
-| Tree rendering (`ContentCards`) | `_id`, `_parentId`, `_type`, `_sortOrder`, `title`, `displayTitle`, `_component`, `_layout` |
-| Move / pick-and-place | `_id`, `_parentId`, `_sortOrder`, `_layout` |
-| Breadcrumb navigation | `_id`, `_parentId`, `_type`, `title` |
-| Extension management | `_type`, `_enabledPlugins`, `title` |
-| Full editing (schema form open) | All fields (fetched separately via `api.get(id)`) |
-
-The tree-structural fields are ~8 fields. A typical content document has 30-80+ fields (all plugin extension properties, body text, graphics, etc.). For a 100-item course, the full payload is ~300-500KB; a tree projection would be ~10-20KB — a **15-30x reduction**.
-
-### Why a tree endpoint is particularly well-suited to this architecture
-
-React Query's query key system is designed for exactly this kind of data splitting:
-
-```js
-// Tree data — lightweight, frequently read, rarely structurally changed
-useQuery({ queryKey: ['content', 'tree', courseId], queryFn: () => api.get(`tree/${courseId}`) })
-
-// Item detail — full document, fetched on demand when editing
-useQuery({ queryKey: ['content', 'item', itemId], queryFn: () => api.get(itemId) })
-```
-
-This enables **selective invalidation**: editing a content item's body text only invalidates the `['content', 'item', itemId]` query — the tree stays cached because the structure hasn't changed. Only structural mutations (add, delete, move) would invalidate the tree query. Currently, every single edit re-fetches every document in the course.
-
-The frontend already has the `buildTree()` function that constructs an adjacency-list tree identical in concept to the proposed server-side `ContentTree`. If the server returned a pre-built tree (or a projected flat array), the client-side `buildTree` would either be simplified or eliminated entirely.
-
-### What the API currently supports
-
-The `/query` endpoint supports `sort`, `limit`, `skip`, `page`, and `collation` as query params. It does **not** support field projection — the `queryHandler` only extracts those five options from the URL.
-
-The MongoDB driver and `MongoDBModule` fully support projections internally, but there is no way to request them through the HTTP API.
-
-### Two options
-
-**Option A: Add projection support to the existing `/query` endpoint**
-
-Add `projection` to the list of recognised query params in `AbstractApiModule.queryHandler()`. This is a small change that benefits all API modules:
-
-```js
-// In queryHandler, add 'projection' to the allowed params
-if (['collation', 'limit', 'page', 'projection', 'skip', 'sort'].includes(key)) {
-  mongoOpts[key] = JSON.parse(req.apiData.query[key])
-}
-```
-
-Usage: `POST /api/content/query?projection={"_id":1,"_parentId":1,"_type":1,"_sortOrder":1,"title":1}`
-
-**For:** Generic, benefits all modules. No new routes or handlers. Frontend can adopt immediately.
-**Against:** Exposes raw MongoDB projection syntax to API consumers. Harder to cache/optimise server-side. No semantic meaning — callers must know which fields they need.
-
-**Option B: Dedicated `GET /api/content/tree/:_courseId` endpoint**
-
-A purpose-built route that returns a tree-optimised projection:
-
-```js
-// In setValues()
-this.routes.push({
-  route: '/tree/:_courseId',
-  handlers: { get: this.handleTree.bind(this) },
-  permissions: { get: ['read:content'] },
-  meta: apidefs.tree
-})
-
-// Handler
-async handleTree (req, res, next) {
-  try {
-    const items = await this.find(
-      { _courseId: req.params._courseId },
-      { validate: false },
-      { projection: { _id: 1, _parentId: 1, _courseId: 1, _type: 1, _sortOrder: 1, title: 1, displayTitle: 1, _component: 1, _layout: 1 } }
-    )
-    res.json(items)
-  } catch (e) {
-    return next(e)
-  }
-}
-```
-
-**For:** Semantic, self-documenting. Easy to cache aggressively (tree structure changes less often than content). Could return a pre-built nested tree structure (eliminating client-side `buildTree`). Clear versioning boundary. Can be extended with `updatedAt` per item for fine-grained staleness checks.
-**Against:** New endpoint to maintain. Requires coordinated frontend change.
-
-### Where a tree endpoint would have real value
-
-1. **Selective invalidation** — the highest-impact change. Currently every mutation invalidates and re-fetches all content (~300-500KB). With separate tree and item-detail queries, editing a field only re-fetches that one item (~1-5KB). Only structural changes (add/delete/move) invalidate the tree (~10-20KB). For a 100-item course, this reduces the data re-fetched per edit by ~99%.
-
-2. **Faster initial load** — the tree endpoint returns ~10-20KB instead of ~300-500KB. The `ContentCards` tree view can render immediately. Full item data is fetched lazily when the user opens an edit form. This is the natural React Query pattern.
-
-3. **Lightweight structural refresh** — instead of re-fetching all content after structural mutations, re-fetch only the tree. The frontend can diff the new tree against the cached one to identify which items changed (new, deleted, moved).
-
-4. **Server-side outline** — useful for features that need a quick structural overview (analytics, course listing with item counts, a table-of-contents panel, multi-course operations).
-
-5. **Alignment with existing client-side code** — `useProjectContent.buildTree()` already constructs this exact data structure client-side. A tree endpoint makes this server-authoritative rather than duplicated.
-
-### Recommendation
-
-**Both options should be implemented, in order:**
-
-**Step 1: Option A (projection on `/query`)** — a small, low-risk change to `AbstractApiModule` that immediately benefits all internal projection use cases (see MongoDB Projections section in the general audit) and lets the frontend start requesting lighter payloads. This is useful even without a dedicated tree endpoint.
-
-**Step 2: Option B (dedicated `/tree` endpoint)** — build this alongside the frontend refactor to split `useProjectContent` into two queries (tree + item detail). The server-side `ContentTree` class proposed above could serve double duty: used internally for `clone`/`delete`/`updateEnabledPlugins` optimisations, and also used to generate the tree endpoint response.
-
-The frontend changes to consume the tree endpoint are straightforward — `useProjectContent` would be refactored into `useProjectTree` (lightweight, frequently refreshed) and `useContentItem(id)` (full document, fetched on demand). React Query's architecture makes this a natural split, and the `buildTree` function can be dropped or simplified since the server would return the data in tree-ready form.