libdragon 10.8.1 → 10.9.0

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.
 
@@ -184,14 +184,14 @@ For a quick development loop it really helps linking the code in this repository
 
     npm link
 
-in the root of the repository. Once you do this, running `libdragon` will use the code here rather than the actual npm installation. Then you can test your changes in the libdragon project here or elsewhere on your computer.
+in the root of the repository. Once you do this, running `libdragon` will use the code here rather than the actual npm installation. Then you can test your changes in the libdragon project here or elsewhere on your computer. This setup is automatically done if you use the [devcontainer](#experimental-devcontainer-support).
 
 When you are happy with your changes, you can verify you conform to the coding standards via:
 
     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
 
@@ -201,6 +201,29 @@ This repository uses [`semantic-release`](https://github.com/semantic-release/se
 
 It will create a `semantic-release` compatible commit from your current staged changes.
 
+### Experimental devcontainer support
+
+The repository provides a configuration (in `.devcontainer`) so that IDEs that support it can create and run the Docker container for you. Then, you can start working on it as if you are working on a machine with libdragon installed.
+
+With the provided setup, you can continue using the cli in the container and it will work for non-container specific actions like `install`, `disasm` etc. You don't have to use the cli in the container, but you can. In general it will be easier and faster to just run `make` in the container but this setup is included to ease developing the cli as well.
+
+To create your own dev container backed project, you can use the contents of the `.devcontainer` folder as reference. You don't need to include nodejs or the cli and you can just run `build.sh` as `postCreateCommand`. See the `devcontainer.json` for more details. As long as your container have the `DOCKER_CONTAINER` environment variable, the tool can work inside a container.
+
+#### Caveats
+
+- In the devcontainer, uploading via USB will not work.
+- Error matching is not yet tested.
+- Ideally the necessary extensions should be automatically installed. This is not configured yet.
+
+<details>
+  <summary>vscode instructions</summary>
+
+  - Make sure you have the [Dev container extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) installed and you fulfill its [requirements](https://code.visualstudio.com/docs/devcontainers/containers).
+  - Clone this repository with `--recurse-submodules` or run `git submodule update --init`.
+  - Open command palette and run `Dev Containers: Reopen in container`.
+  - It will prepare the container and open it in the editor.
+</details>
+
 ## As an NPM dependency
 
 You can install libdragon as an NPM dependency by `npm install libdragon --save` in order to use docker in your N64 projects. A `libdragon` command similar to global intallation is provided that can be used in your NPM scripts as follows;
@@ -242,11 +265,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/destroy.js

@@ -3,13 +3,19 @@ const path = require('path');
 
 const { destroyContainer } = require('./utils');
 const { CONFIG_FILE, LIBDRAGON_PROJECT_MANIFEST } = require('../constants');
-const { fileExists, dirExists, log } = require('../helpers');
+const { fileExists, dirExists, log, ValidationError } = require('../helpers');
 const chalk = require('chalk');
 
 /**
  * @param {import('../project-info').LibdragonInfo} libdragonInfo
  */
 const destroy = async (libdragonInfo) => {
+  if (process.env.DOCKER_CONTAINER) {
+    throw new ValidationError(
+      `Not possible to destroy the container from inside.`
+    );
+  }
+
   await destroyContainer(libdragonInfo);
 
   const projectPath = path.join(libdragonInfo.root, LIBDRAGON_PROJECT_MANIFEST);

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,8 @@ const {
   toPosixPath,
   fileExists,
   dirExists,
+  CommandError,
+  spawnProcess,
 } = require('../helpers');
 
 const { start } = require('./start');
@@ -16,7 +18,6 @@ const { installDependencies } = require('./utils');
 
 /**
  * @param {import('../project-info').LibdragonInfo} libdragonInfo
- * @returns
  */
 function dockerRelativeWorkdir(libdragonInfo) {
   return (
@@ -27,18 +28,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);
@@ -49,20 +46,42 @@ const exec = async (info) => {
     true
   );
 
+  // Don't even bother here, we are already in a container.
+  if (process.env.DOCKER_CONTAINER) {
+    const enableTTY = Boolean(process.stdout.isTTY && process.stdin.isTTY);
+    await spawnProcess(info.options.EXTRA_PARAMS[0], parameters, {
+      userCommand: true,
+      // Inherit stdin/out in tandem if we are going to disable TTY o/w the input
+      // stream remains inherited by the node process while the output pipe is
+      // waiting data from stdout and it behaves like we are still controlling
+      // the spawned process while the terminal is actually displaying say for
+      // example `less`.
+      inheritStdout: enableTTY,
+      inheritStdin: enableTTY,
+      inheritStderr: true,
+    });
+    return 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 +120,7 @@ const exec = async (info) => {
 
   let started = false;
   /**
-   *
    * @param {import('fs').ReadStream=} stdin
-   * @returns
    */
   const startOnceAndCmd = async (stdin) => {
     if (!started) {
@@ -147,14 +164,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(
@@ -108,7 +108,11 @@ const autoVendor = async (info) => {
     return info;
   }
 
-  await runGitMaybeHost(info, ['init']);
+  // Container re-init breaks file modes assume there is git for this case.
+  // TODO: we should remove the unnecessary inits in the future.
+  if (!process.env.DOCKER_CONTAINER) {
+    await runGitMaybeHost(info, ['init']);
+  }
 
   // TODO: TS thinks this is already defined
   const detectedStrategy = await autoDetect(info);
@@ -188,6 +192,8 @@ const autoVendor = async (info) => {
     ]);
     return info;
   }
+
+  return info;
 };
 
 /**
@@ -218,31 +224,33 @@ async function init(info) {
         LIBDRAGON_PROJECT_MANIFEST
       )} exists. This is already a libdragon project, starting it...`
     );
-    if (info.options.DOCKER_IMAGE) {
-      log(
-        `Not changing docker image. Use the install action if you want to override the image.`
-      );
-    }
-    if (info.options.DOCKER_IMAGE) {
-      info = await syncImageAndStart(info);
-    } else {
-      info = {
-        ...info,
-        containerId: await start(info),
-      };
+    if (!process.env.DOCKER_CONTAINER) {
+      if (info.options.DOCKER_IMAGE) {
+        info = await syncImageAndStart(info);
+      } else {
+        info = {
+          ...info,
+          containerId: await start(info),
+        };
+      }
     }
+
     info = await autoVendor(info);
     await installDependencies(info);
     return info;
   }
 
-  await updateImage(info, info.imageName);
-
-  // Download image and start it
-  info.containerId = await start(info);
-
-  // We have created a new container, save the new info ASAP
-  await initGitAndCacheContainerId(info);
+  if (!process.env.DOCKER_CONTAINER) {
+    // Download image and start it
+    await updateImage(info, info.imageName);
+    info.containerId = await start(info);
+    // We have created a new container, save the new info ASAP
+    // When in a container, we should already have git
+    // Re-initing breaks file modes anyways
+    await initGitAndCacheContainerId(
+      /** @type Parameters<initGitAndCacheContainerId>[0] */ (info)
+    );
+  }
 
   info = await autoVendor(info);
 
@@ -270,7 +278,7 @@ module.exports = /** @type {const} */ ({
 
     By default, a git repository and a submodule at \`./libdragon\` will be created to automatically update the vendored libdragon files on subsequent \`update\`s. If you intend to opt-out from this feature, see the \`--strategy manual\` flag to provide your self-managed libdragon copy. The default behaviour is intended for users who primarily want to consume libdragon as is.
 
-    If this is the first time you are creating a libdragon project at that location, this action will also create skeleton project files to kickstart things with the given image, if provided. For subsequent runs, it will act like \`start\` thus can be used to revive an existing project without modifying it.
+    If this is the first time you are creating a libdragon project at that location, this action will also create skeleton project files to kickstart things with the given image, if provided. For subsequent runs without any parameter, it will act like \`start\` thus can be used to revive an existing project without modifying it.
 
     If you have an existing project with an already vendored submodule or subtree libdragon copy, \`init\` will automatically detect it at the provided \`--directory\`.`,
     group: ['docker', 'vendoring'],

package/modules/actions/install.js

@@ -13,21 +13,24 @@ const { log } = require('../helpers');
  */
 const install = async (libdragonInfo) => {
   let updatedInfo = libdragonInfo;
-  const imageName = libdragonInfo.options.DOCKER_IMAGE;
-  // If an image is provided, attempt to install
-  if (imageName) {
-    log(
-      chalk.yellow(
-        'Using `install` action to update the docker image is deprecated. Use the `update` action instead.'
-      )
-    );
-    updatedInfo = await syncImageAndStart(libdragonInfo);
-  } else {
-    // Make sure existing one is running
-    updatedInfo = {
-      ...updatedInfo,
-      containerId: await start(libdragonInfo),
-    };
+
+  if (!process.env.DOCKER_CONTAINER) {
+    const imageName = libdragonInfo.options.DOCKER_IMAGE;
+    // If an image is provided, attempt to install
+    if (imageName) {
+      log(
+        chalk.yellow(
+          'Using `install` action to update the docker image is deprecated. Use the `update` action instead.'
+        )
+      );
+      updatedInfo = await syncImageAndStart(libdragonInfo);
+    } else {
+      // Make sure existing one is running
+      updatedInfo = {
+        ...updatedInfo,
+        containerId: await start(libdragonInfo),
+      };
+    }
   }
 
   // Re-install vendors on new image

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/start.js

@@ -1,7 +1,14 @@
 const chalk = require('chalk').stderr;
 
 const { CONTAINER_TARGET_PATH } = require('../constants');
-const { spawnProcess, log, print, dockerExec } = require('../helpers');
+const {
+  spawnProcess,
+  log,
+  print,
+  dockerExec,
+  assert,
+  ValidationError,
+} = require('../helpers');
 
 const {
   checkContainerAndClean,
@@ -14,6 +21,11 @@ const {
  * @param {import('../project-info').LibdragonInfo} libdragonInfo
  */
 const initContainer = async (libdragonInfo) => {
+  assert(
+    !process.env.DOCKER_CONTAINER,
+    new Error('initContainer does not make sense in a container')
+  );
+
   let newId;
   try {
     log('Creating new container...');
@@ -79,6 +91,11 @@ const initContainer = async (libdragonInfo) => {
  * @param {import('../project-info').LibdragonInfo} libdragonInfo
  */
 const start = async (libdragonInfo) => {
+  assert(
+    !process.env.DOCKER_CONTAINER,
+    new Error('Cannot start a container when we are already in a container.')
+  );
+
   const running =
     libdragonInfo.containerId &&
     (await checkContainerRunning(libdragonInfo.containerId));
@@ -108,6 +125,10 @@ module.exports = /** @type {const} */ ({
    * @param {import('../project-info').LibdragonInfo} libdragonInfo
    */
   fn: async (libdragonInfo) => {
+    if (process.env.DOCKER_CONTAINER) {
+      throw new ValidationError(`We are already in a container.`);
+    }
+
     const containerId = await start(libdragonInfo);
     print(containerId);
     return { ...libdragonInfo, containerId };

package/modules/actions/stop.js

@@ -1,11 +1,18 @@
-const { spawnProcess } = require('../helpers');
+const { spawnProcess, ValidationError } = require('../helpers');
 
 const { checkContainerRunning } = require('./utils');
 
 /**
  * @param {import('../project-info').LibdragonInfo} libdragonInfo
+ * @returns {Promise<import('../project-info').LibdragonInfo | void>}
  */
 const stop = async (libdragonInfo) => {
+  if (process.env.DOCKER_CONTAINER) {
+    throw new ValidationError(
+      `Not possible to stop the container from inside.`
+    );
+  }
+
   const running =
     libdragonInfo.containerId &&
     (await checkContainerRunning(libdragonInfo.containerId));

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

@@ -1,4 +1,4 @@
-const { log } = require('../helpers');
+const { log, assert } = require('../helpers');
 const { updateImage, destroyContainer } = require('./utils');
 const { start } = require('./start');
 
@@ -6,6 +6,13 @@ const { start } = require('./start');
  * @param {import('../project-info').LibdragonInfo} libdragonInfo
  */
 async function syncImageAndStart(libdragonInfo) {
+  assert(
+    !process.env.DOCKER_CONTAINER,
+    new Error(
+      '[syncImageAndStart] We should already know we are in a container.'
+    )
+  );
+
   const oldImageName = libdragonInfo.imageName;
   const imageName = libdragonInfo.options.DOCKER_IMAGE ?? oldImageName;
   // If an image is provided, always attempt to install it

package/modules/actions/utils.js

@@ -53,11 +53,16 @@ const installDependencies = async (libdragonInfo) => {
 
 /**
  * Downloads the given docker image. Returns false if the local image is the
- * same, new image name otherwise.
+ * same, true otherwise.
  * @param {import('../project-info').LibdragonInfo} libdragonInfo
  * @param {string} newImageName
  */
 const updateImage = async (libdragonInfo, newImageName) => {
+  assert(
+    !process.env.DOCKER_CONTAINER,
+    new Error('[updateImage] should not be called in a container')
+  );
+
   // Will not take too much time if already have the same
   const download = async () => {
     log(`Downloading docker image: ${newImageName}`);
@@ -89,13 +94,18 @@ const updateImage = async (libdragonInfo, newImageName) => {
   }
 
   log(`Image is different: ${newImageName}`, true);
-  return newImageName;
+  return true;
 };
 
 /**
  * @param {import('../project-info').LibdragonInfo} libdragonInfo
  */
 const destroyContainer = async (libdragonInfo) => {
+  assert(
+    !process.env.DOCKER_CONTAINER,
+    new Error('[destroyContainer] should not be called in a container')
+  );
+
   if (libdragonInfo.containerId) {
     await spawnProcess('docker', [
       'container',
@@ -121,7 +131,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(
@@ -145,6 +154,11 @@ async function runGitMaybeHost(libdragonInfo, params, options = {}) {
       throw e;
     }
 
+    assert(
+      !process.env.DOCKER_CONTAINER,
+      new Error('[runGitMaybeHost] Native git should exist in a container.')
+    );
+
     return await dockerExec(
       libdragonInfo,
       // Use the host user when initializing git as we will need access
@@ -160,6 +174,13 @@ async function runGitMaybeHost(libdragonInfo, params, options = {}) {
  * @param {import('../project-info').LibdragonInfo} libdragonInfo
  */
 async function checkContainerAndClean(libdragonInfo) {
+  assert(
+    !process.env.DOCKER_CONTAINER,
+    new Error(
+      '[checkContainerAndClean] We should already know we are in a container.'
+    )
+  );
+
   const id =
     libdragonInfo.containerId &&
     (
@@ -189,6 +210,13 @@ async function checkContainerAndClean(libdragonInfo) {
  * @param {string} containerId
  */
 async function checkContainerRunning(containerId) {
+  assert(
+    !process.env.DOCKER_CONTAINER,
+    new Error(
+      '[checkContainerRunning] We should already know we are in a container.'
+    )
+  );
+
   const running = (
     await spawnProcess('docker', [
       'container',
@@ -201,14 +229,19 @@ async function checkContainerRunning(containerId) {
 }
 
 /**
- * @param {import('../project-info').LibdragonInfo} libdragonInfo
+ * @param {import('../project-info').LibdragonInfo & {containerId: string}} libdragonInfo
  */
 async function initGitAndCacheContainerId(libdragonInfo) {
+  if (!libdragonInfo.containerId) {
+    return;
+  }
+
   // If there is managed vendoring, make sure we have a git repo. `git init` is
   // safe anyways...
   if (libdragonInfo.vendorStrategy !== 'manual') {
     await runGitMaybeHost(libdragonInfo, ['init']);
   }
+
   const gitFolder = path.join(libdragonInfo.root, '.git');
   if (await dirExists(gitFolder)) {
     await fs.writeFile(

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
@@ -156,6 +157,10 @@ function spawnProcess(
     spawnOptions: {},
   }
 ) {
+  assert(
+    cmd !== 'docker' || !process.env.DOCKER_CONTAINER,
+    new Error('Trying to invoke docker inside a container.')
+  );
   return new Promise((resolve, reject) => {
     /** @type {Buffer[]} */
     const stdout = [];
@@ -197,26 +202,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 +269,83 @@ 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
+  ) {
+    // TODO: assert for invalid args
+    const haveDockerParams =
+      Array.isArray(dockerParams) && Array.isArray(cmdWithParams);
 
-  // TODO: assert for invalid args
-  const haveDockerParams =
-    Array.isArray(dockerParams) && Array.isArray(cmdWithParams);
+    if (!haveDockerParams) {
+      options = /** @type {SpawnOptions} */ (cmdWithParams);
+    }
 
-  if (!haveDockerParams) {
-    options = /** @type {SpawnOptions} */ (cmdWithParams);
-  }
+    const finalCmdWithParams = haveDockerParams ? cmdWithParams : dockerParams;
+    const finalDockerParams = haveDockerParams ? dockerParams : [];
 
-  const additionalParams = [];
+    assert(
+      finalDockerParams.findIndex(
+        (val) => val === '--workdir=' || val === '-w='
+      ) === -1,
+      new Error('Do not use `=` syntax when setting working dir')
+    );
 
-  // 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;
+    // Convert docker execs into regular commands in the correct cwd
+    if (process.env.DOCKER_CONTAINER) {
+      const workDirIndex = finalDockerParams.findIndex(
+        (val) => val === '--workdir' || val === '-w'
+      );
+      const workDir =
+        workDirIndex >= 0 ? finalDockerParams[workDirIndex + 1] : undefined;
+      return spawnProcess(finalCmdWithParams[0], finalCmdWithParams.slice(1), {
+        ...options,
+        spawnOptions: { cwd: workDir, ...options?.spawnOptions },
+      });
+    }
 
-  if (ttyEnabled) {
-    additionalParams.push('-t');
-  }
+    assert(
+      !!libdragonInfo.containerId,
+      new Error('Trying to invoke dockerExec without a containerId.')
+    );
 
-  // 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
-  );
-};
+    /** @type string[] */
+    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');
+    }
+
+    // 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',
+        ...finalDockerParams,
+        ...additionalParams,
+        libdragonInfo.containerId,
+        ...finalCmdWithParams,
+      ],
+      options
+    );
+  }
+);
 
 /**
  * Recursively copies directories and files
@@ -386,8 +416,9 @@ function toNativePath(p) {
 }
 
 /**
- * @param {boolean} condition
+ * @param {any} condition
  * @param {Error} error
+ * @returns {asserts condition}
  */
 function assert(condition, error) {
   if (!condition) {
@@ -422,6 +453,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 +479,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,39 +27,48 @@ 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) {
+  assert(
+    !process.env.DOCKER_CONTAINER,
+    new Error('[findContainerId] We should already know we are in a container.')
+  );
+
   const idFile = path.join(libdragonInfo.root, '.git', CACHED_CONTAINER_FILE);
   if (await fileExists(idFile)) {
     const id = (await fs.readFile(idFile, { encoding: 'utf8' })).trim();
@@ -109,7 +118,7 @@ async function findContainerId(libdragonInfo) {
 /**
  * @param {string} start
  * @param {string} relativeFile
- * @return {Promise<string>}
+ * @returns {Promise<string | undefined>}
  */
 async function findLibdragonRoot(
   start = '.',
@@ -139,18 +148,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 +179,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 +202,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) {
@@ -223,15 +230,23 @@ const readProjectInfo = async function (optionInfo) {
     }
   }
 
-  info.containerId = await findContainerId(info);
-  log(`Active container id: ${info.containerId}`, true);
+  if (!process.env.DOCKER_CONTAINER) {
+    info.containerId = await findContainerId(info);
+    log(`Active container id: ${info.containerId}`, true);
+  }
 
   // For imageName, flag has the highest priority followed by the one read from
   // the file and then if there is any matching container, name is read from it.
   // As last option fallback to default value.
 
   // If still have the container, read the image name from it
-  if (!info.imageName && (await checkContainerAndClean(info))) {
+  // No need to do anything if we are in a container
+  if (
+    !process.env.DOCKER_CONTAINER &&
+    !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.9.0",
   "description": "This is a docker wrapper for libdragon",
   "main": "index.js",
   "engines": {