adapt-cli 2.1.13 → 3.0.6

package/json/help-install.json

@@ -1,10 +1,10 @@
-{
-    "command": "install",
-    "description": "Install plugins according to the Adapt manifest (adapt.json). You can also specify which plugins to install as arguments. When specifying arguments you can provide an optional semantic version (semver). If a semver is not given the command will attempt to install the latest compatible version. Add the --dry-run option to simulate an installation without making any changes. Add the --compatible option to override any given semvers: the command will attempt to install the latest compatible version for all requested plugins.",
-    "usage": [
-        "install [--dry-run, --compatible]",
-        "install <plugin-name>",
-        "install <plugin-name>#<semver>",
-        "install <plugin-name>@<semver>"
-    ]
-}
+{
+    "command": "install",
+    "description": "Install plugins according to the Adapt manifest (adapt.json). You can also specify which plugins to install as arguments. When specifying arguments you can provide an optional semantic version (semver). If a semver is not given the command will attempt to install the latest compatible version. Add the --dry-run option to simulate an installation without making any changes. Add the --compatible option to override any given semvers: the command will attempt to install the latest compatible version for all requested plugins.",
+    "usage": [
+        "install [--dry-run, --compatible]",
+        "install <plugin-name>",
+        "install <plugin-name>#<semver>",
+        "install <plugin-name>@<semver>"
+    ]
+}

package/json/help-ls.json

@@ -1,7 +1,7 @@
-{
-    "command": "ls",
-    "description": "List the plugin(s) name with version number mentioned in adapt.json file.",
-    "usage": [
-        "ls"
-    ]
-}
+{
+    "command": "ls",
+    "description": "List the plugin(s) name with version number mentioned in adapt.json file.",
+    "usage": [
+        "ls"
+    ]
+}

package/json/help-register.json

@@ -1,7 +1,7 @@
-{
-    "command": "register",
-    "description": "Register a plugin to adapt's remote registry by reading bower.json file. Check folowing URL for more detail - https://github.com/adaptlearning/adapt_framework/wiki/Registering-a-plugin",
-    "usage": [
-        "register"
-    ]
-}
+{
+    "command": "register",
+    "description": "Register a plugin to adapt's remote registry by reading bower.json file. Check folowing URL for more detail - https://github.com/adaptlearning/adapt_framework/wiki/Registering-a-plugin",
+    "usage": [
+        "register"
+    ]
+}

package/json/help-rename.json

@@ -1,7 +1,7 @@
-{
-    "command": "rename",
-    "description": "Unregister a plugin at Adapt's remote registry. Specify as two arguments the current name of the plugin to be renamed and a new name. Please note that you must authenticate with GitHub to unregister and must be a collaborator on the endpoint registered with the plugin or a collaborator on the Adapt framework. Access to GitHub is for authentication only.",
-    "usage": [
-        "rename <plugin name> <new plugin name>"
-    ]
-}
+{
+    "command": "rename",
+    "description": "Unregister a plugin at Adapt's remote registry. Specify as two arguments the current name of the plugin to be renamed and a new name. Please note that you must authenticate with GitHub to unregister and must be a collaborator on the endpoint registered with the plugin or a collaborator on the Adapt framework. Access to GitHub is for authentication only.",
+    "usage": [
+        "rename <plugin name> <new plugin name>"
+    ]
+}

package/json/help-search.json

@@ -1,8 +1,8 @@
-{
-    "command": "search",
-    "description": "List out all the plugin(s) in adapt's remote registry or could also search a plugin with supplied partial name.",
-    "usage": [
-        "search",
-        "search <plugin-name>"
-    ]
-}
+{
+    "command": "search",
+    "description": "List out all the plugin(s) in adapt's remote registry or could also search a plugin with supplied partial name.",
+    "usage": [
+        "search",
+        "search <plugin-name>"
+    ]
+}

package/json/help-uninstall.json

@@ -1,7 +1,7 @@
-{
-    "command": "uninstall",
-    "description": "Remove a local plugin by its name.",
-    "usage": [
-        "uninstall <plugin-name>"
-    ]
-}
+{
+    "command": "uninstall",
+    "description": "Remove a local plugin by its name.",
+    "usage": [
+        "uninstall <plugin-name>"
+    ]
+}

package/json/help-unregister.json

@@ -1,8 +1,8 @@
-{
-    "command": "unregister",
-    "description": "Unregister a plugin at Adapt's remote registry. This command can be run without arguments in a directory which contains the bower.json file for the plugin to be unregistered. Alternatively, specify the name of the plugin as a single argument. Please note that you must authenticate with GitHub to unregister and must be a collaborator on the endpoint registered with the plugin or a collaborator on the Adapt framework. Access to GitHub is for authentication only.",
-    "usage": [
-        "unregister",
-        "unregister <plugin name>"
-    ]
-}
+{
+    "command": "unregister",
+    "description": "Unregister a plugin at Adapt's remote registry. This command can be run without arguments in a directory which contains the bower.json file for the plugin to be unregistered. Alternatively, specify the name of the plugin as a single argument. Please note that you must authenticate with GitHub to unregister and must be a collaborator on the endpoint registered with the plugin or a collaborator on the Adapt framework. Access to GitHub is for authentication only.",
+    "usage": [
+        "unregister",
+        "unregister <plugin name>"
+    ]
+}

package/json/help-update.json

@@ -1,12 +1,12 @@
-{
-    "command": "update",
-    "description": "Update plugins to their latest compatible version. You can also specify which plugins to update as arguments. When specifying arguments you can provide an optional semantic version (semver). Add the --check option for a summary of available updates for the given plugin(s). When using this option no changes are made. Ensure that there is no bower.json file in your project directory.",
-    "usage": [
-        "update [--check]",
-        "update <group> [<group> ..] where <group> is one of [components|extensions|menu|theme|all]",
-        "update <plugin-name>",
-        "update <plugin-name>#<semver>",
-        "update <plugin-name>@<semver>",
-        "update <target> [<target> ..] where target is the name of a plugin or group"
-    ]
-}
+{
+    "command": "update",
+    "description": "Update plugins to their latest compatible version. You can also specify which plugins to update as arguments. When specifying arguments you can provide an optional semantic version (semver). Add the --check option for a summary of available updates for the given plugin(s). When using this option no changes are made. Ensure that there is no bower.json file in your project directory.",
+    "usage": [
+        "update [--check]",
+        "update <group> [<group> ..] where <group> is one of [components|extensions|menu|theme|all]",
+        "update <plugin-name>",
+        "update <plugin-name>#<semver>",
+        "update <plugin-name>@<semver>",
+        "update <target> [<target> ..] where target is the name of a plugin or group"
+    ]
+}

package/json/help-version.json

@@ -1,7 +1,7 @@
-{
-    "command": "version",
-    "description": "Display version of adapt-cli.",
-    "usage": [
-        "version"
-    ]
-}
+{
+    "command": "version",
+    "description": "Display version of adapt-cli.",
+    "usage": [
+        "version"
+    ]
+}

package/json/help.json

@@ -1,19 +1,19 @@
-{
-    "usage": [
-        "<command>"
-    ],
-    "commands": {
-        "create":          "Create a new Adapt course or plugin",
-        "devinstall":      "Get the framework and plugins as Git repository",
-        "help":            "List out the commands available with adapt-cli",
-        "install":         "Install plugin(s) within the Adapt course directory",
-        "ls":              "List all the plugin names mentioned in adapt.json",
-        "rename":          "Rename a plugin at the Adapt remote registry",
-        "register":        "Register a plugin with the Adapt remote registry",
-        "search":          "List/Search for plugin(s) at the Adapt remote registry",
-        "uninstall":       "Remove a local plugin",
-        "unregister":      "Unregister a plugin from the Adapt remote registry",
-        "update":          "Update one or more plugins",
-        "version":         "Display version of adapt-cli"
-    }
-}
+{
+    "usage": [
+        "<command>"
+    ],
+    "commands": {
+        "create":          "Create a new Adapt course or plugin",
+        "devinstall":      "Get the framework and plugins as Git repository",
+        "help":            "List out the commands available with adapt-cli",
+        "install":         "Install plugin(s) within the Adapt course directory",
+        "ls":              "List all the plugin names mentioned in adapt.json",
+        "rename":          "Rename a plugin at the Adapt remote registry",
+        "register":        "Register a plugin with the Adapt remote registry",
+        "search":          "List/Search for plugin(s) at the Adapt remote registry",
+        "uninstall":       "Remove a local plugin",
+        "unregister":      "Unregister a plugin from the Adapt remote registry",
+        "update":          "Update one or more plugins",
+        "version":         "Display version of adapt-cli"
+    }
+}

package/lib/api.js

@@ -0,0 +1,260 @@
+import http from 'http' // api http import, to hold open process for testing
+import { ADAPT_FRAMEWORK } from './util/constants.js'
+import {
+  build,
+  download,
+  erase,
+  getLatestVersion,
+  npmInstall,
+  deleteSrcCourse,
+  deleteSrcCore
+} from './integration/AdaptFramework.js'
+import {
+  install,
+  uninstall,
+  update,
+  schemas
+} from './integration/PluginManagement.js'
+import Plugin from './integration/Plugin.js'
+import Project from './integration/Project.js'
+import fs from 'fs-extra'
+import async from 'async'
+
+// TODO: api, check no interactivity, should be sorted, will fail silently if it absolutely cannot do what you've asked
+// TODO: api, console and error output, error on fail when isInteractive: false? or something else? return Targets?
+// TODO: api, figure out error translations, should probably error with codes?
+
+class API {
+  /**
+   * Installs a clean copy of the framework
+   * @param {Object} options
+   * @param {string} [options.version=null] Specific version of the framework to install
+   * @param {string} [options.repository] URL to github repo
+   * @param {string} [options.cwd=process.cwd()] Directory to install into
+   * @return {Promise}
+   */
+  async installFramework ({
+    version = null,
+    repository = ADAPT_FRAMEWORK,
+    cwd = process.cwd()
+  } = {}) {
+    if (!version) version = await getLatestVersion({ repository })
+    await erase({
+      isInteractive: false,
+      cwd
+    })
+    await download({
+      repository,
+      branch: version,
+      cwd
+    })
+    await deleteSrcCourse({
+      cwd
+    })
+    await deleteSrcCore({
+      cwd
+    })
+    await npmInstall({
+      cwd
+    })
+  }
+
+  /**
+   * @param {Object} options
+   * @param {Object} [options.repository=ADAPT_FRAMEWORK] The github repository url
+   * @returns {string}
+   */
+  async getLatestFrameworkVersion ({
+    repository = ADAPT_FRAMEWORK
+  } = {}) {
+    return getLatestVersion({ repository })
+  }
+
+  /**
+   * Runs build for a current course
+   * @param {Object} options
+   * @param {boolean} [options.sourceMaps=false] Whether to run the build with sourcemaps
+   * @param {boolean} [options.checkJSON=false] Whether to run without checking the json
+   * @param {boolean} [options.cache=true] Whether to clear build caches
+   * @param {string} [options.outputDir="build/"] Root path of the framework installation
+   * @param {string} [options.cachePath="build/.cache"] Path of compilation cache file
+   * @param {string} [options.cwd=process.cwd()] Root path of the framework installation
+   * @return {Promise}
+   */
+  async buildCourse ({
+    sourceMaps = false,
+    checkJSON = false,
+    cache = true,
+    outputDir = null,
+    cachePath = './build/.cache',
+    cwd = process.cwd()
+  } = {}) {
+    await build({
+      sourceMaps,
+      checkJSON,
+      cache,
+      cwd,
+      outputDir,
+      cachePath
+    })
+  }
+
+  /**
+   * Installs multiple plugins
+   * Can install from source folder or bower registry
+   * @param {Object} options
+   * @param {[string]} [options.plugins=null] An array with name@version or name@path strings
+   * @param {string} [options.cwd=process.cwd()] Root path of the framework installation
+   * @return {Promise<[Target]>}
+   */
+  async installPlugins ({
+    plugins = null,
+    cwd = process.cwd()
+  } = {}) {
+    return await install({
+      plugins,
+      isInteractive: false,
+      cwd
+    })
+  }
+
+  /**
+   * Uninstalls multiple plugins
+   * @param {Object} options
+   * @param {[string]} [options.plugins=null] An array with name@version or name@path strings
+   * @param {string} [options.cwd=process.cwd()] Root path of the framework installation
+   * @return {Promise<[Target]>}
+   */
+  async uninstallPlugins ({
+    plugins = null,
+    cwd = process.cwd()
+  } = {}) {
+    return await uninstall({
+      plugins,
+      isInteractive: false,
+      cwd
+    })
+  }
+
+  /**
+   * Updates multiple plugins
+   * Can install from source folder or bower registry
+   * @param {Object} options
+   * @param {[string]} [options.plugins=null] An array with name@version or name@path strings
+   * @param {string} [options.cwd=process.cwd()] Root path of the framework installation
+   * @return {Promise<[Target]>}
+   */
+  async updatePlugins ({
+    plugins = null,
+    cwd = process.cwd()
+  } = {}) {
+    return await update({
+      plugins,
+      isInteractive: false,
+      cwd
+    })
+  }
+
+  /**
+   * Retrieves all schemas defined in the project
+   * Clears schema cache
+   * @param {string} [options.cwd=process.cwd()] Root path of the framework installation
+   * @return {Promise<[string]>} Resolves with array of JSON schema filepaths
+   */
+  async getSchemaPaths ({
+    cwd = process.cwd()
+  } = {}) {
+    this._schemaPaths = await schemas({ cwd })
+    this._schemas = {}
+    return this._schemaPaths
+  }
+
+  /**
+   * Retrieves named schema
+   * Caches schemas for subsequent use
+   * Call getSchemaPaths to reset cache
+   * @param {string} options.name Schema filepath as returned from getSchemaPaths
+   * @return {Promise<Object>} Resolves with the JSON schema contents
+   */
+  async getSchema ({
+    name
+  } = {}) {
+    if (!this._schemaPaths) return new Error('Please run getSchemaPaths first')
+    if (!fs.existsSync(name) || !this._schemaPaths.includes(name)) throw new Error(`Schema does not exist: ${name}`)
+    return (this._schemas[name] = this._schemas[name] ?? await fs.readJSON(name))
+  }
+
+  /**
+   * Returns all installed plugins
+   * @return {Promise<[Plugin]>}
+   */
+  async getInstalledPlugins ({
+    cwd = process.cwd()
+  } = {}) {
+    const project = new Project({ cwd })
+    if (!project.isAdaptDirectory) throw new Error(`Not in an adapt folder at: ${cwd}`)
+    const installedPlugins = await project.getInstalledPlugins()
+    for (const plugin of installedPlugins) {
+      await plugin.fetchProjectInfo()
+    }
+    return installedPlugins
+  }
+
+  /**
+   * Gets the update information for installed and named plugins
+   * @param {Object} options
+   * @param {[string]} [options.plugins=null] An y of plugin names (if not specified, all plugins are checked)
+   * @param {string} [options.cwd=process.cwd()] Root path of the framework installation
+   * @return {Promise<[Plugin]>}
+   */
+  async getPluginUpdateInfos ({
+    plugins = null,
+    cwd = process.cwd()
+  } = {}) {
+    /** @type {Project} */
+    const project = new Project({ cwd })
+    if (!project.isAdaptDirectory) throw new Error(`Not in an adapt folder at: ${cwd}`)
+    const frameworkVersion = project.version
+    /** @type {[Plugin]} */
+    const installedPlugins = await project.getInstalledPlugins()
+    const filteredPlugins = !plugins?.length
+      ? installedPlugins
+      : plugins
+        .map(name => installedPlugins.find(plugin => plugin.packageName === name))
+        .filter(Boolean)
+    await async.eachOfLimit(filteredPlugins, 8, async plugin => {
+      await plugin.fetchProjectInfo()
+      await plugin.fetchBowerInfo()
+      await plugin.findCompatibleVersion(frameworkVersion)
+    })
+    return filteredPlugins
+  }
+
+  /**
+   * Returns an object representing the plugin at the path specified
+   * @returns {Plugin}
+   */
+  async getPluginFromPath ({
+    pluginPath,
+    cwd = null
+  } = {}) {
+    const project = cwd ? new Project({ cwd }) : null
+    return Plugin.fromPath({ pluginPath, project })
+  }
+}
+
+const api = new API()
+export default api
+
+// debugging
+if (process.argv.includes('--debug-wait')) {
+  // http server to hold open process for testing
+  const a = http.createServer((request, response) => {
+    response.writeHead(200, { 'Content-Type': 'text/plain' })
+    response.end('test', 'utf-8')
+  })
+  a.listen(999)
+  // make api global to debug more easily
+  global.api = api
+  console.log('API Ready')
+}

package/lib/cli.js

@@ -1,52 +1,69 @@
-var path = require('path'),
-    _ = require('lodash'),
-    CommandParser = require('./CommandParser'),
-    AdaptConsoleApplication = require('./AdaptConsoleApplication'),
-    stdoutRenderer = {
-        log: _.bind(console.log, console),
-        write: _.bind(process.stdout.write, process.stdout)
-    };
-
-function withPackage(pack) {
-    this.pkg = pack || require(path.join(__dirname, '..', 'package.json'));
-    return this;
-}
-
-function withOptions(argv) {
-    argv = argv || process.argv;
-    this.command = new CommandParser(argv);
-    return this;
-}
-
-function execute() {
-    var commands = require('./commands'),
-        app = new AdaptConsoleApplication(commands, stdoutRenderer);
-
-    app.do(this.command, function (err) {
-        process.exit(err ? 1: 0);
-    });
-}
-
-function getApi() {
-    var commands = require('./commands');
-    var apiCommands = {};
-
-    _.each(commands, function(command, commandName) {
-        var prefix = 'api';
-        if (commandName.startsWith(prefix)) {
-            apiCommands[commandName.split(prefix)[1]] = command;
-        }
-    });
-
-    return {
-        commands:apiCommands
-    }
-}
-
-module.exports = {
-    command: null,
-    withOptions: withOptions,
-    withPackage: withPackage,
-    execute: execute,
-    api: getApi()
-};
+import authenticate from './commands/authenticate.js'
+import create from './commands/create.js'
+import devinstall from './commands/devinstall.js'
+import help from './commands/help.js'
+import install from './commands/install.js'
+import ls from './commands/ls.js'
+import register from './commands/register.js'
+import rename from './commands/rename.js'
+import search from './commands/search.js'
+import uninstall from './commands/uninstall.js'
+import unregister from './commands/unregister.js'
+import update from './commands/update.js'
+import version from './commands/version.js'
+import logger from './logger.js'
+
+const commands = {
+  authenticate,
+  create,
+  devinstall,
+  help,
+  install,
+  ls,
+  register,
+  rename,
+  search,
+  uninstall,
+  unregister,
+  update,
+  version
+}
+
+const translationTable = [
+  { pattern: /^-v$|^--version$/i, replacement: 'version' },
+  { pattern: /^upgrade$/i, replacement: 'update' }
+]
+
+class CLI {
+  withOptions (argv = process.argv || ['node', 'path']) {
+    const parameters = argv.slice(2).map(param => {
+      const translation = translationTable.find(item => item.pattern.test(param))
+      return translation ? translation.replacement : param
+    })
+    const name = parameters.length
+      ? String.prototype.toLowerCase.call(parameters.shift())
+      : ''
+    this.command = {
+      name,
+      parameters
+    }
+    return this
+  }
+
+  async execute () {
+    try {
+      if (!commands[this.command.name]) {
+        const e = new Error(`Unknown command "${this.command.name}", please check the documentation.`)
+        logger?.log(e.message)
+        throw e
+      }
+      const commandArguments = [logger].concat(this.command.parameters)
+      await commands[this.command.name](...commandArguments)
+    } catch (err) {
+      console.error(err)
+      process.exit(err ? 1 : 0)
+    }
+  }
+}
+
+export default new CLI()

package/lib/commands/authenticate.js

@@ -0,0 +1,18 @@
+import chalk from 'chalk'
+import { authenticate as pluginAuthenticate } from '../integration/PluginManagement.js'
+
+export default async function authenticate (logger, ...args) {
+  // strip flags
+  args = args.filter(arg => !String(arg).startsWith('--'))
+  try {
+    const confirmation = await pluginAuthenticate({
+      logger,
+      cwd: process.cwd(),
+      pluginName: args[0]
+    })
+    const { username, type, pluginName } = confirmation
+    logger?.log(chalk.green(`${username} authenticated as ${type} for ${pluginName}`))
+  } catch (err) {
+    logger?.error('Authentication failed')
+  }
+}