libdragon 10.7.1 → 10.8.1

package/modules/actions/init.js

@@ -3,7 +3,6 @@ const path = require('path');
 
 const chalk = require('chalk').stderr;
 
-const { fn: install } = require('./install');
 const { start } = require('./start');
 const {
   installDependencies,
@@ -27,33 +26,149 @@ const {
   toPosixPath,
   toNativePath,
 } = require('../helpers');
+const { syncImageAndStart } = require('./update-and-start');
 
-const autoVendor = async (libdragonInfo) => {
-  await runGitMaybeHost(libdragonInfo, ['init']);
+/**
+ * @param {import('../project-info').LibdragonInfo} info
+ * @return {Promise<"submodule" | "subtree" | undefined>}
+ */
+const autoDetect = async (info) => {
+  const vendorTarget = path.relative(
+    info.root,
+    toNativePath(info.vendorDirectory)
+  );
+  const vendorTargetExists = await fs.stat(vendorTarget).catch((e) => {
+    if (e.code !== 'ENOENT') throw e;
+    return false;
+  });
 
-  if (libdragonInfo.vendorStrategy === 'submodule') {
-    await runGitMaybeHost(libdragonInfo, [
+  if (
+    vendorTargetExists &&
+    (await runGitMaybeHost(info, [
       'submodule',
-      'add',
-      '--force',
-      '--name',
-      LIBDRAGON_SUBMODULE,
-      '--branch',
-      LIBDRAGON_BRANCH,
-      LIBDRAGON_GIT,
-      libdragonInfo.vendorDirectory,
-    ]);
-  } else if (libdragonInfo.vendorStrategy === 'subtree') {
+      'status',
+      info.vendorDirectory,
+    ]).catch((e) => {
+      if (!(e instanceof CommandError)) {
+        throw e;
+      }
+    }))
+  ) {
+    log(`${info.vendorDirectory} is a submodule.`);
+    return 'submodule';
+  }
+
+  if (vendorTargetExists) {
+    const gitLogs = await runGitMaybeHost(info, ['log'], {
+      inheritStdin: false,
+      inheritStdout: false,
+      inheritStderr: false,
+    }).catch((e) => {
+      if (!(e instanceof CommandError)) {
+        throw e;
+      }
+    });
+
+    if (
+      gitLogs &&
+      gitLogs.includes(`git-subtree-dir: ${info.vendorDirectory}`)
+    ) {
+      log(`${info.vendorDirectory} is a subtree.`);
+      return 'subtree';
+    }
+  }
+};
+
+/**
+ * @param {import('../project-info').LibdragonInfo} info
+ */
+const autoVendor = async (info) => {
+  // Update the strategy information for the project if the flag is provided
+  if (info.options.VENDOR_STRAT) {
+    info.vendorStrategy = info.options.VENDOR_STRAT;
+  }
+
+  // Update the directory information for the project if the flag is provided
+  if (info.options.VENDOR_DIR) {
+    const relativeVendorDir = path.relative(info.root, info.options.VENDOR_DIR);
+    // Validate vendoring path
+    if (relativeVendorDir.startsWith('..')) {
+      throw new ParameterError(
+        `\`--directory=${info.options.VENDOR_DIR}\` is outside the project directory.`,
+        info.options.CURRENT_ACTION.name
+      );
+    }
+
+    // Immeditately convert it to a posix and relative path
+    info.vendorDirectory = toPosixPath(relativeVendorDir);
+  }
+
+  // No need to do anything here
+  if (info.vendorStrategy === 'manual') {
+    return info;
+  }
+
+  await runGitMaybeHost(info, ['init']);
+
+  // TODO: TS thinks this is already defined
+  const detectedStrategy = await autoDetect(info);
+
+  if (
+    info.options.VENDOR_STRAT &&
+    detectedStrategy &&
+    detectedStrategy !== info.options.VENDOR_STRAT
+  ) {
+    throw new ValidationError(
+      `${info.vendorDirectory} is a ${detectedStrategy} which is different from the provided strategy: ${info.options.VENDOR_STRAT}.`
+    );
+  }
+
+  if (detectedStrategy) {
+    log(
+      `Using ${info.vendorDirectory} as a ${detectedStrategy} vendoring target.`
+    );
+    return {
+      ...info,
+      vendorStrategy: /** @type {import('../parameters').VendorStrategy} */ (
+        detectedStrategy
+      ),
+    };
+  }
+
+  if (info.vendorStrategy === 'submodule') {
+    try {
+      await runGitMaybeHost(info, [
+        'submodule',
+        'add',
+        '--force',
+        '--name',
+        LIBDRAGON_SUBMODULE,
+        '--branch',
+        LIBDRAGON_BRANCH,
+        LIBDRAGON_GIT,
+        info.vendorDirectory,
+      ]);
+    } catch (e) {
+      if (!(e instanceof CommandError)) throw e;
+      // We speculate this is caused by the user, so replace it with a more useful error message.
+      e.message = `Unable to create submodule. If you have copied the executable in your project folder or you have a file named ${info.vendorDirectory}, removing it might solve this issue. Original error:\n${e.message}`;
+      throw e;
+    }
+
+    return info;
+  }
+
+  if (info.vendorStrategy === 'subtree') {
     // Create a commit if it does not exist. This is required for subtree.
     try {
-      await runGitMaybeHost(libdragonInfo, ['rev-parse', 'HEAD']);
+      await runGitMaybeHost(info, ['rev-parse', 'HEAD']);
     } catch (e) {
       if (!(e instanceof CommandError)) throw e;
 
       // This will throw if git user name/email is not set up. Let's not assume
       // anything for now. This means subtree is not supported for someone without
       // git on the host machine.
-      await runGitMaybeHost(libdragonInfo, [
+      await runGitMaybeHost(info, [
         'commit',
         '--allow-empty',
         '-n',
@@ -62,34 +177,32 @@ const autoVendor = async (libdragonInfo) => {
       ]);
     }
 
-    await runGitMaybeHost(libdragonInfo, [
+    await runGitMaybeHost(info, [
       'subtree',
       'add',
       '--prefix',
-      path.relative(libdragonInfo.root, libdragonInfo.vendorDirectory),
+      path.relative(info.root, info.vendorDirectory),
       LIBDRAGON_GIT,
       LIBDRAGON_BRANCH,
       '--squash',
     ]);
+    return info;
   }
-
-  return libdragonInfo;
 };
 
 /**
  * Initialize a new libdragon project in current working directory
  * Also downloads the image
+ * @param {import('../project-info').LibdragonInfo} info
  */
 async function init(info) {
   log(`Initializing a libdragon project at ${info.root}`);
 
-  let newInfo = info;
-
   // Validate manifest
-  const manifestPath = path.join(newInfo.root, LIBDRAGON_PROJECT_MANIFEST);
+  const manifestPath = path.join(info.root, LIBDRAGON_PROJECT_MANIFEST);
   const manifestStats = await fs.stat(manifestPath).catch((e) => {
     if (e.code !== 'ENOENT') throw e;
-    return false;
+    return /** @type {const} */ (false);
   });
 
   if (manifestStats && !manifestStats.isDirectory()) {
@@ -98,101 +211,58 @@ async function init(info) {
     );
   }
 
-  // Validate vendoring strategy. Do not allow a switch after successful initialization
-  if (
-    newInfo.haveProjectConfig &&
-    newInfo.options.VENDOR_STRAT &&
-    newInfo.options.VENDOR_STRAT !== 'manual' &&
-    newInfo.vendorStrategy !== newInfo.options.VENDOR_STRAT
-  ) {
-    throw new ParameterError(
-      `Requested strategy switch: ${newInfo.vendorStrategy} -> ${newInfo.options.VENDOR_STRAT} It is not possible to switch vendoring strategy after initializing a project. You can always switch to manual and handle libdragon yourself.`,
-      info.options.CURRENT_ACTION.name
-    );
-  }
-
-  // Update the strategy information for the project if the flag is provided
-  if (newInfo.options.VENDOR_STRAT) {
-    newInfo.vendorStrategy = newInfo.options.VENDOR_STRAT;
-  }
-
-  // Update the directory information for the project if the flag is provided
-  if (newInfo.options.VENDOR_DIR) {
-    const relativeVendorDir = path.relative(info.root, info.options.VENDOR_DIR);
-    // Validate vendoring path
-    if (relativeVendorDir.startsWith('..')) {
-      throw new ParameterError(
-        `\`--directory=${info.options.VENDOR_DIR}\` is outside the project directory.`,
-        info.options.CURRENT_ACTION.name
-      );
-    }
-
-    // Immeditately convert it to a posix and relative path
-    newInfo.vendorDirectory = toPosixPath(relativeVendorDir);
-  }
-
-  if (newInfo.haveProjectConfig) {
+  if (info.haveProjectConfig) {
     log(
       `${path.join(
-        newInfo.root,
+        info.root,
         LIBDRAGON_PROJECT_MANIFEST
       )} exists. This is already a libdragon project, starting it...`
     );
-    if (newInfo.options.DOCKER_IMAGE) {
+    if (info.options.DOCKER_IMAGE) {
       log(
         `Not changing docker image. Use the install action if you want to override the image.`
       );
     }
-    // TODO: we may make sure git and submodule is initialized here
-    return await install(newInfo);
+    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(newInfo, newInfo.imageName);
+  await updateImage(info, info.imageName);
 
   // Download image and start it
-  newInfo.containerId = await start(newInfo);
+  info.containerId = await start(info);
 
   // We have created a new container, save the new info ASAP
-  await initGitAndCacheContainerId(newInfo);
+  await initGitAndCacheContainerId(info);
 
-  if (newInfo.vendorStrategy !== 'manual') {
-    const vendorTarget = path.relative(
-      newInfo.root,
-      toNativePath(newInfo.vendorDirectory)
-    );
-    const vendorTargetExists = await fs.stat(vendorTarget).catch((e) => {
-      if (e.code !== 'ENOENT') throw e;
-      return false;
-    });
-
-    if (vendorTargetExists) {
-      throw new ValidationError(
-        `${path.resolve(
-          vendorTarget
-        )} already exists. That is the libdragon vendoring target, please remove and retry.`
-      );
-    }
-
-    newInfo = await autoVendor(newInfo);
-  }
+  info = await autoVendor(info);
 
   log(`Preparing project files...`);
   const skeletonFolder = path.join(__dirname, '../../skeleton');
 
   await Promise.all([
-    installDependencies(newInfo),
+    installDependencies(info),
     // node copy functions does not work with pkg
-    copyDirContents(skeletonFolder, newInfo.root),
+    copyDirContents(skeletonFolder, info.root),
   ]);
 
-  log(chalk.green(`libdragon ready at \`${newInfo.root}\`.`));
-  return newInfo;
+  log(chalk.green(`libdragon ready at \`${info.root}\`.`));
+  return info;
 }
 
-module.exports = {
+module.exports = /** @type {const} */ ({
   name: 'init',
   fn: init,
-  mustHaveProject: false,
+  forwardsRestParams: false,
   usage: {
     name: 'init',
     summary: 'Create a libdragon project in the current directory.',
@@ -200,7 +270,9 @@ module.exports = {
 
     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, 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

@@ -2,31 +2,26 @@ const chalk = require('chalk').stderr;
 
 const { installDependencies } = require('./utils');
 const { start } = require('./start');
-const { updateAndStart } = require('./update-and-start');
+const { syncImageAndStart } = require('./update-and-start');
 const { log } = require('../helpers');
 
 /**
  * Updates the image if flag is provided and install vendors onto the container.
  * We should probably remove the image installation responsibility from this
  * action but it might be a breaking change.
- * @param libdragonInfo
- * @param skipUpdate This is added to skip the update when calling this from
- * the update action as it already does an update itself. install doing an image
- * update is pretty much a useless operation, but let's keep it in case someone
- * depends on it. It used to only update the image if the flag is provided and
- * we still keep that logic but with a deprecation warning.
+ * @param {import('../project-info').LibdragonInfo} libdragonInfo
  */
-const install = async (libdragonInfo, skipUpdate) => {
+const install = async (libdragonInfo) => {
   let updatedInfo = libdragonInfo;
   const imageName = libdragonInfo.options.DOCKER_IMAGE;
   // If an image is provided, attempt to install
-  if (imageName && skipUpdate !== true) {
+  if (imageName) {
     log(
       chalk.yellow(
         'Using `install` action to update the docker image is deprecated. Use the `update` action instead.'
       )
     );
-    updatedInfo = await updateAndStart(libdragonInfo);
+    updatedInfo = await syncImageAndStart(libdragonInfo);
   } else {
     // Make sure existing one is running
     updatedInfo = {
@@ -41,9 +36,10 @@ const install = async (libdragonInfo, skipUpdate) => {
   return updatedInfo;
 };
 
-module.exports = {
+module.exports = /** @type {const} */ ({
   name: 'install',
   fn: install,
+  forwardsRestParams: false,
   usage: {
     name: 'install',
     summary: 'Vendor libdragon as is.',
@@ -51,4 +47,4 @@ module.exports = {
 
     Must be run in an initialized libdragon project. This can be useful to recover from a half-baked container.`,
   },
-};
+});

package/modules/actions/make.js

@@ -1,5 +1,8 @@
 const { fn: exec } = require('./exec');
 
+/**
+ * @param {import('../project-info').LibdragonInfo} info
+ */
 const make = async (info) => {
   return await exec({
     ...info,
@@ -10,7 +13,7 @@ const make = async (info) => {
   });
 };
 
-module.exports = {
+module.exports = /** @type {const} */ ({
   name: 'make',
   fn: make,
   forwardsRestParams: true,
@@ -21,4 +24,4 @@ module.exports = {
 
     Must be run in an initialized libdragon project. This action is a shortcut to the \`exec\` action under the hood.`,
   },
-};
+});

package/modules/actions/npm-utils.js

@@ -27,7 +27,10 @@ async function findNPMRoot() {
   }
 }
 
-// Install other NPM dependencies if this is an NPM project
+/**
+ * Install other NPM dependencies if this is an NPM project
+ * @param {import('../project-info').LibdragonInfo} libdragonInfo
+ */
 const installNPMDependencies = async (libdragonInfo) => {
   const npmRoot = await findNPMRoot();
   if (npmRoot) {
@@ -55,7 +58,7 @@ const installNPMDependencies = async (libdragonInfo) => {
         return new Promise((resolve, reject) => {
           fsClassic.access(
             path.join(paths[0], 'Makefile'),
-            fsClassic.F_OK,
+            fsClassic.constants.F_OK,
             async (e) => {
               if (e) {
                 // File does not exist - skip
@@ -110,6 +113,9 @@ const installNPMDependencies = async (libdragonInfo) => {
   }
 };
 
+/**
+ * @param {string[]} params
+ */
 function runNPM(params) {
   return spawnProcess(
     /^win/.test(process.platform) ? 'npm.cmd' : 'npm',

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', [
@@ -34,19 +34,20 @@ const initContainer = async (libdragonInfo) => {
       ])
     ).trim();
 
-    const newInfo = {
-      ...libdragonInfo,
-      containerId: newId,
-    };
-
     // chown the installation folder once on init
     const { uid, gid } = libdragonInfo.userInfo;
-    await dockerExec(newInfo, [
-      'chown',
-      '-R',
-      `${uid >= 0 ? uid : ''}:${gid >= 0 ? gid : ''}`,
-      '/n64_toolchain',
-    ]);
+    await dockerExec(
+      {
+        ...libdragonInfo,
+        containerId: newId,
+      },
+      [
+        'chown',
+        '-R',
+        `${uid >= 0 ? uid : ''}:${gid >= 0 ? gid : ''}`,
+        '/n64_toolchain',
+      ]
+    );
   } catch (e) {
     // Dispose the invalid container, clean and exit
     await destroyContainer({
@@ -74,6 +75,9 @@ const initContainer = async (libdragonInfo) => {
   return newId;
 };
 
+/**
+ * @param {import('../project-info').LibdragonInfo} libdragonInfo
+ */
 const start = async (libdragonInfo) => {
   const running =
     libdragonInfo.containerId &&
@@ -98,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.',
@@ -113,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,7 +2,10 @@ const { log } = require('../helpers');
 const { updateImage, destroyContainer } = require('./utils');
 const { start } = require('./start');
 
-async function updateAndStart(libdragonInfo) {
+/**
+ * @param {import('../project-info').LibdragonInfo} libdragonInfo
+ */
+async function syncImageAndStart(libdragonInfo) {
   const oldImageName = libdragonInfo.imageName;
   const imageName = libdragonInfo.options.DOCKER_IMAGE ?? oldImageName;
   // If an image is provided, always attempt to install it
@@ -29,5 +32,5 @@ async function updateAndStart(libdragonInfo) {
 }
 
 module.exports = {
-  updateAndStart,
+  syncImageAndStart,
 };

package/modules/actions/update.js

@@ -1,26 +1,28 @@
 const { log } = require('../helpers');
 const { LIBDRAGON_GIT, LIBDRAGON_BRANCH } = require('../constants');
-const { runGitMaybeHost } = require('./utils');
-const { fn: install } = require('./install');
-const { updateAndStart } = require('./update-and-start');
+const { runGitMaybeHost, installDependencies } = require('./utils');
+const { syncImageAndStart } = require('./update-and-start');
 
+/**
+ * @param {import('../project-info').LibdragonInfo} info
+ */
 const update = async (info) => {
-  const newInfo = await updateAndStart(info);
+  info = await syncImageAndStart(info);
 
-  if (newInfo.vendorStrategy !== 'manual') {
-    log(`Updating ${newInfo.vendorStrategy}...`);
+  if (info.vendorStrategy !== 'manual') {
+    log(`Updating ${info.vendorStrategy}...`);
   }
 
-  if (newInfo.vendorStrategy === 'submodule') {
-    await runGitMaybeHost(newInfo, [
+  if (info.vendorStrategy === 'submodule') {
+    await runGitMaybeHost(info, [
       'submodule',
       'update',
       '--remote',
       '--merge',
-      newInfo.vendorDirectory,
+      info.vendorDirectory,
     ]);
-  } else if (newInfo.vendorStrategy === 'subtree') {
-    await runGitMaybeHost(newInfo, [
+  } else if (info.vendorStrategy === 'subtree') {
+    await runGitMaybeHost(info, [
       'subtree',
       'pull',
       '--prefix',
@@ -31,14 +33,13 @@ const update = async (info) => {
     ]);
   }
 
-  // The second parameter forces it to skip the image update step as we already
-  // do that above.
-  return await install(newInfo, true);
+  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.',
@@ -47,4 +48,4 @@ module.exports = {
       Must be run in an initialized libdragon project.`,
     group: ['docker'],
   },
-};
+});