adapt-authoring-core 3.0.2 → 3.2.0

package/adapt-authoring.json

@@ -7,17 +7,21 @@
     "sourceIndex": "docs/index-backend.md",
     "manualPages": {
       "binscripts.md": "reference",
+      "configure-environment.md": "getting-started",
       "contributing.md": "contributing",
       "contributing-code.md": "contributing",
       "coremodules.md": "reference",
       "customising.md": "development",
+      "developer-workflow.md": "contributing",
+      "error-handling.md": "concepts",
       "folder-structure.md": "getting-started",
       "hooks.md": "concepts",
       "licensing.md": "reference",
       "releasing.md": "contributing",
       "request-response.md": "concepts",
       "run.md": "getting-started",
-      "writing-a-module.md": "development"
+      "writing-a-module.md": "development",
+      "writing-tests.md": "development"
     },
     "manualPlugins": [
       "docs/plugins/binscripts.js",

package/conf/config.schema.json

@@ -40,6 +40,44 @@
       "description": "The default language used by the server",
       "type": "string",
       "default": "en"
+    },
+    "appName": {
+      "description": "Application name displayed in the UI header and browser tab",
+      "type": "string",
+      "default": "Adapt",
+      "_adapt": { "isPublic": true }
+    },
+    "primaryColour": {
+      "description": "Primary palette colour for the UI theme (hex format)",
+      "type": "string",
+      "pattern": "^#([0-9a-fA-F]{3}|[0-9a-fA-F]{6})$",
+      "default": "#1ec0d9",
+      "_adapt": { "isPublic": true }
+    },
+    "chromeColour": {
+      "description": "Chrome colour (navy): icon rail, app bar, headings (hex format)",
+      "type": "string",
+      "pattern": "^#([0-9a-fA-F]{3}|[0-9a-fA-F]{6})$",
+      "default": "#263944",
+      "_adapt": { "isPublic": true }
+    },
+    "commitColour": {
+      "description": "Commit colour (mint): the single affirmative action per view, e.g. Save/Create (hex format)",
+      "type": "string",
+      "pattern": "^#([0-9a-fA-F]{3}|[0-9a-fA-F]{6})$",
+      "default": "#00dd95",
+      "_adapt": { "isPublic": true }
+    },
+    "accentColour": {
+      "description": "Accent colour (expressive) and the default decorative-icon ink; never a button fill (hex format)",
+      "type": "string",
+      "pattern": "^#([0-9a-fA-F]{3}|[0-9a-fA-F]{6})$",
+      "default": "#ec4899",
+      "_adapt": { "isPublic": true }
+    },
+    "logo": {
+      "description": "Absolute path to a custom logo image (PNG recommended — email-safe) to bake into the UI build (overrides the built-in mark) and reuse in branded emails. Leave unset to use the built-in logo.",
+      "type": "string"
     }
   }
 }

package/docs/writing-a-module.md

@@ -98,6 +98,17 @@ export default class MyModule extends AbstractModule {
 }
 ```
 
+`waitForModule` rejects if the module isn't installed, so it's for **required** dependencies. For an **optional** integration, probe first with `App#isModuleAvailable` (which never throws) and only wait when it's present — don't `try/catch` `waitForModule`, as that conflates "not installed" with "installed but failed to load":
+
+```javascript
+if (this.app.isModuleAvailable('websocket')) {
+  const websocket = await this.app.waitForModule('websocket');
+  // wire up the optional integration
+}
+```
+
+Both accept short names (without the `adapt-authoring-` prefix).
+
 ### _Optional task: add a configuration schema_
 
 If you plan to add user-configurable settings to your module, you can add a `config.schema.json` to define which settings users need to add. See [this page](defining-config) for more information.
@@ -122,4 +133,33 @@ If you don't want to publish your module to npm, you can simply provide the URL
     "adapt-authoring-mymodule": "https://github.com/MY_GITHUB_ACCOUNT/GITHUB_REPO_NAME.git"
   }
 }
-```
+```
+
+## Conventions
+
+Beyond structure and code, modules follow a few project-wide conventions.
+
+### Linting
+
+All code must pass [Standard.js](https://standardjs.com/) — no config file is needed. Run `npx standard` in the module root; it must pass before opening a PR.
+
+### Testing
+
+Write tests with `node:test` and `node:assert/strict` (see [Writing tests](writing-tests)). The project's testable-code conventions:
+
+- Extract discrete logic (transformations, mappers, predicates, validators) into one function per file under `lib/utils/<fn>.js`, re-exported via a `lib/utils.js` barrel.
+- Keep logic in the class only when it needs instance state, orchestrates side effects, or is a trivial one-liner delegating to a utility.
+- Each utility gets a matching `tests/utils-<name>.spec.js`, importing the file directly.
+- Use `mock.module()` (before the dynamic `import()`) when the function imports app modules; use table-driven tests for mappers and lookups.
+- Run unit tests with `node --experimental-test-module-mocks --test 'tests/**/*.spec.js'`.
+
+### Workflow and releases
+
+- Start from a clean `master` (`git checkout master && git pull`), then branch.
+- Commit with `Tag: description (fixes #N)` — the tag determines the release type (see [Contributing code](contributing-code)).
+- Merging to `master` triggers an **immediate** semantic-release publish; there is no staging step between merge and publish (see [Developer workflow](developer-workflow)).
+
+### Documentation
+
+- Document non-obvious behaviour in `docs/*.md` guides (built into the documentation site), not just inline comments. Cover what the module does, the APIs/seams it exposes, and any gotchas.
+- Keep the guides current: when a change alters documented behaviour, update the relevant `docs/*.md` in the **same PR**. Treat stale docs as a bug.

package/lib/AbstractModule.js

@@ -1,4 +1,5 @@
 import Hook from './Hook.js'
+import { toShortName } from './utils/toShortName.js'
 /**
  * Abstract class for authoring tool modules. All custom modules must extend this class.
  * @memberof core
@@ -114,7 +115,7 @@ class AbstractModule {
    * @param {...*} rest Arguments to log
    */
   log (level, ...rest) {
-    this.app.logger?.log(level, this.name.replace(/^adapt-authoring-/, ''), ...rest)
+    this.app.logger?.log(level, toShortName(this.name), ...rest)
   }
 }
 

package/lib/App.js

@@ -146,6 +146,15 @@ class App extends AbstractModule {
     const results = await Promise.all(modNames.map(m => this.dependencyloader.waitForModule(m)))
     return results.length > 1 ? results : results[0]
   }
+
+  /**
+   * Whether a dependency is installed and loadable as an Adapt module. Use to guard optional integrations without throwing (`waitForModule` rejects when a module is missing).
+   * @param {string} modName Name of the module (short or full)
+   * @return {boolean}
+   */
+  isModuleAvailable (modName) {
+    return this.dependencyloader.isAvailable(modName)
+  }
 }
 
 export default App

package/lib/DependencyLoader.js

@@ -1,7 +1,7 @@
 import { glob } from 'glob'
 import path from 'path'
 import Hook from './Hook.js'
-import { metadataFileName, packageFileName, stripScope, readJson } from './Utils.js'
+import { metadataFileName, packageFileName, stripScope, toShortName, readJson } from './Utils.js'
 
 /**
  * Handles the loading of Adapt authoring tool module dependencies.
@@ -179,6 +179,25 @@ class DependencyLoader {
     }))
   }
 
+  /**
+   * Resolves a module name to the canonical key used in {@link DependencyLoader#configs}: short names (without the `adapt-authoring-` prefix) are expanded to the full form. Config keys are scope-stripped at load time, so a scoped package is reached by its unscoped name.
+   * @param {string} modName Module name (short or full)
+   * @return {string} The canonical config key
+   */
+  resolveModuleName (modName) {
+    return modName.startsWith('adapt-authoring-') ? modName : `adapt-authoring-${modName}`
+  }
+
+  /**
+   * Whether a dependency is installed and loadable as an Adapt module. Lets callers guard optional integrations without throwing — unlike {@link DependencyLoader#waitForModule}, which rejects when a module is missing.
+   * @param {string} modName Module name (short or full)
+   * @return {boolean} `true` when the module is present and not declared `module: false`
+   */
+  isAvailable (modName) {
+    const config = this.configs[this.resolveModuleName(modName)]
+    return Boolean(config) && config.module !== false
+  }
+
   /**
    * Waits for a single module to load. Returns the instance (if loaded), or hooks into moduleLoadedHook to wait for it.
    * @param {string} modName Name of module to wait for (accepts short names without 'adapt-authoring-' prefix)
@@ -189,7 +208,7 @@ class DependencyLoader {
     if (!this._configsLoaded) {
       await this.configsLoadedHook.onInvoke()
     }
-    if (!modName.startsWith('adapt-authoring-')) modName = `adapt-authoring-${modName}`
+    modName = this.resolveModuleName(modName)
     if (!this.configs[modName]) {
       throw this.app.errors.DEP_MISSING.setData({ module: modName })
     }
@@ -216,7 +235,7 @@ class DependencyLoader {
   logProgress (error, instance) {
     if (error) return
 
-    const toShort = names => names.map(n => n.replace('adapt-authoring-', '')).join(', ')
+    const toShort = names => names.map(toShortName).join(', ')
     const loaded = []
     const notLoaded = []
     let totalCount = 0

package/lib/Utils.js

@@ -9,4 +9,5 @@ export { ensureDir } from './utils/ensureDir.js'
 export { escapeRegExp } from './utils/escapeRegExp.js'
 export { stringifyValues } from './utils/stringifyValues.js'
 export { stripScope } from './utils/stripScope.js'
+export { toShortName } from './utils/toShortName.js'
 export { loadDependencyFiles } from './utils/loadDependencyFiles.js'

package/lib/utils/toShortName.js

@@ -0,0 +1,9 @@
+/**
+ * Strips the `adapt-authoring-` prefix from a module name to give its short, display form (e.g. 'adapt-authoring-server' becomes 'server'). Inverse of the canonicalisation in {@link DependencyLoader#resolveModuleName}.
+ * @param {string} name - The module name
+ * @returns {string} The name without the prefix
+ */
+export function toShortName (name) {
+  if (typeof name !== 'string') return name
+  return name.replace(/^adapt-authoring-/, '')
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "adapt-authoring-core",
-  "version": "3.0.2",
+  "version": "3.2.0",
   "description": "A bundle of reusable 'core' functionality",
   "homepage": "https://github.com/adapt-security/adapt-authoring-core",
   "license": "GPL-3.0",

package/tests/DependencyLoader.spec.js

@@ -506,6 +506,38 @@ describe('DependencyLoader', () => {
     })
   })
 
+  describe('#resolveModuleName()', () => {
+    it('should expand a short name to the canonical key', () => {
+      const loader = new DependencyLoader({ rootDir: '/test' })
+      assert.equal(loader.resolveModuleName('server'), 'adapt-authoring-server')
+    })
+
+    it('should leave a full name unchanged', () => {
+      const loader = new DependencyLoader({ rootDir: '/test' })
+      assert.equal(loader.resolveModuleName('adapt-authoring-server'), 'adapt-authoring-server')
+    })
+  })
+
+  describe('#isAvailable()', () => {
+    it('should return true for a present loadable module (short name)', () => {
+      const loader = new DependencyLoader({ rootDir: '/test' })
+      loader.configs = { 'adapt-authoring-server': { name: 'adapt-authoring-server', module: true } }
+      assert.equal(loader.isAvailable('server'), true)
+    })
+
+    it('should return false for a missing module', () => {
+      const loader = new DependencyLoader({ rootDir: '/test' })
+      loader.configs = {}
+      assert.equal(loader.isAvailable('server'), false)
+    })
+
+    it('should return false for a dependency declared module: false', () => {
+      const loader = new DependencyLoader({ rootDir: '/test' })
+      loader.configs = { 'adapt-authoring-docs': { name: 'adapt-authoring-docs', module: false } }
+      assert.equal(loader.isAvailable('docs'), false)
+    })
+  })
+
   describe('#logProgress()', () => {
     it('should not throw when called with valid instance', () => {
       const mockApp = { rootDir: '/test' }

package/tests/utils-toShortName.spec.js

@@ -0,0 +1,30 @@
+import { describe, it } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { toShortName } from '../lib/utils/toShortName.js'
+
+describe('toShortName()', () => {
+  it('should strip the adapt-authoring- prefix', () => {
+    assert.equal(toShortName('adapt-authoring-server'), 'server')
+  })
+
+  it('should only strip an anchored prefix', () => {
+    assert.equal(toShortName('x-adapt-authoring-y'), 'x-adapt-authoring-y')
+  })
+
+  it('should return a name without the prefix unchanged', () => {
+    assert.equal(toShortName('server'), 'server')
+  })
+
+  it('should return an empty string unchanged', () => {
+    assert.equal(toShortName(''), '')
+  })
+
+  it('should return undefined unchanged', () => {
+    assert.equal(toShortName(undefined), undefined)
+  })
+
+  it('should return null unchanged', () => {
+    assert.equal(toShortName(null), null)
+  })
+})