libdragon 10.8.1 → 10.8.2

package/README.md

@@ -1,6 +1,6 @@
 # Docker Libdragon
 
-[![Build](https://github.com/anacierdem/libdragon-docker/actions/workflows/ci.yml/badge.svg?branch=master)](https://github.com/anacierdem/libdragon-docker/actions/workflows/ci.yml)
+[![Build](https://github.com/anacierdem/libdragon-docker/actions/workflows/release.yml/badge.svg?branch=master)](https://github.com/anacierdem/libdragon-docker/actions/workflows/release.yml)
 
 This is a wrapper for a docker container to make managing the libdragon toolchain easier. It has the additional advantage that libdragon toolchain and library can be installed on a per-project basis instead of managing system-wide installations.
 
@@ -191,7 +191,7 @@ When you are happy with your changes, you can verify you conform to the coding s
     npm run format-check
     npm run lint-check
 
-You can auto-fix applicable errors by running `format` and `lint` scripts instead. Additionally, typescript is used as the type system. To be able to get away with transpiling the code during development, jsDoc flavor of types are used instead of inline ones. To check if your types, run:
+You can auto-fix applicable errors by running `format` and `lint` scripts instead. Additionally, typescript is used as the type system. To be able to get away with transpiling the code during development, jsDoc flavor of types are used instead of inline ones. To check your types, run:
 
     npm run tsc
 
@@ -242,11 +242,6 @@ will init the container for this project and run `make && make install` for `ed6
 
 This is an experimental dependency management.
 
-## TODOS
-
-- [ ] Skip CI checks for irrelevant changes.
-- [ ] Verify the NPM dependency mechanism is still working and add a test.
-
 ## Funding
 
 If this tool helped you, consider supporting its development by sponsoring it!

package/index.js

@@ -18,9 +18,30 @@ const {
 const { parseParameters } = require('./modules/parameters');
 const { readProjectInfo, writeProjectInfo } = require('./modules/project-info');
 
+// Note: it is not possible to merge these type definitions in a single comment
+/**
+ * @template {any} [U=any]
+ * @typedef {(U extends any ? (k: U)=>void : never) extends ((k: infer I)=>void) ? I : never} UnionToIntersection
+ */
+/**
+ * @template {any} [K=any]
+ * never does not break the call `info.options.CURRENT_ACTION.fn`
+ * @typedef {[K] extends [UnionToIntersection<K>] ? any : unknown} NoUnion
+ * @typedef {NoUnion<Exclude<Parameters<import('./modules/parameters').Actions[import('./modules/project-info').ActionsNoProject]['fn']>[0], undefined>>} EitherCLIOrLibdragonInfo
+ */
+
 parseParameters(process.argv)
   .then(readProjectInfo)
-  .then((info) => info.options.CURRENT_ACTION.fn(info))
+  .then((info) => {
+    return info.options.CURRENT_ACTION.fn(
+      /** @type {EitherCLIOrLibdragonInfo} */ (info)
+    );
+    // This type make sure a similar restriction to this code block is enforced
+    // without adding unnecessary javascript.
+    // return isProjectAction(info)
+    //   ? info.options.CURRENT_ACTION.fn(info)
+    //   : info.options.CURRENT_ACTION.fn(info);
+  })
   .catch((e) => {
     if (e instanceof ParameterError) {
       log(chalk.red(e.message));

package/modules/actions/disasm.js

@@ -13,7 +13,7 @@ const {
 /**
  * @param {string} stop
  * @param {string} start
- * @return {Promise<string>}
+ * @returns {Promise<string>}
  */
 const findElf = async (stop, start = '.') => {
   start = path.resolve(start);

package/modules/actions/docker-utils.js

@@ -1,7 +1,6 @@
 /**
  *
  * @param {import('../project-info').LibdragonInfo} libdragonInfo
- * @returns
  */
 function dockerHostUserParams(libdragonInfo) {
   const { uid, gid } = libdragonInfo.userInfo;

package/modules/actions/exec.js

@@ -8,6 +8,7 @@ const {
   toPosixPath,
   fileExists,
   dirExists,
+  CommandError,
 } = require('../helpers');
 
 const { start } = require('./start');
@@ -16,7 +17,6 @@ const { installDependencies } = require('./utils');
 
 /**
  * @param {import('../project-info').LibdragonInfo} libdragonInfo
- * @returns
  */
 function dockerRelativeWorkdir(libdragonInfo) {
   return (
@@ -27,18 +27,14 @@ function dockerRelativeWorkdir(libdragonInfo) {
 }
 
 /**
- *
  * @param {import('../project-info').LibdragonInfo} libdragonInfo
- * @returns
  */
 function dockerRelativeWorkdirParams(libdragonInfo) {
   return ['--workdir', dockerRelativeWorkdir(libdragonInfo)];
 }
 
 /**
- *
  * @param {import('../project-info').LibdragonInfo} info
- * @returns
  */
 const exec = async (info) => {
   const parameters = info.options.EXTRA_PARAMS.slice(1);
@@ -52,17 +48,22 @@ const exec = async (info) => {
   const stdin = new PassThrough();
 
   /** @type {string[]} */
-  const paramsWithConvertedPaths = parameters.map((item) => {
-    if (item.startsWith('-')) {
+  const paramsWithConvertedPaths = await Promise.all(
+    parameters.map(async (item) => {
+      if (item.startsWith('-')) {
+        return item;
+      }
+      if (
+        item.includes(path.sep) &&
+        ((await fileExists(item)) || (await dirExists(item)))
+      ) {
+        return toPosixPath(
+          path.isAbsolute(item) ? path.relative(process.cwd(), item) : item
+        );
+      }
       return item;
-    }
-    if (item.includes(path.sep) && (fileExists(item) || dirExists(item))) {
-      return toPosixPath(
-        path.isAbsolute(item) ? path.relative(process.cwd(), item) : item
-      );
-    }
-    return item;
-  });
+    })
+  );
 
   /**
    *
@@ -101,9 +102,7 @@ const exec = async (info) => {
 
   let started = false;
   /**
-   *
    * @param {import('fs').ReadStream=} stdin
-   * @returns
    */
   const startOnceAndCmd = async (stdin) => {
     if (!started) {
@@ -147,14 +146,16 @@ const exec = async (info) => {
       // In the first run, pass the stdin to the process if it is not a TTY
       // o/w we loose a user input unnecesarily somehow.
       stdin:
-        !process.stdin.isTTY &&
+        (!process.stdin.isTTY || undefined) &&
         /** @type {import('fs').ReadStream} */ (
           /** @type {unknown} */ (process.stdin)
         ),
     });
   } catch (e) {
+    if (!(e instanceof CommandError)) {
+      throw e;
+    }
     if (
-      !e.out ||
       // TODO: is there a better way?
       !e.out.toString().includes(info.containerId)
     ) {

package/modules/actions/init.js

@@ -30,7 +30,7 @@ const { syncImageAndStart } = require('./update-and-start');
 
 /**
  * @param {import('../project-info').LibdragonInfo} info
- * @return {Promise<"submodule" | "subtree" | undefined>}
+ * @returns {Promise<"submodule" | "subtree" | undefined>}
  */
 const autoDetect = async (info) => {
   const vendorTarget = path.relative(
@@ -188,6 +188,8 @@ const autoVendor = async (info) => {
     ]);
     return info;
   }
+
+  return info;
 };
 
 /**
@@ -242,7 +244,9 @@ async function init(info) {
   info.containerId = await start(info);
 
   // We have created a new container, save the new info ASAP
-  await initGitAndCacheContainerId(info);
+  await initGitAndCacheContainerId(
+    /** @type Parameters<initGitAndCacheContainerId>[0] */ (info)
+  );
 
   info = await autoVendor(info);
 

package/modules/actions/npm-utils.js

@@ -55,59 +55,61 @@ const installNPMDependencies = async (libdragonInfo) => {
 
     await Promise.all(
       deps.map(({ name, paths }) => {
-        return new Promise((resolve, reject) => {
-          fsClassic.access(
-            path.join(paths[0], 'Makefile'),
-            fsClassic.constants.F_OK,
-            async (e) => {
-              if (e) {
-                // File does not exist - skip
-                resolve();
-                return;
-              }
+        return /** @type Promise<void> */ (
+          new Promise((resolve, reject) => {
+            fsClassic.access(
+              path.join(paths[0], 'Makefile'),
+              fsClassic.constants.F_OK,
+              async (e) => {
+                if (e) {
+                  // File does not exist - skip
+                  resolve();
+                  return;
+                }
 
-              if (paths.length > 1) {
-                reject(
-                  new ValidationError(
-                    `Using same dependency with different versions is not supported! ${name}`
-                  )
-                );
-                return;
-              }
+                if (paths.length > 1) {
+                  reject(
+                    new ValidationError(
+                      `Using same dependency with different versions is not supported! ${name}`
+                    )
+                  );
+                  return;
+                }
 
-              try {
-                const relativePath = toPosixPath(
-                  path.relative(libdragonInfo.root, paths[0])
-                );
-                const containerPath = path.posix.join(
-                  CONTAINER_TARGET_PATH,
-                  relativePath
-                );
-                const makePath = path.posix.join(containerPath, 'Makefile');
+                try {
+                  const relativePath = toPosixPath(
+                    path.relative(libdragonInfo.root, paths[0])
+                  );
+                  const containerPath = path.posix.join(
+                    CONTAINER_TARGET_PATH,
+                    relativePath
+                  );
+                  const makePath = path.posix.join(containerPath, 'Makefile');
 
-                await dockerExec(
-                  libdragonInfo,
-                  [...dockerHostUserParams(libdragonInfo)],
-                  [
-                    '/bin/bash',
-                    '-c',
-                    '[ -f ' +
-                      makePath +
-                      ' ] && make -C ' +
-                      containerPath +
-                      ' && make -C ' +
-                      containerPath +
-                      ' install',
-                  ]
-                );
+                  await dockerExec(
+                    libdragonInfo,
+                    [...dockerHostUserParams(libdragonInfo)],
+                    [
+                      '/bin/bash',
+                      '-c',
+                      '[ -f ' +
+                        makePath +
+                        ' ] && make -C ' +
+                        containerPath +
+                        ' && make -C ' +
+                        containerPath +
+                        ' install',
+                    ]
+                  );
 
-                resolve();
-              } catch (e) {
-                reject(e);
+                  resolve();
+                } catch (e) {
+                  reject(e);
+                }
               }
-            }
-          );
-        });
+            );
+          })
+        );
       })
     );
   }

package/modules/actions/stop.js

@@ -4,6 +4,7 @@ const { checkContainerRunning } = require('./utils');
 
 /**
  * @param {import('../project-info').LibdragonInfo} libdragonInfo
+ * @returns {Promise<import('../project-info').LibdragonInfo | void>}
  */
 const stop = async (libdragonInfo) => {
   const running =

package/modules/actions/utils.js

@@ -121,7 +121,6 @@ const destroyContainer = async (libdragonInfo) => {
  * @param {import('../project-info').LibdragonInfo} libdragonInfo
  * @param {string[]} params
  * @param {import('../helpers').SpawnOptions} options
- * @returns
  */
 async function runGitMaybeHost(libdragonInfo, params, options = {}) {
   assert(
@@ -201,7 +200,7 @@ async function checkContainerRunning(containerId) {
 }
 
 /**
- * @param {import('../project-info').LibdragonInfo} libdragonInfo
+ * @param {import('../project-info').LibdragonInfo & {containerId: string}} libdragonInfo
  */
 async function initGitAndCacheContainerId(libdragonInfo) {
   // If there is managed vendoring, make sure we have a git repo. `git init` is

package/modules/constants.js

@@ -11,6 +11,11 @@ module.exports = /** @type {const} */ ({
 
   ACCEPTED_STRATEGIES: ['submodule', 'subtree', 'manual'],
 
+  // These do not need a project to exist and their actions do not need the whole
+  // structure. Actions that need the full project information should not be
+  // listed here.
+  NO_PROJECT_ACTIONS: ['help', 'version'],
+
   // cli exit codes
   STATUS_OK: 0,
   STATUS_ERROR: 1,

package/modules/helpers.js

@@ -5,6 +5,7 @@ const chalk = require('chalk').stderr;
 const { spawn } = require('child_process');
 
 const { globals } = require('./globals');
+const { NO_PROJECT_ACTIONS } = require('./constants');
 
 /**
  * A structure to keep additional error information
@@ -197,26 +198,26 @@ function spawnProcess(
       resolve('');
     };
 
-    if (!enableInTTY && stdin) {
+    if (!enableInTTY && stdin && command.stdin) {
       stdin.pipe(command.stdin);
     }
 
-    if (!enableOutTTY && (globals.verbose || userCommand)) {
+    if (!enableOutTTY && (globals.verbose || userCommand) && command.stdout) {
       command.stdout.pipe(process.stdout);
       process.stdout.once('error', eatEpipe);
     }
 
-    if (!inheritStdout) {
+    if (!inheritStdout && command.stdout) {
       command.stdout.on('data', function (data) {
         stdout.push(Buffer.from(data));
       });
     }
 
-    if (!enableErrorTTY && (globals.verbose || userCommand)) {
+    if (!enableErrorTTY && (globals.verbose || userCommand) && command.stderr) {
       command.stderr.pipe(process.stderr);
     }
 
-    if (!inheritStderr) {
+    if (!inheritStderr && command.stderr) {
       command.stderr.on('data', function (data) {
         stderr.push(Buffer.from(data));
       });
@@ -264,58 +265,60 @@ function spawnProcess(
  * (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,
-    new Error('Trying to invoke dockerExec without a containerId.')
-  );
+const dockerExec = /** @type {DockerExec} */ (
+  function (
+    libdragonInfo,
+    dockerParams,
+    cmdWithParams,
+    /** @type {SpawnOptions | undefined} */
+    options
+  ) {
+    assert(
+      !!libdragonInfo.containerId,
+      new Error('Trying to invoke dockerExec without a containerId.')
+    );
+
+    // TODO: assert for invalid args
+    const haveDockerParams =
+      Array.isArray(dockerParams) && Array.isArray(cmdWithParams);
+
+    if (!haveDockerParams) {
+      options = /** @type {SpawnOptions} */ (cmdWithParams);
+    }
 
-  // TODO: assert for invalid args
-  const haveDockerParams =
-    Array.isArray(dockerParams) && Array.isArray(cmdWithParams);
+    const additionalParams = [];
 
-  if (!haveDockerParams) {
-    options = /** @type {SpawnOptions} */ (cmdWithParams);
-  }
+    // Docker TTY wants in & out streams both to be a TTY
+    // If no options are provided, disable TTY as spawnProcess defaults to no
+    // inherit as well.
+    const enableTTY = options
+      ? options.inheritStdout && options.inheritStdin
+      : false;
+    const ttyEnabled = enableTTY && process.stdout.isTTY && process.stdin.isTTY;
 
-  const additionalParams = [];
-
-  // Docker TTY wants in & out streams both to be a TTY
-  // If no options are provided, disable TTY as spawnProcess defaults to no
-  // inherit as well.
-  const enableTTY = options
-    ? options.inheritStdout && options.inheritStdin
-    : false;
-  const ttyEnabled = enableTTY && process.stdout.isTTY && process.stdin.isTTY;
+    if (ttyEnabled) {
+      additionalParams.push('-t');
+    }
 
-  if (ttyEnabled) {
-    additionalParams.push('-t');
+    // Always enable stdin, also see; https://github.com/anacierdem/libdragon-docker/issues/45
+    // Currently we run all exec commands in stdin mode even if the actual process
+    // does not need any input. This will eat any user input by default.
+    additionalParams.push('-i');
+
+    return spawnProcess(
+      'docker',
+      [
+        'exec',
+        ...(haveDockerParams
+          ? [...dockerParams, ...additionalParams]
+          : additionalParams),
+        libdragonInfo.containerId,
+        ...(haveDockerParams ? cmdWithParams : dockerParams),
+      ],
+      options
+    );
   }
-
-  // Always enable stdin, also see; https://github.com/anacierdem/libdragon-docker/issues/45
-  // Currently we run all exec commands in stdin mode even if the actual process
-  // does not need any input. This will eat any user input by default.
-  additionalParams.push('-i');
-
-  return spawnProcess(
-    'docker',
-    [
-      'exec',
-      ...(haveDockerParams
-        ? [...dockerParams, ...additionalParams]
-        : additionalParams),
-      libdragonInfo.containerId,
-      ...(haveDockerParams ? cmdWithParams : dockerParams),
-    ],
-    options
-  );
-};
+);
 
 /**
  * Recursively copies directories and files
@@ -386,8 +389,9 @@ function toNativePath(p) {
 }
 
 /**
- * @param {boolean} condition
+ * @param {any} condition
  * @param {Error} error
+ * @returns {asserts condition}
  */
 function assert(condition, error) {
   if (!condition) {
@@ -422,6 +426,18 @@ function log(text, verboseOnly = false) {
   }
 }
 
+/**
+ * @param {import('./project-info').CLIInfo | import('./project-info').LibdragonInfo} info
+ * @returns {info is import('./project-info').LibdragonInfo}
+ */
+function isProjectAction(info) {
+  return !NO_PROJECT_ACTIONS.includes(
+    /** @type {import('./project-info').ActionsNoProject} */ (
+      info.options.CURRENT_ACTION.name
+    )
+  );
+}
+
 module.exports = {
   spawnProcess,
   toPosixPath,
@@ -436,4 +452,5 @@ module.exports = {
   CommandError,
   ParameterError,
   ValidationError,
+  isProjectAction,
 };

package/modules/parameters.js

@@ -26,7 +26,7 @@ const { globals } = require('./globals');
  * @param {string[]} argv
  */
 const parseParameters = async (argv) => {
-  /** @type CommandlineOptions */
+  /** @type Partial<CommandlineOptions> & {EXTRA_PARAMS: string[] } */
   const options = {
     EXTRA_PARAMS: [],
     CURRENT_ACTION: undefined,
@@ -143,7 +143,7 @@ const parseParameters = async (argv) => {
     process.exit(STATUS_BAD_PARAM);
   }
 
-  return { options };
+  return { options: /** @type CommandlineOptions */ (options) };
 };
 
 module.exports = {

package/modules/project-info.js

@@ -27,37 +27,41 @@ const {
   toPosixPath,
   assert,
   ParameterError,
+  isProjectAction,
 } = require('./helpers');
 
-// These do not need a project to exist.
-const NO_PROJECT_ACTIONS = /** @type {const} */ (['help', 'version']);
-
 /**
- * @typedef { typeof NO_PROJECT_ACTIONS[number] } ActionsNoProject
+ * @typedef { typeof import('./constants').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
  *
+ * This is all the potential CLI combinations
  * @typedef { {
- *  options: ActionsNoProjectOptions
+ *  options: import('./parameters').CommandlineOptions
  * } } CLIInfo
  *
+ * Then readProjectInfo creates two possible set of outputs. One is for actions
+ * that don't need a project and one with project. This setup forces the actions
+ * to not use detailed information if they are listed in NO_PROJECT_ACTIONS
+ * @typedef { {
+ *  options: ActionsNoProjectOptions
+ * } } NoProjectInfo
+ *
  * @typedef { {
+ *  options: ActionsWithProjectOptions
  *  root: string;
  *  userInfo: os.UserInfo<string>;
  *  haveProjectConfig: boolean;
  *  imageName: string;
  *  vendorDirectory: string;
  *  vendorStrategy: import('./parameters').VendorStrategy;
- *  containerId: string
- * } } ExtendedInfo
- *
- * @typedef { CLIInfo & Partial<ExtendedInfo> } LibdragonInfo
+ *  containerId?: string
+ * } } LibdragonInfo
  */
 
 /**
  * @param {LibdragonInfo} libdragonInfo
- * @returns string
  */
 async function findContainerId(libdragonInfo) {
   const idFile = path.join(libdragonInfo.root, '.git', CACHED_CONTAINER_FILE);
@@ -109,7 +113,7 @@ async function findContainerId(libdragonInfo) {
 /**
  * @param {string} start
  * @param {string} relativeFile
- * @return {Promise<string>}
+ * @returns {Promise<string | undefined>}
  */
 async function findLibdragonRoot(
   start = '.',
@@ -139,18 +143,15 @@ async function findGitRoot() {
 }
 
 /**
- * @param {LibdragonInfo} optionInfo
+ * @param {CLIInfo} optionInfo
+ * @returns {Promise<LibdragonInfo | NoProjectInfo>}
  */
 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
-  if (
-    NO_PROJECT_ACTIONS.includes(
-      /** @type {ActionsNoProject} */ (optionInfo.options.CURRENT_ACTION.name)
-    )
-  ) {
-    return /** @type {CLIInfo} */ (optionInfo);
+  if (!isProjectAction(optionInfo)) {
+    return /** @type {NoProjectInfo} */ (optionInfo);
   }
 
   const migratedRoot = await findLibdragonRoot();
@@ -173,10 +174,16 @@ const readProjectInfo = async function (optionInfo) {
     );
   }
 
+  const foundRoot =
+    projectRoot ?? (await findNPMRoot()) ?? (await findGitRoot());
+  if (!foundRoot) {
+    log('Could not find project root, set as cwd.', true);
+  }
+
   /** @type {LibdragonInfo} */
   let info = {
     ...optionInfo,
-    root: projectRoot ?? (await findNPMRoot()) ?? (await findGitRoot()),
+    root: foundRoot ?? process.cwd(),
     userInfo: os.userInfo(),
 
     // Use this to discriminate if there is a project when the command is run
@@ -190,11 +197,6 @@ const readProjectInfo = async function (optionInfo) {
     vendorStrategy: DEFAULT_STRATEGY,
   };
 
-  if (!info.root) {
-    log('Could not find project root, set as cwd.', true);
-    info.root = process.cwd();
-  }
-
   log(`Project root: ${info.root}`, true);
 
   if (migratedRoot) {
@@ -231,7 +233,11 @@ const readProjectInfo = async function (optionInfo) {
   // As last option fallback to default value.
 
   // If still have the container, read the image name from it
-  if (!info.imageName && (await checkContainerAndClean(info))) {
+  if (
+    !info.imageName &&
+    info.containerId &&
+    (await checkContainerAndClean(info))
+  ) {
     info.imageName = (
       await spawnProcess('docker', [
         'container',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "libdragon",
-  "version": "10.8.1",
+  "version": "10.8.2",
   "description": "This is a docker wrapper for libdragon",
   "main": "index.js",
   "engines": {