adapt-authoring-core 0.0.1

package/.eslintignore

@@ -0,0 +1 @@
+node_modules

package/.eslintrc

@@ -0,0 +1,14 @@
+{
+  "env": {
+      "browser": false,
+      "node": true,
+      "commonjs": false,
+      "es2020": true
+  },
+  "extends": [
+      "standard"
+  ],
+  "parserOptions": {
+      "ecmaVersion": 2020
+  }
+}

package/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,55 @@
+name: Bug Report
+description: File a bug report
+labels: ["bug"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for taking the time to fill out this bug report!
+  - type: textarea
+    id: description
+    attributes:
+      label: What happened?
+      description: Please describe the issue
+    validations:
+      required: true
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected behaviour
+      description: Tell us what should have happened
+  - type: textarea
+    id: repro-steps
+    attributes:
+      label: Steps to reproduce
+      description: Tell us how to reproduce the issue
+    validations:
+      required: true
+  - type: input
+    id: aat-version
+    attributes:
+      label: Authoring tool version
+      description: What version of the Adapt authoring tool are you running?
+    validations:
+      required: true
+  - type: input
+    id: fw-version
+    attributes:
+      label: Framework version
+      description: What version of the Adapt framework are you running?
+  - type: dropdown
+    id: browsers
+    attributes:
+      label: What browsers are you seeing the problem on?
+      multiple: true
+      options:
+        - Firefox
+        - Chrome
+        - Safari
+        - Microsoft Edge
+  - type: textarea
+    id: logs
+    attributes:
+      label: Relevant log output
+      description: Please copy and paste any relevant log output. This will be automatically formatted into code, so no need for backticks.
+      render: sh

package/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1 @@
+blank_issues_enabled: false

package/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,22 @@
+name: Feature request
+description: Request a new feature
+labels: ["enhancement"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for taking the time to request a new feature in the Adapt authoring tool! The Adapt team will consider all new feature requests, but unfortunately cannot commit to every one.
+  - type: textarea
+    id: description
+    attributes:
+      label: Feature description
+      description: Please describe your feature request
+    validations:
+      required: true
+  - type: checkboxes
+    id: contribute
+    attributes:
+      label: Can you work on this feature?
+      description: If you are able to commit your own time to work on this feature, it will greatly increase the liklihood of it being implemented by the core dev team. Otherwise, it will be triaged and prioritised alongside the core team's current priorities.
+      options:
+        - label: I can contribute

package/.github/dependabot.yml

@@ -0,0 +1,11 @@
+# To get started with Dependabot version updates, you'll need to specify which
+# package ecosystems to update and where the package manifests are located.
+# Please see the documentation for all configuration options:
+# https://docs.github.com/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file
+
+version: 2
+updates:
+  - package-ecosystem: "npm" # See documentation for possible values
+    directory: "/" # Location of package manifests
+    schedule:
+      interval: "weekly"

package/.github/pull_request_template.md

@@ -0,0 +1,25 @@
+[//]: # (Please title your PR according to eslint commit conventions)
+[//]: # (See https://github.com/conventional-changelog/conventional-changelog/tree/master/packages/conventional-changelog-eslint#eslint-convention for details)
+
+[//]: # (Add a link to the original issue)
+
+[//]: # (Delete as appropriate)
+### Fix
+* A sentence describing each fix
+
+### Update
+* A sentence describing each udpate
+
+### New
+* A sentence describing each new feature
+
+### Breaking
+* A sentence describing each breaking change
+
+[//]: # (List appropriate steps for testing if needed)
+### Testing
+1. Steps for testing
+
+[//]: # (Mention any other dependencies)
+
+

package/.github/workflows/labelled_prs.yml

@@ -0,0 +1,16 @@
+name: Add labelled PRs to project
+
+on:
+  pull_request:
+    types: [ labeled ]
+
+jobs:
+  add-to-project:
+    if: ${{ github.event.label.name == 'dependencies' }}
+    name: Add to main project
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/add-to-project@v0.1.0
+        with:
+          project-url: https://github.com/orgs/adapt-security/projects/5
+          github-token: ${{ secrets.PROJECTS_SECRET }}

package/.github/workflows/new.yml

@@ -0,0 +1,19 @@
+name: Add to main project
+
+on:
+  issues:
+    types:
+      - opened
+  pull_request:
+    types:
+      - opened
+
+jobs:
+  add-to-project:
+    name: Add to main project
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/add-to-project@v0.1.0
+        with:
+          project-url: https://github.com/orgs/adapt-security/projects/5
+          github-token: ${{ secrets.PROJECTS_SECRET }}

package/adapt-authoring.json

@@ -0,0 +1,23 @@
+{
+  "module": false,
+  "documentation": {
+    "enable": true,
+    "manualIndex": "docs/index-manual.md",
+    "sourceIndex": "docs/index-backend.md",
+    "manualPages": {
+      "binscripts.md": "reference",
+      "coremodules.md": "reference",
+      "data-folder.md": "basics",
+      "customising.md": "advanced",
+      "licensing.md": "reference",
+      "temp-folder.md": "basics",
+      "writing-a-module.md": "basics",
+      "writing-core-code.md": "contributing"
+    },
+    "manualPlugins": [
+      "docs/plugins/binscripts.js",
+      "docs/plugins/coremodules.js",
+      "docs/plugins/licensing.js"
+    ]
+  }
+}

package/conf/config.schema.json

@@ -0,0 +1,23 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "isProduction": {
+      "description": "Whether this app configuration is a production environment",
+      "type": "boolean",
+      "default": true
+    },
+    "dataDir": {
+      "description": "Directory for persistant application data",
+      "type": "string",
+      "isDirectory": true,
+      "default": "$ROOT/APP_DATA/data"
+    },
+    "tempDir": {
+      "description": "Temporary directory for application data",
+      "type": "string",
+      "isDirectory": true,
+      "default": "$ROOT/APP_DATA/temp"
+    }
+  }
+}

package/docs/customising.md

@@ -0,0 +1,13 @@
+# Customising the application
+The Adapt authoring tool architecture has been designed from the ground up to support full customisation, be it in the form of adding extra self-contained pieces of functionality, or replacing/removing entire chunks of the core feature-set. It is also incredibly simple to add extra functionality that has been written by other developers.
+
+## Module security concerns
+Before using any third-party code, please be aware that any modules you choose to install have the potential to cause catastrophic problems for your server. This could include (but is not limited to):
+- Unexpectedly modifying database data
+- Transmitting personal data to external parties
+- Crashing the server
+- Erasing of entire hard-disk contents
+
+Most of these issues can be mitigated by making sure your server is correctly configured by an experienced system administrator (i.e. setting correct permissions etc.), but please be **VERY** careful when trusting third-party code.
+
+#### If in doubt, leave it out!

package/docs/data-folder.md

@@ -0,0 +1,4 @@
+# The data folder
+The data folder is used to store persistant application data and **should not in any circumstances be modified or removed**. Doing so will result in data loss and generally cause unexpected runtime issues.
+
+As a module developer, you should store any data in here which should persist between app restarts. You can make use of the `isDirectory` schema keyword to make configuration simpler for end-users. See the [schemas page](schemas-introduction#isdirectory) for more information.

package/docs/index-backend.md

@@ -0,0 +1,19 @@
+# Welcome!
+
+This is the home of the official API reference documentation for the Node.js back-end of the Adapt authoring tool  (for the front-end docs, see [this page]()).
+
+The Adapt authoring tool is a server-based user interface for authoring eLearning courses using the Adapt framework.
+
+*This documentation is auto-generated using the tools packaged with the Adapt authoring tool [core repository](https://github.com/adaptlearning/adapt-authoring).*
+
+## Contributing
+If you come across any errors or omissions in this documentation, please submit an issue on our [GitHub page](https://github.com/adaptlearning/adapt_authoring/issues).
+
+If you also have time to fix the issue, please see our [contribution guide](https://github.com/adaptlearning/adapt_framework/wiki/Contributing-code) on how to submit a fix.
+
+## Useful links
+
+- [Project website](https://www.adaptlearning.org/)
+- [GitHub project](https://github.com/adapt-security/adapt-authoring)
+- [Technical discussion forum](https://community.adaptlearning.org/mod/forum/view.php?id=4)
+- [Gitter chatrooms](https://www.adaptlearning.org/)

package/docs/index-manual.md

@@ -0,0 +1,11 @@
+![](https://www.adaptlearning.org/wp-content/uploads/2015/11/home-icon-03.png)
+
+# Adapt authoring tool
+
+## Developer guides
+
+> Handy guides and how-to information to help understand and make use of the Adapt authoring tool APIs in a practical way.
+
+[<i class="material-icons">download</i> Install](install)
+[<i class="material-icons">settings</i> Configure](configuration)
+[<i class="material-icons">flight_takeoff</i> Run](run)

package/docs/plugins/binscripts.js

@@ -0,0 +1,45 @@
+import fs from 'fs-extra';
+import { parse } from 'comment-parser';
+
+export default class BinScripts {
+  async run() {
+    this.manualFile = 'binscripts.md';
+    this.replace = { CONTENT: await this.generateMd() }
+  }
+  async generateMd() {
+    const allDeps = await Promise.all(Object.values(this.app.dependencies).map(this.processDep));
+    return allDeps
+      .reduce((m, d) => d ? m.concat(d) : m, [])
+      .sort((a,b) => a.name.localeCompare(b.name))
+      .map(d => this.dataToMd(d))
+      .join('\n');
+  }
+  async processDep({ name, bin, rootDir }) {
+    if(!bin || typeof bin === 'string') {
+      return;
+    }
+    return await Promise.all(Object.entries(bin).map(async ([scriptName, filePath]) => {
+      const data = { name: scriptName, description: 'No description provided.', moduleName: name };
+      const contents = (await fs.readFile(`${rootDir}/${filePath}`)).toString();
+      const match = contents.match(/^#!\/usr\/bin\/env node(\s*)?\/\*\*([\s\S]+?)\*\//);
+      if(match) {
+        const [{ description, tags }] = parse(match[0]);
+        const params = tags.reduce((m,t) => {
+          if(t.tag === 'param') m.push({ name: t.name, description: t.description });
+          return m;
+        }, []);
+        data.description = description;
+        if(params.length) data.params = params;
+      }
+      return data;
+    }));
+  }
+  dataToMd({ name, description, moduleName, params }) {
+    let content = `<h2 class="script" id="${name}">${name} <span class="module">from ${moduleName}</span></h2>`
+    content += `<div class="details"><p class="description">${description}</p>`;
+    if(params) {
+      content += `<p><b>Params</b><ul>${params.reduce((s,p) => `${s}<li><code>${p.name}</code> ${p.description}</li>`, '')}</ul></p>`;
+    }
+    return content;
+  }
+}

package/docs/plugins/binscripts.md

@@ -0,0 +1,33 @@
+# Bin scripts
+The authoring tool core bundle includes a number of useful scripts which make setting up and using the tool more straightforward. This page outlines these scripts and how they function, along with any parameters they may expect.
+
+## Running a bin script
+
+To run a bin script, you must use the npx command which comes bundled with npm which and used to execute node modules. Scripts are run using the following format: **npx** followed by the **script name**, with any **flags or parameters** coming at the end.
+
+As an example, a task called `at-myscript` may be run like so:
+
+> We prefix any core authoring tool scripts `at-` for transparency (as an added bonus they also come towards the top of the `bin/` folder in `node_modules`!).
+
+```bash
+npx at-myscript --test=true
+```
+
+See the [official npx docs](https://docs.npmjs.com/cli/v7/commands/npx) for more information on npx.
+
+{{{CONTENT}}}
+
+<style>
+  h2.script {
+    margin-bottom: 5px;   
+  }
+  h2.script .module {
+    font-weight: 300;
+    font-size: 16px;
+    vertical-align: middle;
+  }
+  p.description,
+  .details ul {
+    margin: 0;   
+  }
+</style>

package/docs/plugins/coremodules.js

@@ -0,0 +1,15 @@
+export default class CoreModules {
+  async run() {
+    this.manualFile = 'coremodules.md';
+    this.replace = {
+      VERSION: this.app.pkg.version,
+      MODULES: this.generateMd()
+    };
+  }
+  generateMd() {
+    return Object.keys(this.app.dependencies).sort().reduce((s, name) => {
+      const { version, description, homepage } = this.app.dependencies[name];
+      return s += `\n| ${homepage ? `[${name}](${homepage})` : name} | ${version} | ${description} |`;
+    }, '| Name | Version | Description |\n| - | :-: | - |');
+  }
+}

package/docs/plugins/coremodules.md

@@ -0,0 +1,4 @@
+# Core module list
+The following modules are included in Adapt authoring v{{{VERSION}}} core package of modules, and are supported by the core dev team.
+
+{{{MODULES}}}

package/docs/plugins/licensing.js

@@ -0,0 +1,119 @@
+import fetch from 'node-fetch'
+import fs from 'fs/promises'
+import { glob } from 'glob'
+import path from 'path'
+
+export default class Licensing {
+  async run () {
+    this.manualFile = 'licensing.md'
+    this.licenses = {}
+    this.dependencies = []
+
+    await this.loadDependencies()
+
+    const adaptLicense = this.licenses[JSON.parse((await fs.readFile(path.resolve(this.config.app.rootDir, 'package.json'))).toString()).license]
+
+    this.replace = {
+      ADAPT_LICENSE: adaptLicense.name,
+      ADAPT_LICENSE_TEXT: adaptLicense.description,
+      ADAPT_LICENSE_PERMISSIONS: adaptLicense.permissions.map(p => `- ${this.permissionsMap(p)}`).join('\n'),
+      LICENSES: await this.generateLicenseSummaryMd(),
+      LICENSE_DETAILS: await this.generateLicenseDetailsMd(),
+      MODULES: await this.generateMd(),
+      MODULE_COUNT: this.dependencies.length,
+      UNKNOWN_LICENSES: this.generateUnknownLicenseMd()
+    }
+  }
+
+  async loadDependencies () {
+    const files = await glob('node_modules/*/package.json')
+    await Promise.all(files.map(async f => {
+      const packageName = path.dirname(f).replace('node_modules/', '')
+      if (packageName.startsWith('adapt-authoring')) {
+        return
+      }
+      const pkg = JSON.parse((await fs.readFile(f)).toString())
+      this.dependencies.push(pkg)
+      await this.storeLicenseData(pkg)
+    }))
+  }
+
+  async storeLicenseData (pkg) {
+    if (!pkg.license) {
+      return
+    }
+    if (typeof pkg.license === 'object') {
+      pkg.license = pkg.license.type
+    }
+    const licenses = pkg.license.replace('(', '').replace(')', '').split(/\s(?:AND|OR)\s/)
+    for (let l of licenses) {
+      l = this.licenseNameMap(l)
+      if (this.licenses[l]) {
+        return this.licenses[l].count++
+      }
+      this.licenses[l] = { count: 1 }
+      try {
+        const { GITHUB_USER, GITHUB_TOKEN } = process.env
+        const res = await fetch(`https://api.github.com/licenses/${l.toLowerCase()}`, { headers: { Authorization: `Basic ${Buffer.from(`${GITHUB_USER}:${GITHUB_TOKEN}`).toString('base64')}` } })
+        if (res.status === 200) Object.assign(this.licenses[l], await res.json())
+        if (res.status > 299) console.error(`Failed to fetch '${l}' license: (${res.status}) ${(await res.json()).message}`)
+      } catch (e) {
+        console.error(e)
+      }
+    }
+  }
+
+  licenseNameMap (name) {
+    switch (name) {
+      case 'Apache2':
+        return 'Apache-2.0'
+      case 'GPL-3.0-or-later':
+        return 'GPL-3.0'
+      default:
+        return name
+    }
+  }
+
+  permissionsMap (p) {
+    return `${p[0].toUpperCase()}${p.slice(1).replaceAll('-', ' ')}`
+  }
+
+  async generateLicenseSummaryMd () {
+    let md = '| License | Modules using license |\n| - | :-: |\n'
+
+    Object.keys(this.licenses)
+      .sort()
+      .forEach(l => md += `| ${l} | ${this.licenses[l].count} |\n`)
+
+    return md
+  }
+
+  async generateLicenseDetailsMd () {
+    let md = ''
+    Object.entries(this.licenses).forEach(([key, { name, spdx_id, description, body, permissions }]) => {
+      if (!name) return
+      md += '<details>\n'
+      md += `<summary>${name} (${spdx_id})</summary>\n`
+      md += `<p>${description}</p>\n`
+      md += `<p>This license allows the following:\n<ul>${permissions.map(p => `<li>${this.permissionsMap(p)}</li>`).join('\n')}</ul></p>\n`
+      md += '<p>The original license text is as follows:</p>\n'
+      md += `<pre>${body}</pre>\n`
+      md += '</details>\n\n'
+    })
+    return md
+  }
+
+  generateUnknownLicenseMd () {
+    const unknowns = []
+    Object.entries(this.licenses).forEach(([key, { name }]) => !name && unknowns.push(key))
+    if (unknowns.length) {
+      return `No information is held on the following licenses, please do your own research to dermine their suitability.\n\n${unknowns.map(u => `- ${u}`).join('\n')}\n`
+    }
+  }
+
+  async generateMd () {
+    let md = '<tr><th>Name</th><th>Version</th><th>License</th><th>Description</th></tr>\n'
+    this.dependencies.forEach(pkg => md += `<tr><td>${pkg.homepage ? `<a href="${pkg.homepage}" target="_blank">${pkg.name}</a>` : pkg.name}</td><td>${pkg.version}</td><td>${pkg.license}</td><td>${pkg.description}</tr>\n`)
+    return `<details>\n<summary>Module dependency list</summary>\n<table>${md}</table>\n</details>`
+  }
+}

package/docs/plugins/licensing.md

@@ -0,0 +1,36 @@
+# Licensing
+When building a business around an open-source product, it is crucially important to understand how that code is licensed, and how those licenses apply to your business. This page aims to clarify which licenses apply to the Adapt authoring tool core package, and gives details on how those licenses may affect its use. **This page is not intended to provide legal advice; qualified legal professionals should be consulted to advise on how your own business may be affected.**
+
+The Adapt authoring tool core package is licensed under the **{{{ADAPT_LICENSE}}}**, which is summarised as follows:
+
+_{{{ADAPT_LICENSE_TEXT}}}_
+
+The {{{ADAPT_LICENSE}}} allows the following:
+
+{{{ADAPT_LICENSE_PERMISSIONS}}}
+
+You can view more information on the {{{ADAPT_LICENSE}}} license in [License details](#license-details).
+
+## Third-party dependencies
+
+The Adapt authoring tool makes use of {{{MODULE_COUNT}}} third-party Node.js modules. These include transient dependencies (i.e. dependencies not directly imported by the authoring tool code, but used by its dependencies). Each module has its own license which must be taken into consideration when building a business around Adapt products. 
+
+The below table lists all licenses used, as well as the number of dependencies which use each license.
+
+{{{LICENSES}}}
+
+## License details
+
+Listed below are all licenses used by the Adapt authoring tool and its dependencies. Click each heading to view detailed information, including the full licenses themselves.
+
+{{{LICENSE_DETAILS}}}
+
+{{{UNKNOWN_LICENSES}}}
+
+### Full dependency list
+
+Click the heading below to view a complete list of all third-party dependencies.
+
+{{{MODULES}}}
+
+## Commonly asked questions

package/docs/temp-folder.md

@@ -0,0 +1,12 @@
+# The temp folder
+The `temp` folder (note: this path will vary depending on your local configuration) is, as the name suggests, a temporary store for files used at runtime by the application. These files can be related to any number of things such as file uploads, course builds, documentation builds and so on.
+
+## Using the temp folder
+As a module developer, it is recommended that you store any temporary files needed by your module in here. Please be aware however, that due to its non-permanent nature, any data stored in the temp folder has the potential to be removed at any time. We therefore recommend running relevant checks during the startup of your module, and reinitialise any missing files at that point.
+
+It is safe to assume that the temp folder will *not* be removed while the app is running; anyone choosing to do so should expect fatal errors.
+
+## Removing the temp folder
+It is perfectly safe to remove the temp folder. You may wish to do this in the event of low disk space, before an update, or even as a regular housekeeping task.
+
+> If you do remove the temp folder, this must be done while the app is stopped, or your users may encounter errors while using the app. Restarting the application will ensure that any vital files are reinstated.