adapt-authoring-core 2.5.0 → 3.0.1

package/docs/developer-workflow.md

@@ -0,0 +1,649 @@
+# Developer workflow
+
+This guide covers day-to-day development workflows for the Adapt authoring tool, with a focus on managing parallel streams of work across the multi-repo architecture.
+
+## Quick navigation
+
+- [How the project is structured](#how-the-project-is-structured)
+- [Local development environment](#local-development-environment)
+- [Workflow 1: Single-module bug fix](#workflow-1-single-module-bug-fix)
+- [Workflow 2: Multi-module feature](#workflow-2-multi-module-feature)
+- [Workflow 3: Hotfix during feature work](#workflow-3-hotfix-during-feature-work)
+- [Workflow 4: Patching an older release line](#workflow-4-patching-an-older-release-line)
+- [Coordinating releases](#coordinating-releases)
+- [Version pinning strategy](#version-pinning-strategy)
+- [Common pitfalls](#common-pitfalls)
+
+## How the project is structured
+
+Understanding the release pipeline is essential to choosing the right workflow.
+
+```
+┌─────────────────────────────────────────────────────────┐
+│  adapt-authoring (parent)                               │
+│  ├── Depends on 43+ adapt-authoring-* modules           │
+│  ├── Released manually via workflow_dispatch             │
+│  └── Runs integration tests across all modules          │
+│                                                         │
+│  Each module (api/, core/, auth/, server/, etc.)         │
+│  ├── Is a separate git repository                       │
+│  ├── Has its own CI (linting, tests, releases)          │
+│  ├── Releases automatically on merge to master          │
+│  └── Published to npm or GitHub Packages                │
+└─────────────────────────────────────────────────────────┘
+```
+
+**Key implication:** Merging a PR to a module's `master` branch triggers an immediate release via semantic-release. There is no staging step between merge and publish. This makes merge timing critical when coordinating multi-module changes.
+
+## Local development environment
+
+### Directory layout
+
+The recommended local setup keeps all repos in a single parent directory:
+
+```
+AAT/
+├── adapt-authoring/        # Parent application (npm workspaces)
+├── api/                    # adapt-authoring-api (own git repo)
+├── auth/                   # adapt-authoring-auth (own git repo)
+├── core/                   # adapt-authoring-core (own git repo)
+├── mongodb/                # adapt-authoring-mongodb (own git repo)
+├── server/                 # adapt-authoring-server (own git repo)
+├── ...                     # 40+ more module repos
+└── adapt-authoring/
+    └── local_adapt_modules/  # Symlinks or clones used by workspaces
+```
+
+### How local testing works
+
+The parent `adapt-authoring/` uses npm workspaces pointed at `local_adapt_modules/*`. When a module is present in that directory, npm resolves it locally instead of from the registry. This means you can test changes to any module without publishing first.
+
+```bash
+# Link a module for local development
+cd adapt-authoring/local_adapt_modules
+ln -s ../../api adapt-authoring-api
+
+# Reinstall to pick up the local link
+cd ..
+npm install --legacy-peer-deps
+```
+
+### Running the application locally
+
+```bash
+cd adapt-authoring
+npm start              # Production mode
+npm run debug          # With --inspect flag for debugger
+```
+
+### Running tests
+
+```bash
+# Integration tests (from parent — boots app + MongoDB)
+cd adapt-authoring
+npm test
+
+# Unit tests (from a specific module)
+cd api
+npm test               # Runs: node --test tests/**/*.spec.js
+
+# Linting (from any module)
+npx standard
+```
+
+## Workflow 1: Single-module bug fix
+
+This is the most common workflow. A bug exists in one module and needs to be fixed and released.
+
+### Steps
+
+```bash
+# 1. Start from a clean master
+cd api
+git checkout master && git pull origin master
+
+# 2. Create a branch
+git checkout -b issue/1234
+
+# 3. Make changes, lint, and test
+#    ... edit files ...
+npx standard
+npm test
+
+# 4. Commit with the correct prefix
+git commit -m "Fix: Prevent crash when uploading empty file (fixes #1234)"
+
+# 5. Push and create PR
+git push -u origin issue/1234
+gh pr create --title "Fix: Prevent crash when uploading empty file" \
+  --body "### Fixes #1234
+
+### Fix
+* Prevent crash when req.file is undefined on upload endpoint
+
+### Testing
+1. Upload an empty file via the UI
+2. Verify no 500 error"
+```
+
+### What happens after merge
+
+1. GitHub Actions runs semantic-release on the module
+2. A new patch version is published (e.g. `3.3.0` → `3.3.1`)
+3. The parent `adapt-authoring` repo still pins the old exact version — **the fix does not reach production until you explicitly bump it**
+4. A main repo release (manual) picks up the new version when you're ready
+
+This is by design. The parent uses [exact version pinning](#version-pinning-strategy), so no module update reaches production until a developer deliberately updates `package.json`.
+
+### Getting the fix to production
+
+Update the pinned version in the parent to the newly released patch:
+
+```bash
+cd adapt-authoring
+git checkout master && git pull origin master
+
+# Update the dependency to the specific patch version
+npm install adapt-authoring-api@3.3.1 --save-exact --legacy-peer-deps
+
+# Commit the dependency bump
+git add package.json package-lock.json
+git commit -m "Upgrade: Bump adapt-authoring-api to v3.3.1 (refs #1234)"
+git push origin master
+
+# Trigger the release workflow from GitHub Actions UI
+# or via CLI:
+gh workflow run release.yml
+```
+
+Because versions are pinned exactly, this bump includes *only* the bugfix — no unrelated features are pulled in.
+
+## Workflow 2: Multi-module feature
+
+A new feature spans multiple modules — for example, adding batch export support might touch `content`, `assets`, `api`, and `ui`.
+
+### Phase 1: Branch all affected modules
+
+```bash
+# Create feature branches in each affected module
+for module in content assets api ui; do
+  cd /path/to/AAT/$module
+  git checkout master && git pull origin master
+  git checkout -b feature/batch-export
+done
+```
+
+Use a consistent branch name across all modules — this makes it obvious which branches belong together.
+
+### Phase 2: Develop and test locally
+
+Work across the modules as needed. The local workspace setup means all your changes are picked up without publishing:
+
+```bash
+# Run the full application with all your local changes
+cd adapt-authoring
+npm start
+
+# Run integration tests against your combined changes
+npm test
+```
+
+**Important:** Regularly test your feature branches against `master` of all other modules. This catches integration issues early and prevents surprises at merge time.
+
+### Phase 3: Create PRs — but do not merge yet
+
+Create a PR in each affected module. Use the PR description to cross-reference the related PRs:
+
+```bash
+cd content
+git push -u origin feature/batch-export
+gh pr create --title "New: Add batch export support" \
+  --body "### Fixes #42
+
+Part of the batch export feature. Related PRs:
+- <org>/<module-assets-repo>#15
+- <org>/<module-api-repo>#28
+- <org>/<module-ui-repo>#33
+
+### New
+* Add batch selection to content schema
+
+### Testing
+1. Select multiple items and trigger export
+2. Verify export completes with all items"
+```
+
+### Phase 4: Review and approve all PRs
+
+Get all PRs reviewed and approved, but **do not merge them individually**. Merging one module triggers a release of that module, and the feature may not work without the other modules being updated simultaneously.
+
+### Phase 5: Merge in dependency order
+
+Once all PRs are approved and CI is green, merge them in dependency order — modules that others depend on should be merged first:
+
+```
+1. core (if changed)     — foundational, no module deps
+2. api                   — depends on core
+3. assets                — depends on api
+4. content               — depends on assets, api
+5. ui                    — depends on api
+```
+
+Wait for each module's release workflow to complete before merging the next, so that downstream modules can resolve the new version as a peer dependency.
+
+```bash
+# Check that the release completed
+gh run list --repo <org>/adapt-authoring-api --limit 3
+```
+
+### Phase 6: Update and release the parent
+
+Update the parent to pin the exact new versions of each changed module:
+
+```bash
+cd adapt-authoring
+git checkout master && git pull origin master
+
+# Update all changed dependencies to their exact new versions
+npm install adapt-authoring-api@3.5.0 \
+            adapt-authoring-assets@1.6.0 \
+            adapt-authoring-content@1.1.0 \
+            adapt-authoring-ui@2.1.0 \
+            --save-exact --legacy-peer-deps
+
+# Run integration tests
+npm test
+
+# Commit and push
+git add package.json package-lock.json
+git commit -m "New: Add batch export support (fixes #100)"
+git push origin master
+
+# Trigger release
+gh workflow run release.yml
+```
+
+## Workflow 3: Hotfix during feature work
+
+You're midway through a multi-module feature when a critical bug is reported in production. Here's how to handle it without disrupting your feature work.
+
+### The situation
+
+```
+You are working on:
+  content    → branch: feature/batch-export
+  assets     → branch: feature/batch-export
+  api        → branch: feature/batch-export
+
+Bug reported in: api (unrelated to your feature)
+```
+
+### Step 1: Fix the bug on a separate branch
+
+The multi-repo structure helps here — the bug is in one module and your feature branches are unaffected:
+
+```bash
+cd api
+
+# Stash or commit any in-progress feature work
+git stash  # or commit to the feature branch
+
+# Create a hotfix branch from master
+git checkout master && git pull origin master
+git checkout -b issue/5678
+
+# Fix the bug
+#    ... edit files ...
+npx standard
+npm test
+
+# Commit and PR
+git commit -m "Fix: Correct pagination offset in list endpoint (fixes #5678)"
+git push -u origin issue/5678
+gh pr create --title "Fix: Correct pagination offset in list endpoint" \
+  --body "### Fixes #5678
+
+### Fix
+* Off-by-one error in pagination calculation
+
+### Testing
+1. Request page 2 of any list endpoint
+2. Verify correct items are returned"
+```
+
+### Step 2: Get the fix merged and released
+
+Follow the normal review process. Once merged, semantic-release publishes the patch.
+
+### Step 3: Push the fix to production
+
+Because versions are pinned exactly, you can bump *only* the patched module — no unreleased features from other modules are pulled in:
+
+```bash
+cd adapt-authoring
+git checkout master && git pull origin master
+npm install adapt-authoring-api@3.3.1 --save-exact --legacy-peer-deps
+git add package.json package-lock.json
+git commit -m "Upgrade: Bump adapt-authoring-api to v3.3.1 (fixes #5678)"
+git push origin master
+gh workflow run release.yml
+```
+
+### Step 4: Rebase your feature branch
+
+Back on your feature work, rebase to pick up the hotfix (especially important if your feature touches the same module):
+
+```bash
+cd api
+git checkout feature/batch-export
+git rebase master
+
+# If you stashed earlier
+git stash pop
+```
+
+If there are no conflicts, you're done. If there are conflicts, resolve them — the fix is now part of your feature branch's history.
+
+### Step 5: Test the feature against the updated master
+
+```bash
+cd adapt-authoring
+npm test
+```
+
+This ensures your feature still works with the hotfix in place.
+
+## Workflow 4: Patching an older release line
+
+A feature has been developed and released as a new minor version (`v1.1.0`), but production is still pinned to `v1.0.0`. A bug is now found that needs fixing in the `v1.0.x` line *without* including the `v1.1.0` changes. The fix also needs to be in `v1.1.x` going forward.
+
+**This requires two releases:** a patch on the old line (`v1.0.1`) and a patch on the current line (`v1.1.1`).
+
+### Prerequisites: maintenance branch support
+
+Modules need semantic-release configured to support maintenance branches. This is a one-time setup per module — see [Configuring maintenance branch support](#configuring-maintenance-branch-support) below.
+
+### Step 1: Create the maintenance branch
+
+Branch from the tag of the version you need to patch:
+
+```bash
+cd my-module
+git fetch --tags
+git checkout -b 1.0.x v1.0.0
+```
+
+The branch name **must** match the pattern configured in semantic-release (e.g. `1.0.x`, `1.1.x`). This tells semantic-release to release within that version range.
+
+### Step 2: Fix the bug on the maintenance branch
+
+```bash
+git checkout -b issue/5678 1.0.x
+
+# Make the fix
+npx standard
+npm test
+
+git commit -m "Fix: Handle null values in export (fixes #5678)"
+git push -u origin issue/5678
+
+# PR targets the 1.0.x branch, NOT master
+gh pr create --base 1.0.x \
+  --title "Fix: Handle null values in export" \
+  --body "### Fixes #5678
+
+### Fix
+* Guard against null values during content export
+
+### Testing
+1. Export a course with empty optional fields
+2. Verify export completes without error"
+```
+
+### Step 3: Merge and release v1.0.1
+
+Once the PR is reviewed and merged into the `1.0.x` branch, semantic-release runs and publishes `v1.0.1`. This version contains only the `v1.0.0` code plus the bugfix — no `v1.1.0` feature code.
+
+Push the maintenance branch to trigger the release:
+
+```bash
+# The 1.0.x branch needs to exist on the remote for the workflow to trigger
+git push origin 1.0.x
+```
+
+### Step 4: Update production
+
+```bash
+cd adapt-authoring
+git checkout master && git pull origin master
+npm install adapt-authoring-mymodule@1.0.1 --save-exact --legacy-peer-deps
+git add package.json package-lock.json
+git commit -m "Upgrade: Bump adapt-authoring-mymodule to v1.0.1 (fixes #5678)"
+git push origin master
+gh workflow run release.yml
+```
+
+Production now has the bugfix without the feature.
+
+### Step 5: Cherry-pick the fix to master
+
+The fix also needs to be in the `v1.1.x` line. Cherry-pick it onto master:
+
+```bash
+cd my-module
+git checkout master && git pull origin master
+git checkout -b issue/5678-forward
+
+# Cherry-pick the fix commit (use the actual SHA)
+git cherry-pick <commit-sha>
+
+# Resolve conflicts if any — the code may have changed between v1.0.0 and v1.1.0
+npx standard
+npm test
+
+git push -u origin issue/5678-forward
+gh pr create --title "Fix: Handle null values in export (fixes #5678)" \
+  --body "### Fixes #5678
+
+Cherry-pick of the fix from the 1.0.x maintenance branch.
+
+### Fix
+* Guard against null values during content export"
+```
+
+Once merged to master, semantic-release publishes `v1.1.1` with the fix included.
+
+### Visual timeline
+
+```
+master:  v1.0.0 ──── New: feature ──── v1.1.0 ──── cherry-pick fix ──── v1.1.1
+              \                                          ↑
+1.0.x:         └──────────────── Fix: bug ──── v1.0.1   │
+                                    │                    │
+                                    └────────────────────┘
+                                      (same fix, both lines)
+```
+
+### Configuring maintenance branch support
+
+This is a one-time setup per module. Two files need updating:
+
+**1. `package.json` — add `branches` to the release config:**
+
+```json
+"release": {
+  "branches": [
+    "+([0-9]).+([0-9]).x",
+    "master"
+  ],
+  "plugins": [
+    ["@semantic-release/commit-analyzer", { "preset": "eslint" }],
+    ["@semantic-release/release-notes-generator", { "preset": "eslint" }],
+    "@semantic-release/npm",
+    "@semantic-release/github",
+    "@semantic-release/git"
+  ]
+}
+```
+
+The `+([0-9]).+([0-9]).x` pattern matches branches like `1.0.x`, `2.3.x`, etc. The `master` entry keeps the existing behaviour for normal releases. Order matters — maintenance branches must come before the main branch.
+
+**2. `.github/workflows/releases.yml` — trigger on maintenance branches:**
+
+```yaml
+name: Release
+on:
+  push:
+    branches:
+      - master
+      - '+([0-9]).+([0-9]).x'
+
+jobs:
+  release:
+    name: Release
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      issues: write
+      pull-requests: write
+      id-token: write
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v3
+        with:
+          fetch-depth: 0
+      - name: Setup Node.js
+        uses: actions/setup-node@v3
+        with:
+          node-version: 'lts/*'
+      - name: Update npm
+        run: npm install -g npm@latest
+      - name: Install dependencies
+        run: npm install
+      - name: Release
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: npx semantic-release
+```
+
+The key change is adding `'+([0-9]).+([0-9]).x'` to the `branches` trigger so pushes to maintenance branches also run the release workflow.
+
+### When to create maintenance branches
+
+Don't create maintenance branches preemptively. Create them only when you actually need to patch an older release line. Once a maintenance branch is no longer needed (e.g. production has moved to `v1.1.x`), it can be left as-is — it won't interfere with future releases.
+
+### Cleaning up maintenance branches
+
+Maintenance branches can be deleted from the remote once production has moved past that version line:
+
+```bash
+# Only after production is on v1.1.x or later
+git push origin --delete 1.0.x
+```
+
+## Coordinating releases
+
+### Module releases (automatic)
+
+Every merge to a module's `master` (or a maintenance branch like `1.0.x`) triggers semantic-release. The commit message prefix determines the version bump:
+
+| Merge contains | Version bump | Example |
+|---|---|---|
+| `Fix:` commits only | Patch (0.0.x) | 3.3.0 → 3.3.1 |
+| `Update:` or `New:` | Minor (0.x.0) | 3.3.0 → 3.4.0 |
+| `Breaking:` | Major (x.0.0) | 3.3.0 → 4.0.0 |
+| `Docs:`, `Chore:` only | No release | — |
+
+### Main repository releases (manual)
+
+The parent `adapt-authoring` repo aggregates module updates and releases on its own cadence:
+
+1. Module releases accumulate on npm/GitHub Packages
+2. A developer updates `package.json` in the parent to reference new versions
+3. Integration tests run to validate the combination
+4. The release workflow is triggered manually via `gh workflow run release.yml`
+5. `at-utils version-check` determines the appropriate version bump based on which modules changed
+
+### When to release the parent
+
+- **After a hotfix:** Immediately, to get the fix to production
+- **After a feature:** Once all module PRs are merged, their releases complete, and integration tests pass
+- **On a regular cadence:** Periodically, to batch smaller improvements
+
+## Version pinning strategy
+
+The parent `adapt-authoring/package.json` uses **exact version pinning** (no `^` or `~` prefix) for all module dependencies. This is the foundation that makes the hotfix-during-feature-work workflow safe.
+
+### Why exact versions?
+
+The problem with caret ranges (`^`):
+
+```
+Timeline:
+  1. adapt-authoring-api is at 3.3.0 in production
+  2. Developer ships a new feature → api 3.4.0 released to npm
+  3. A bug is found in production
+  4. Developer fixes the bug → api 3.4.1 released to npm
+  5. Production site runs npm ci...
+```
+
+With `"adapt-authoring-api": "^3.3.0"`, step 5 installs `3.4.1` — which includes the untested feature from step 2 alongside the bugfix. The production site gets changes that haven't been through a full release cycle.
+
+With `"adapt-authoring-api": "3.3.0"` (exact), step 5 installs exactly `3.3.0`. The developer then explicitly bumps to `3.3.1` (bugfix only) or `3.4.1` (bugfix + feature) depending on what's appropriate.
+
+### How it works in practice
+
+| Scenario | What to bump to | Command |
+|---|---|---|
+| Hotfix only | The patch version | `npm install adapt-authoring-api@3.3.1 --save-exact` |
+| Feature ready for release | The minor version (includes all patches) | `npm install adapt-authoring-api@3.4.1 --save-exact` |
+| Breaking change | The major version | `npm install adapt-authoring-api@4.0.0 --save-exact` |
+
+### Rules
+
+1. **Always use `--save-exact`** when updating dependencies in the parent repo (or set `save-exact=true` in `.npmrc`)
+2. **Never use `@latest`** in the parent repo — always specify the exact version you intend to deploy
+3. **One concern per bump** — if you're shipping a hotfix, only bump the module that was patched; don't bundle in other module updates
+4. **Batch feature updates** into planned releases — update multiple modules together only when you're ready to test and release the full set
+
+### What about peer dependencies in modules?
+
+Module-to-module peer dependencies (e.g. `"adapt-authoring-core": "^2.0.0"` in `adapt-authoring-api/package.json`) should continue using caret ranges. These express compatibility ranges, not deployment targets. The parent's exact pins determine what actually runs together in production.
+
+## Common pitfalls
+
+### Shipping unreleased features with a hotfix
+
+**Problem:** A module has a new feature (minor release) and a subsequent bugfix (patch release). You bump the parent to get the bugfix, but the new feature comes along for the ride because both are on `master`.
+
+**Solution:** This is exactly why the parent uses exact version pinning. When bumping for a hotfix, specify the patch version explicitly (`3.3.1`), not `@latest`. If the bugfix was released *after* a feature (i.e. `master` already has `v3.4.0` and you need to patch `v3.3.0`), use a [maintenance branch](#workflow-4-patching-an-older-release-line) to release `v3.3.1` from the old line. In most cases, plan your merge order so that hotfixes land before features on the module's master branch.
+
+### Merging a multi-module feature one PR at a time
+
+**Problem:** You merge the API changes but not the UI changes. The API release publishes a new version that the UI hasn't been updated to work with. Users who update get a broken combination.
+
+**Solution:** Merge in dependency order, wait for each release, and don't leave partial features merged overnight.
+
+### Forgetting to rebase after a hotfix
+
+**Problem:** Your feature branch diverges from master after a hotfix lands. When you eventually merge, you may introduce conflicts or accidentally revert the hotfix.
+
+**Solution:** Rebase feature branches promptly after any hotfix to the same module.
+
+### Committing with the wrong prefix
+
+**Problem:** A `Fix:` commit triggers a patch release, but your change is actually a breaking change. Consumers don't expect a major API shift in a patch version.
+
+**Solution:** Double-check your commit prefix. Use `Breaking:` for anything that changes existing behaviour in a non-backwards-compatible way. See [commit message guidelines](contributing-code#commit-messages) for details.
+
+### Testing only the module, not the integration
+
+**Problem:** Module-level tests pass, but the feature breaks when modules interact.
+
+**Solution:** Always run `npm test` from the parent `adapt-authoring/` directory before marking your work as ready for review. This runs integration tests that boot the full application.
+
+### Publishing a dependency bump without testing
+
+**Problem:** You update `adapt-authoring/package.json` to reference new module versions and release without running integration tests. A subtle incompatibility ships.
+
+**Solution:** Always run integration tests locally (or let CI run them) before triggering the parent release workflow.

package/docs/error-handling.md

@@ -0,0 +1,49 @@
+# Error handling
+Handling errors correctly is a key aspect of writing stable software. This guide will give some tips on how you should deal with errors, as well as the utilities available to make error handling simpler.
+
+Before going into specifics, it would be useful to discuss application errors in general terms. The errors you experience are likely to fall into one of the following broad groups:
+- **Initialisation errors**: i.e. problems during start-up
+- **General server errors**: errors which occur outside of user requests, possibly during automated tasks
+- **User errors**: errors which are a direct result of a user request
+
+You will need to deal with each category of error differently. Below are some general tips on handling each type of error.
+
+## Initialisation errors
+Any errors which occur during initialisation should be captured and logged as appropriate. Depending on the type of error, it may or may not be considered fatal to your code.
+
+Some examples:
+- For a database-handler module, failing to connect to the database would be considered a fatal error, as no further actions can be executed. In this case, the code should perform any clean-up and exit.
+- For a configuration module, failing to load the user configuration file may not be fatal if the application can run without it (e.g. with default settings). In this case the error should be logged, but the code can continue to initialise post-error.
+- For a module which attempts to load a specific file in each module connected to the core system, failing to load a single configuration file may not be an error as such, but rather an expected outcome if the configuration file in question is not something that's required to be defined for every module. In this case, the code can continue and it may not even be necessary to log a message.
+
+## General server errors
+'General server errors' is a broad category which covers other errors that don't take place at either initialisation or as a result of direct user action. Again, depending on the specific error, these may or may not be fatal.
+
+Some examples:
+- For a database-handler module, disconnecting from the database is an expected error, and can be handled and rectified easily.
+
+## User errors
+User errors are any errors which are caused as a direct result of a user performing an action incorrectly. It is even *more* critical with user errors that the error is as specific and descriptive as possible, as the response needs to be informative and instructive to the user that caused the error. Failing to do so will result in an unpleasant user experience.
+
+Some examples:
+- A user uploads a file in an invalid format. This definitely isn't a fatal error, as the code can continue post-error. The returned error should inform the user of the issue, as well as how it can be rectified.
+
+## Defining errors
+Depending on the kinds of error that you're dealing with in your code, it may be useful to include a set of custom error definitions specific to your code.
+
+Defining useful errors is a critical part of any software system. The error registry makes it easy to define errors for your own modules, and make use of errors defined in other modules.
+
+## Catching errors
+
+## Throwing errors
+As mentioned above, it is preferable to catch errors internally in your code and re-throw these errors.
+
+The error registry acts as a central store for all errors defined in the system, and errors can be accessed and thrown from here. For convenience, the errors registry is available directly as a property of the main App instance via `app.errors`:
+
+```js
+try {
+  // do something here
+} catch(e) {
+  throw this.app.errors.MY_ERROR
+}
+```