libdragon 10.8.0 → 10.8.1

package/modules/actions/start.js

@@ -11,11 +11,11 @@ const {
 
 /**
  * Create a new container
+ * @param {import('../project-info').LibdragonInfo} libdragonInfo
  */
 const initContainer = async (libdragonInfo) => {
   let newId;
   try {
-    // Create a new container
     log('Creating new container...');
     newId = (
       await spawnProcess('docker', [
@@ -75,6 +75,9 @@ const initContainer = async (libdragonInfo) => {
   return newId;
 };
 
+/**
+ * @param {import('../project-info').LibdragonInfo} libdragonInfo
+ */
 const start = async (libdragonInfo) => {
   const running =
     libdragonInfo.containerId &&
@@ -99,14 +102,18 @@ const start = async (libdragonInfo) => {
   return id;
 };
 
-module.exports = {
+module.exports = /** @type {const} */ ({
   name: 'start',
+  /**
+   * @param {import('../project-info').LibdragonInfo} libdragonInfo
+   */
   fn: async (libdragonInfo) => {
     const containerId = await start(libdragonInfo);
     print(containerId);
     return { ...libdragonInfo, containerId };
   },
   start,
+  forwardsRestParams: false,
   usage: {
     name: 'start',
     summary: 'Start the container for current project.',
@@ -114,4 +121,4 @@ module.exports = {
 
       Must be run in an initialized libdragon project.`,
   },
-};
+});

package/modules/actions/stop.js

@@ -2,6 +2,9 @@ const { spawnProcess } = require('../helpers');
 
 const { checkContainerRunning } = require('./utils');
 
+/**
+ * @param {import('../project-info').LibdragonInfo} libdragonInfo
+ */
 const stop = async (libdragonInfo) => {
   const running =
     libdragonInfo.containerId &&
@@ -14,9 +17,10 @@ const stop = async (libdragonInfo) => {
   return libdragonInfo;
 };
 
-module.exports = {
+module.exports = /** @type {const} */ ({
   name: 'stop',
   fn: stop,
+  forwardsRestParams: false,
   usage: {
     name: 'stop',
     summary: 'Stop the container for current project.',
@@ -24,4 +28,4 @@ module.exports = {
 
       Must be run in an initialized libdragon project.`,
   },
-};
+});

package/modules/actions/update-and-start.js

@@ -2,6 +2,9 @@ const { log } = require('../helpers');
 const { updateImage, destroyContainer } = require('./utils');
 const { start } = require('./start');
 
+/**
+ * @param {import('../project-info').LibdragonInfo} libdragonInfo
+ */
 async function syncImageAndStart(libdragonInfo) {
   const oldImageName = libdragonInfo.imageName;
   const imageName = libdragonInfo.options.DOCKER_IMAGE ?? oldImageName;

package/modules/actions/update.js

@@ -3,6 +3,9 @@ const { LIBDRAGON_GIT, LIBDRAGON_BRANCH } = require('../constants');
 const { runGitMaybeHost, installDependencies } = require('./utils');
 const { syncImageAndStart } = require('./update-and-start');
 
+/**
+ * @param {import('../project-info').LibdragonInfo} info
+ */
 const update = async (info) => {
   info = await syncImageAndStart(info);
 
@@ -33,9 +36,10 @@ const update = async (info) => {
   await installDependencies(info);
 };
 
-module.exports = {
+module.exports = /** @type {const} */ ({
   name: 'update',
   fn: update,
+  forwardsRestParams: false,
   usage: {
     name: 'update',
     summary: 'Update libdragon and do an install.',
@@ -44,4 +48,4 @@ module.exports = {
       Must be run in an initialized libdragon project.`,
     group: ['docker'],
   },
-};
+});

package/modules/actions/utils.js

@@ -21,6 +21,9 @@ const {
 const { dockerHostUserParams } = require('./docker-utils');
 const { installNPMDependencies } = require('./npm-utils');
 
+/**
+ * @param {import('../project-info').LibdragonInfo} libdragonInfo
+ */
 const installDependencies = async (libdragonInfo) => {
   const buildScriptPath = path.join(
     libdragonInfo.root,
@@ -51,9 +54,8 @@ const installDependencies = async (libdragonInfo) => {
 /**
  * Downloads the given docker image. Returns false if the local image is the
  * same, new image name otherwise.
- * @param libdragonInfo
- * @param newImageName
- * @returns false | string
+ * @param {import('../project-info').LibdragonInfo} libdragonInfo
+ * @param {string} newImageName
  */
 const updateImage = async (libdragonInfo, newImageName) => {
   // Will not take too much time if already have the same
@@ -90,6 +92,9 @@ const updateImage = async (libdragonInfo, newImageName) => {
   return newImageName;
 };
 
+/**
+ * @param {import('../project-info').LibdragonInfo} libdragonInfo
+ */
 const destroyContainer = async (libdragonInfo) => {
   if (libdragonInfo.containerId) {
     await spawnProcess('docker', [
@@ -110,6 +115,14 @@ const destroyContainer = async (libdragonInfo) => {
  * Invokes host git with provided params. If host does not have git, falls back
  * to the docker git, with the nix user set to the user running libdragon.
  */
+
+/**
+ *
+ * @param {import('../project-info').LibdragonInfo} libdragonInfo
+ * @param {string[]} params
+ * @param {import('../helpers').SpawnOptions} options
+ * @returns
+ */
 async function runGitMaybeHost(libdragonInfo, params, options = {}) {
   assert(
     libdragonInfo.vendorStrategy !== 'manual',
@@ -143,6 +156,9 @@ async function runGitMaybeHost(libdragonInfo, params, options = {}) {
   }
 }
 
+/**
+ * @param {import('../project-info').LibdragonInfo} libdragonInfo
+ */
 async function checkContainerAndClean(libdragonInfo) {
   const id =
     libdragonInfo.containerId &&
@@ -169,6 +185,9 @@ async function checkContainerAndClean(libdragonInfo) {
   return id ? libdragonInfo.containerId : undefined;
 }
 
+/**
+ * @param {string} containerId
+ */
 async function checkContainerRunning(containerId) {
   const running = (
     await spawnProcess('docker', [
@@ -181,6 +200,9 @@ async function checkContainerRunning(containerId) {
   return running ? containerId : undefined;
 }
 
+/**
+ * @param {import('../project-info').LibdragonInfo} libdragonInfo
+ */
 async function initGitAndCacheContainerId(libdragonInfo) {
   // If there is managed vendoring, make sure we have a git repo. `git init` is
   // safe anyways...

package/modules/actions/version.js

@@ -5,13 +5,13 @@ const printVersion = async () => {
   log(`libdragon-cli v${version}`);
 };
 
-module.exports = {
+module.exports = /** @type {const} */ ({
   name: 'version',
   fn: printVersion,
-  mustHaveProject: false,
+  forwardsRestParams: false,
   usage: {
     name: 'version',
     summary: 'Display cli version.',
     description: `Displays currently running cli version.`,
   },
-};
+});

package/modules/constants.js

@@ -1,4 +1,4 @@
-module.exports = {
+module.exports = /** @type {const} */ ({
   DOCKER_HUB_IMAGE: 'ghcr.io/dragonminded/libdragon:latest',
   LIBDRAGON_GIT: 'https://github.com/DragonMinded/libdragon',
   LIBDRAGON_BRANCH: 'trunk',
@@ -9,6 +9,8 @@ module.exports = {
   CONFIG_FILE: 'config.json',
   DEFAULT_STRATEGY: 'submodule',
 
+  ACCEPTED_STRATEGIES: ['submodule', 'subtree', 'manual'],
+
   // cli exit codes
   STATUS_OK: 0,
   STATUS_ERROR: 1,
@@ -16,4 +18,4 @@ module.exports = {
   STATUS_VALIDATION_ERROR: 4,
 
   IMAGE_FILE: 'docker-image', // deprecated
-};
+});

package/modules/helpers.js

@@ -6,31 +6,86 @@ const { spawn } = require('child_process');
 
 const { globals } = require('./globals');
 
-// An error caused by a command explicitly run by the user
+/**
+ * A structure to keep additional error information
+ * @typedef {Object} ErrorState
+ * @property {number} code
+ * @property {string} out
+ * @property {boolean} userCommand
+ */
+
+/**
+ * An error caused by a command exiting with a non-zero exit code
+ * @class
+ */
 class CommandError extends Error {
+  /**
+   * @param {string} message Error message to report
+   * @param {ErrorState} errorState
+   */
   constructor(message, { code, out, userCommand }) {
     super(message);
+
+    /**
+     * Exit code
+     * @type {number}
+     * @public
+     */
     this.code = code;
+
+    /**
+     * Error output as a single concatanated string
+     * @type {string}
+     * @public
+     */
     this.out = out;
+
+    /**
+     * true when the error caused by a command explicitly run by the end user
+     * @type {boolean}
+     * @public
+     */
     this.userCommand = userCommand;
   }
 }
 
-// The user provided an unexpected input
+/**
+ * An error caused by the user providing an unexpected input
+ * @class
+ */
 class ParameterError extends Error {
+  /**
+   * @param {string} message Error message to report
+   * @param {string} actionName
+   */
   constructor(message, actionName) {
     super(message);
+
+    /**
+     * true when the error caused by a command explicitly run by the end user
+     * @type {string}
+     * @public
+     */
     this.actionName = actionName;
   }
 }
 
-// Something was not as expected to continue the operation
+/**
+ * Something was not as expected to continue the operation
+ * @class
+ */
 class ValidationError extends Error {
+  /**
+   * @param {string} message
+   */
   constructor(message) {
     super(message);
   }
 }
 
+/**
+ * @param {string} path
+ */
 async function fileExists(path) {
   return fs
     .stat(path)
@@ -41,6 +96,9 @@ async function fileExists(path) {
     });
 }
 
+/**
+ * @param {string} path
+ */
 async function dirExists(path) {
   return fs
     .stat(path)
@@ -51,9 +109,27 @@ async function dirExists(path) {
     });
 }
 
+/**
+ * @typedef {{
+ *  userCommand?: boolean,
+ *  inheritStdin?: boolean,
+ *  inheritStdout?: boolean,
+ *  inheritStderr?: boolean,
+ *  spawnOptions?: import('child_process').SpawnOptions,
+ *  stdin?: fsClassic.ReadStream,
+ * }} SpawnOptions
+ */
+
 // A simple Promise wrapper for child_process.spawn. Return the err/out streams
 // from the process by default. Specify inheritStdout / inheritStderr to disable
 // this and inherit the parent process's stream, passing through the TTY if any.
+/**
+ *
+ * @param {string} cmd
+ * @param {string[]} params
+ * @param {SpawnOptions} options
+ * @returns {Promise<string>}
+ */
 function spawnProcess(
   cmd,
   params = [],
@@ -81,7 +157,10 @@ function spawnProcess(
   }
 ) {
   return new Promise((resolve, reject) => {
+    /** @type {Buffer[]} */
     const stdout = [];
+
+    /** @type {Buffer[]} */
     const stderr = [];
 
     log(chalk.grey(`Spawning: ${cmd} ${params.join(' ')}`), true);
@@ -102,6 +181,9 @@ function spawnProcess(
     // See a very old related issue: https://github.com/nodejs/node/issues/947
     // When the stream is not fully consumed by the pipe target and it exits,
     // an EPIPE or EOF is thrown. We don't care about those.
+    /**
+     * @param {Error & {code: string}} err
+     */
     const eatEpipe = (err) => {
       if (err.code !== 'EPIPE' && err.code !== 'EOF') {
         throw err;
@@ -140,11 +222,17 @@ function spawnProcess(
       });
     }
 
+    /**
+     * @param {Error} err
+     */
     const errorHandler = (err) => {
       command.off('close', closeHandler);
       reject(err);
     };
 
+    /**
+     * @param {number} code
+     */
     const closeHandler = function (code) {
       // The stream was fully consumed, if there is this an additional error on
       // stdout, it must be a legitimate error
@@ -170,9 +258,21 @@ function spawnProcess(
   });
 }
 
-function dockerExec(libdragonInfo, dockerParams, cmdWithParams, options) {
+/**
+ * @typedef {{
+ * (libdragonInfo: import('./project-info').LibdragonInfo, dockerParams: string[], cmdWithParams: string[], options?: SpawnOptions): Promise<string>;
+ * (libdragonInfo: import('./project-info').LibdragonInfo, cmdWithParams: string[], options?: SpawnOptions, unused?: unknown): Promise<string>;
+ * }} DockerExec
+ */
+const dockerExec = /** @type {DockerExec} */ function (
+  libdragonInfo,
+  dockerParams,
+  cmdWithParams,
+  /** @type {SpawnOptions} */
+  options
+) {
   assert(
-    libdragonInfo.containerId,
+    !!libdragonInfo.containerId,
     new Error('Trying to invoke dockerExec without a containerId.')
   );
 
@@ -181,7 +281,7 @@ function dockerExec(libdragonInfo, dockerParams, cmdWithParams, options) {
     Array.isArray(dockerParams) && Array.isArray(cmdWithParams);
 
   if (!haveDockerParams) {
-    options = cmdWithParams;
+    options = /** @type {SpawnOptions} */ (cmdWithParams);
   }
 
   const additionalParams = [];
@@ -215,10 +315,12 @@ function dockerExec(libdragonInfo, dockerParams, cmdWithParams, options) {
     ],
     options
   );
-}
+};
 
 /**
  * Recursively copies directories and files
+ * @param {string} src
+ * @param {string} dst
  */
 async function copyDirContents(src, dst) {
   log(`Copying from ${src} to ${dst}`, true);
@@ -269,14 +371,24 @@ async function copyDirContents(src, dst) {
   );
 }
 
+/**
+ * @param {string} p
+ */
 function toPosixPath(p) {
   return p.replace(new RegExp('\\' + path.sep, 'g'), path.posix.sep);
 }
 
+/**
+ * @param {string} p
+ */
 function toNativePath(p) {
   return p.replace(new RegExp('\\' + path.posix.sep, 'g'), path.sep);
 }
 
+/**
+ * @param {boolean} condition
+ * @param {Error} error
+ */
 function assert(condition, error) {
   if (!condition) {
     error.message = `[ASSERTION FAILED] ${error.message}`;
@@ -284,12 +396,19 @@ function assert(condition, error) {
   }
 }
 
+/**
+ * @param {string} text
+ */
 function print(text) {
   // eslint-disable-next-line no-console
   console.log(text);
   return;
 }
 
+/**
+ * @param {string} text
+ * @param {boolean} verboseOnly
+ */
 function log(text, verboseOnly = false) {
   if (!verboseOnly) {
     // eslint-disable-next-line no-console

package/modules/parameters.js

@@ -2,10 +2,31 @@ const chalk = require('chalk').stderr;
 
 const { log } = require('./helpers');
 const actions = require('./actions');
-const { STATUS_BAD_PARAM } = require('./constants');
+const { STATUS_BAD_PARAM, ACCEPTED_STRATEGIES } = require('./constants');
 const { globals } = require('./globals');
 
+/** @typedef { import('./actions') } Actions */
+
+/** @typedef { typeof import('./constants').ACCEPTED_STRATEGIES[number] } VendorStrategy */
+
+/**
+ * @template {keyof Actions} [T=keyof Actions]
+ * @typedef {{
+ *  EXTRA_PARAMS: string[];
+ *  CURRENT_ACTION: Actions[T];
+ *  VERBOSE?: boolean;
+ *  DOCKER_IMAGE?: string;
+ *  VENDOR_DIR?: string;
+ *  VENDOR_STRAT?: VendorStrategy;
+ *  FILE?: string;
+ * }} CommandlineOptions
+ */
+
+/**
+ * @param {string[]} argv
+ */
 const parseParameters = async (argv) => {
+  /** @type CommandlineOptions */
   const options = {
     EXTRA_PARAMS: [],
     CURRENT_ACTION: undefined,
@@ -38,12 +59,19 @@ const parseParameters = async (argv) => {
     }
 
     if (['--strategy', '-s'].includes(val)) {
-      options.VENDOR_STRAT = argv[++i];
+      options.VENDOR_STRAT = /** @type VendorStrategy */ (argv[++i]);
       continue;
     } else if (val.indexOf('--strategy=') === 0) {
-      options.VENDOR_STRAT = val.split('=')[1];
+      options.VENDOR_STRAT = /** @type VendorStrategy */ (val.split('=')[1]);
       continue;
     }
+    if (
+      options.VENDOR_STRAT &&
+      !ACCEPTED_STRATEGIES.includes(options.VENDOR_STRAT)
+    ) {
+      log(chalk.red(`Invalid strategy \`${options.VENDOR_STRAT}\``));
+      process.exit(STATUS_BAD_PARAM);
+    }
 
     if (['--file', '-f'].includes(val)) {
       options.FILE = argv[++i];
@@ -63,7 +91,7 @@ const parseParameters = async (argv) => {
       process.exit(STATUS_BAD_PARAM);
     }
 
-    options.CURRENT_ACTION = actions[val];
+    options.CURRENT_ACTION = actions[/** @type {keyof Actions} */ (val)];
 
     if (!options.CURRENT_ACTION) {
       log(chalk.red(`Invalid action \`${val}\``));
@@ -90,8 +118,12 @@ const parseParameters = async (argv) => {
   }
 
   if (
-    ![actions.init, actions.install, actions.update].includes(
-      options.CURRENT_ACTION
+    !(
+      /** @type {typeof actions[keyof actions][]} */ ([
+        actions.init,
+        actions.install,
+        actions.update,
+      ]).includes(options.CURRENT_ACTION)
     ) &&
     options.DOCKER_IMAGE
   ) {
@@ -100,14 +132,13 @@ const parseParameters = async (argv) => {
   }
 
   if (
-    options.VENDOR_STRAT &&
-    !['submodule', 'subtree', 'manual'].includes(options.VENDOR_STRAT)
+    !(
+      /** @type {typeof actions[keyof actions][]} */ ([
+        actions.disasm,
+      ]).includes(options.CURRENT_ACTION)
+    ) &&
+    options.FILE
   ) {
-    log(chalk.red(`Invalid strategy \`${options.VENDOR_STRAT}\``));
-    process.exit(STATUS_BAD_PARAM);
-  }
-
-  if (![actions.disasm].includes(options.CURRENT_ACTION) && options.FILE) {
     log(chalk.red('Invalid flag: file'));
     process.exit(STATUS_BAD_PARAM);
   }

package/modules/project-info.js

@@ -29,9 +29,36 @@ const {
   ParameterError,
 } = require('./helpers');
 
-const initAction = require('./actions/init');
-const destroyAction = require('./actions/destroy');
+// These do not need a project to exist.
+const NO_PROJECT_ACTIONS = /** @type {const} */ (['help', 'version']);
 
+/**
+ * @typedef { typeof NO_PROJECT_ACTIONS[number] } ActionsNoProject
+ * @typedef { Exclude<keyof import('./parameters').Actions, ActionsNoProject> } ActionsWithProject
+ * @typedef { import('./parameters').CommandlineOptions<ActionsNoProject> } ActionsNoProjectOptions
+ * @typedef { import('./parameters').CommandlineOptions<ActionsWithProject> } ActionsWithProjectOptions
+ *
+ * @typedef { {
+ *  options: ActionsNoProjectOptions
+ * } } CLIInfo
+ *
+ * @typedef { {
+ *  root: string;
+ *  userInfo: os.UserInfo<string>;
+ *  haveProjectConfig: boolean;
+ *  imageName: string;
+ *  vendorDirectory: string;
+ *  vendorStrategy: import('./parameters').VendorStrategy;
+ *  containerId: string
+ * } } ExtendedInfo
+ *
+ * @typedef { CLIInfo & Partial<ExtendedInfo> } LibdragonInfo
+ */
+
+/**
+ * @param {LibdragonInfo} libdragonInfo
+ * @returns string
+ */
 async function findContainerId(libdragonInfo) {
   const idFile = path.join(libdragonInfo.root, '.git', CACHED_CONTAINER_FILE);
   if (await fileExists(idFile)) {
@@ -79,6 +106,11 @@ async function findContainerId(libdragonInfo) {
   }
 }
 
+/**
+ * @param {string} start
+ * @param {string} relativeFile
+ * @return {Promise<string>}
+ */
 async function findLibdragonRoot(
   start = '.',
   relativeFile = path.join(LIBDRAGON_PROJECT_MANIFEST, CONFIG_FILE)
@@ -106,18 +138,19 @@ async function findGitRoot() {
   }
 }
 
-async function readProjectInfo(info) {
+/**
+ * @param {LibdragonInfo} optionInfo
+ */
+const readProjectInfo = async function (optionInfo) {
   // No need to do anything here if the action does not depend on the project
   // The only exception is the init and destroy actions, which do not need an
   // existing project but readProjectInfo must always run to analyze the situation
-  const forceReadProjectInfo = [initAction, destroyAction].includes(
-    info.options.CURRENT_ACTION
-  );
   if (
-    info.options.CURRENT_ACTION.mustHaveProject === false &&
-    !forceReadProjectInfo
+    NO_PROJECT_ACTIONS.includes(
+      /** @type {ActionsNoProject} */ (optionInfo.options.CURRENT_ACTION.name)
+    )
   ) {
-    return info;
+    return /** @type {CLIInfo} */ (optionInfo);
   }
 
   const migratedRoot = await findLibdragonRoot();
@@ -130,15 +163,19 @@ async function readProjectInfo(info) {
       path.join(LIBDRAGON_PROJECT_MANIFEST, IMAGE_FILE)
     ));
 
-  if (!projectRoot && !forceReadProjectInfo) {
+  if (
+    !projectRoot &&
+    !['init', 'destroy'].includes(optionInfo.options.CURRENT_ACTION.name)
+  ) {
     throw new ParameterError(
       'This is not a libdragon project. Initialize with `libdragon init` first.',
-      info.options.CURRENT_ACTION.name
+      optionInfo.options.CURRENT_ACTION.name
     );
   }
 
-  info = {
-    ...info,
+  /** @type {LibdragonInfo} */
+  let info = {
+    ...optionInfo,
     root: projectRoot ?? (await findNPMRoot()) ?? (await findGitRoot()),
     userInfo: os.userInfo(),
 
@@ -211,10 +248,10 @@ async function readProjectInfo(info) {
   log(`Active vendor strategy: ${info.vendorStrategy}`, true);
 
   return info;
-}
+};
 
 /**
- * @param info This is only the base info without options
+ * @param { LibdragonInfo | void } info This is only the base info without options
  * fn and command line options
  */
 async function writeProjectInfo(info) {