libdragon 10.4.0 → 10.5.0

package/modules/actions/init.js

@@ -4,7 +4,7 @@ const path = require('path');
 const chalk = require('chalk');
 
 const { fn: install } = require('./install');
-const { fn: start } = require('./start');
+const { start } = require('./start');
 const {
   installDependencies,
   tryCacheContainerId,
@@ -23,8 +23,10 @@ const {
   copyDirContents,
   CommandError,
   ParameterError,
+  ValidationError,
+  toPosixPath,
+  toNativePath,
 } = require('../helpers');
-const { setProjectInfoToSave } = require('../project-info');
 
 const autoVendor = async (libdragonInfo) => {
   await runGitMaybeHost(libdragonInfo, ['init']);
@@ -81,55 +83,60 @@ const autoVendor = async (libdragonInfo) => {
 async function init(libdragonInfo) {
   log(`Initializing a libdragon project at ${libdragonInfo.root}`);
 
-  // TODO: use exists instead & check if it is a directory
-  const files = await fs.readdir(libdragonInfo.root);
+  let newInfo = libdragonInfo;
 
-  const manifestFile = files.find(
-    (name) => name === LIBDRAGON_PROJECT_MANIFEST
-  );
+  // Validate manifest
+  const manifestPath = path.join(newInfo.root, LIBDRAGON_PROJECT_MANIFEST);
+  const manifestStats = await fs.stat(manifestPath).catch((e) => {
+    if (e.code !== 'ENOENT') throw e;
+    return false;
+  });
 
-  let newInfo = libdragonInfo;
+  if (manifestStats && !manifestStats.isDirectory()) {
+    throw new ValidationError(
+      'There is already a `.libdragon` file and it is not a directory.'
+    );
+  }
 
   // Validate vendoring strategy. Do not allow a switch after successful initialization
   if (
-    manifestFile &&
+    newInfo.haveProjectConfig &&
     newInfo.options.VENDOR_STRAT &&
     newInfo.options.VENDOR_STRAT !== 'manual' &&
     newInfo.vendorStrategy !== newInfo.options.VENDOR_STRAT
   ) {
-    throw new Error(
+    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.`
     );
   }
 
   // Update the strategy information for the project if the flag is provided
   if (newInfo.options.VENDOR_STRAT) {
-    newInfo = setProjectInfoToSave({
-      ...newInfo,
-      vendorStrategy: 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(
+      libdragonInfo.root,
+      libdragonInfo.options.VENDOR_DIR
+    );
     // Validate vendoring path
-    if (path.isAbsolute(newInfo.options.VENDOR_DIR)) {
+    if (relativeVendorDir.startsWith('..')) {
       throw new ParameterError(
-        '`--directory` must be project-relative as it will be mounted to the docker container.'
+        `\`--directory=${libdragonInfo.options.VENDOR_DIR}\` is outside the project directory.`
       );
     }
 
-    newInfo = setProjectInfoToSave({
-      ...newInfo,
-      vendorDirectory: newInfo.options.VENDOR_DIR,
-    });
+    // Immeditately convert it to a posix and relative path
+    newInfo.vendorDirectory = toPosixPath(relativeVendorDir);
   }
 
-  if (manifestFile) {
+  if (newInfo.haveProjectConfig) {
     log(
       `${path.join(
         newInfo.root,
-        manifestFile
+        LIBDRAGON_PROJECT_MANIFEST
       )} exists. This is already a libdragon project, starting it...`
     );
     if (newInfo.options.DOCKER_IMAGE) {
@@ -137,31 +144,36 @@ async function init(libdragonInfo) {
         `Not changing docker image. Use the install action if you want to override the image.`
       );
     }
-    await install(newInfo);
-    return;
+    // TODO: we may make sure git and submodule is initialized here
+    return await install(newInfo);
   }
 
-  newInfo.imageName =
-    (await updateImage(newInfo, newInfo.imageName)) || newInfo.imageName;
+  await updateImage(newInfo, newInfo.imageName);
+
   // Download image and start it
-  const containerReadyPromise = start(newInfo).then((newId) => ({
+  const containerReadyPromise = start(newInfo, true).then((newId) => ({
     ...newInfo,
     containerId: newId,
   }));
 
   let vendorAndGitReadyPromise = containerReadyPromise;
   if (newInfo.vendorStrategy !== 'manual') {
-    const libdragonFile = files.find((name) =>
-      name.match(
-        new RegExp(`^${path.relative(newInfo.root, newInfo.vendorDirectory)}$`)
-      )
+    const vendorTarget = path.relative(
+      newInfo.root,
+      toNativePath(newInfo.vendorDirectory)
     );
+    const [vendorTargetExists] = await Promise.all([
+      fs.stat(vendorTarget).catch((e) => {
+        if (e.code !== 'ENOENT') throw e;
+        return false;
+      }),
+      containerReadyPromise,
+    ]);
 
-    if (libdragonFile) {
-      throw new Error(
-        `${path.join(
-          newInfo.root,
-          libdragonFile
+    if (vendorTargetExists) {
+      throw new ValidationError(
+        `${path.resolve(
+          vendorTarget
         )} already exists. That is the libdragon vendoring target, please remove and retry.`
       );
     }
@@ -181,10 +193,21 @@ async function init(libdragonInfo) {
   ]);
 
   log(chalk.green(`libdragon ready at \`${newInfo.root}\`.`));
+  return newInfo;
 }
 
 module.exports = {
   name: 'init',
   fn: init,
   showStatus: true,
+  usage: {
+    name: 'init',
+    summary: 'Create a libdragon project in the current directory.',
+    description: `Creates a libdragon project in the current directory. Every libdragon project will have its own docker container instance. If you are in a git repository or an NPM project, libdragon will be initialized at their root also marking there with a \`.libdragon\` folder. Do not remove the \`.libdragon\` folder and commit its contents if you are using source control, as it keeps persistent libdragon project information.
+
+    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.`,
+    group: ['docker', 'vendoring'],
+  },
 };

package/modules/actions/install.js

@@ -1,52 +1,56 @@
+const chalk = require('chalk');
+
+const { installDependencies, mustHaveProject } = require('./utils');
+const { start } = require('./start');
+const { updateAndStart } = require('./update-and-start');
 const { log } = require('../helpers');
-const {
-  destroyContainer,
-  installDependencies,
-  updateImage,
-} = require('./utils');
-const { fn: start } = require('./start');
 
 /**
  * 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. Maybe we can keep it backward
- * compatible with additional flags.
+ * 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.
  */
-const install = async (libdragonInfo) => {
-  let containerId;
-  const oldImageName = libdragonInfo.imageName;
+const install = async (libdragonInfo, skipUpdate) => {
+  await mustHaveProject(libdragonInfo);
+  let updatedInfo = libdragonInfo;
   const imageName = libdragonInfo.options.DOCKER_IMAGE;
-  // If an image is provided, always attempt to install it
-  // See https://github.com/anacierdem/libdragon-docker/issues/47
-  if (imageName) {
-    log(`Changing image from \`${oldImageName}\` to \`${imageName}\``);
-
-    // Download the new image and if it is different, re-create the container
-    if (await updateImage(libdragonInfo, imageName)) {
-      await destroyContainer(libdragonInfo);
-    }
-
-    containerId = await start({
-      ...libdragonInfo,
-      imageName,
-    });
+  // If an image is provided, attempt to install
+  if (imageName && skipUpdate !== true) {
+    log(
+      chalk.yellow(
+        'Using `install` action to update the docker image is deprecated. Use the `update` action instead.'
+      )
+    );
+    updatedInfo = await updateAndStart(libdragonInfo);
   } else {
     // Make sure existing one is running
-    containerId = await start(libdragonInfo);
+    updatedInfo = {
+      ...updatedInfo,
+      containerId: await start(libdragonInfo),
+    };
   }
 
   // Re-install vendors on new image
   // TODO: skip this if unnecessary
-  await installDependencies({
-    ...libdragonInfo,
-    imageName,
-    containerId,
-  });
+  await installDependencies(updatedInfo);
+  return updatedInfo;
 };
 
 module.exports = {
   name: 'install',
   fn: install,
   showStatus: true,
+  usage: {
+    name: 'install',
+    summary: 'Vendor libdragon as is.',
+    description: `Attempts to build and install everything libdragon related into the container. This includes all the tools and third parties used by libdragon except for the toolchain. If you have made changes to libdragon, you can execute this action to build everything based on your changes. Requires you to have an intact vendoring target (also see the \`--directory\` flag). If you are not working on libdragon itself, you can just use the \`update\` action instead.
+
+    Must be run in an initialized libdragon project. This can be useful to recover from a half-baked container.`,
+  },
 };

package/modules/actions/make.js

@@ -0,0 +1,19 @@
+const { fn: exec } = require('./exec');
+
+const make = async (libdragonInfo, params) => {
+  return await exec(libdragonInfo, ['make', ...params]);
+};
+
+module.exports = {
+  name: 'make',
+  fn: make,
+  forwardsRestParams: true,
+  showStatus: true,
+  usage: {
+    name: 'make [params]',
+    summary: 'Run the libdragon build system in the current directory.',
+    description: `Runs the libdragon build system in the current directory. It will mirror your current working directory to the container.
+
+    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

@@ -0,0 +1,122 @@
+const path = require('path');
+const fsClassic = require('fs');
+
+const _ = require('lodash');
+
+const { dockerHostUserParams } = require('./docker-utils');
+
+const { CONTAINER_TARGET_PATH } = require('../constants');
+const {
+  fileExists,
+  toPosixPath,
+  spawnProcess,
+  dockerExec,
+  ValidationError,
+} = require('../helpers');
+
+async function findNPMRoot() {
+  try {
+    const root = path.resolve((await runNPM(['root'])).trim(), '..');
+    // Only report if package.json really exists. npm fallbacks to cwd
+    if (await fileExists(path.join(root, 'package.json'))) {
+      return root;
+    }
+  } catch {
+    // User does not have and does not care about NPM if it didn't work
+    return undefined;
+  }
+}
+
+// Install other NPM dependencies if this is an NPM project
+const installNPMDependencies = async (libdragonInfo) => {
+  const npmRoot = await findNPMRoot();
+  if (npmRoot) {
+    const packageJsonPath = path.join(npmRoot, 'package.json');
+
+    const { dependencies, devDependencies } = require(packageJsonPath);
+
+    const deps = await Promise.all(
+      Object.keys({
+        ...dependencies,
+        ...devDependencies,
+      })
+        .filter((dep) => dep !== 'libdragon')
+        .map(async (dep) => {
+          const npmPath = await runNPM(['ls', dep, '--parseable=true']);
+          return {
+            name: dep,
+            paths: _.uniq(npmPath.split('\n').filter((f) => f)),
+          };
+        })
+    );
+
+    await Promise.all(
+      deps.map(({ name, paths }) => {
+        return new Promise((resolve, reject) => {
+          fsClassic.access(
+            path.join(paths[0], 'Makefile'),
+            fsClassic.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;
+              }
+
+              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',
+                  ]
+                );
+
+                resolve();
+              } catch (e) {
+                reject(e);
+              }
+            }
+          );
+        });
+      })
+    );
+  }
+};
+
+function runNPM(params) {
+  return spawnProcess(
+    /^win/.test(process.platform) ? 'npm.cmd' : 'npm',
+    params
+  );
+}
+module.exports = {
+  installNPMDependencies,
+  findNPMRoot,
+};

package/modules/actions/start.js

@@ -2,12 +2,12 @@ const chalk = require('chalk');
 
 const { CONTAINER_TARGET_PATH } = require('../constants');
 const { spawnProcess, log, dockerExec } = require('../helpers');
-const { setProjectInfoToSave } = require('../project-info');
 
 const {
   checkContainerAndClean,
   checkContainerRunning,
   destroyContainer,
+  mustHaveProject,
 } = require('./utils');
 
 /**
@@ -75,19 +75,17 @@ const initContainer = async (libdragonInfo) => {
       chalk.green(`Successfully initialized docker container: ${name.trim()}`)
     );
 
-  // Schedule an update to write image name
-  setProjectInfoToSave(libdragonInfo);
   return newId;
 };
 
-const start = async (libdragonInfo) => {
+const start = async (libdragonInfo, skipProjectCheck) => {
+  !skipProjectCheck && (await mustHaveProject(libdragonInfo));
   const running =
     libdragonInfo.containerId &&
     (await checkContainerRunning(libdragonInfo.containerId));
 
   if (running) {
     log(`Container ${running} already running.`, true);
-    log(libdragonInfo.containerId);
     return running;
   }
 
@@ -96,19 +94,29 @@ const start = async (libdragonInfo) => {
   if (!id) {
     log(`Container does not exist, re-initializing...`, true);
     id = await initContainer(libdragonInfo);
-    log(id);
     return id;
   }
 
   log(`Starting container: ${id}`, true);
   await spawnProcess('docker', ['container', 'start', id]);
 
-  log(id);
   return id;
 };
 
 module.exports = {
   name: 'start',
-  fn: start,
+  fn: async (libdragonInfo) => {
+    const containerId = await start(libdragonInfo);
+    log(containerId);
+    return { ...libdragonInfo, containerId };
+  },
+  start,
   showStatus: false, // This will only print out the id
+  usage: {
+    name: 'start',
+    summary: 'Start the container for current project.',
+    description: `Start the container assigned to the current libdragon project. Will first attempt to start an existing container if found, followed by a new container run and installation similar to the \`install\` action. Will always print out the container id on success.
+
+      Must be run in an initialized libdragon project.`,
+  },
 };

package/modules/actions/stop.js

@@ -0,0 +1,29 @@
+const { spawnProcess } = require('../helpers');
+
+const { checkContainerRunning, mustHaveProject } = require('./utils');
+
+const stop = async (libdragonInfo) => {
+  await mustHaveProject(libdragonInfo);
+  const running =
+    libdragonInfo.containerId &&
+    (await checkContainerRunning(libdragonInfo.containerId));
+  if (!running) {
+    return;
+  }
+
+  await spawnProcess('docker', ['container', 'stop', running]);
+  return libdragonInfo;
+};
+
+module.exports = {
+  name: 'stop',
+  fn: stop,
+  showStatus: false, // This will only print out the id
+  usage: {
+    name: 'stop',
+    summary: 'Stop the container for current project.',
+    description: `Stop the container assigned to the current libdragon project.
+
+      Must be run in an initialized libdragon project.`,
+  },
+};

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

@@ -0,0 +1,33 @@
+const { log } = require('../helpers');
+const { updateImage, destroyContainer } = require('./utils');
+const { start } = require('./start');
+
+async function updateAndStart(libdragonInfo) {
+  const oldImageName = libdragonInfo.imageName;
+  const imageName = libdragonInfo.options.DOCKER_IMAGE ?? oldImageName;
+  // If an image is provided, always attempt to install it
+  // See https://github.com/anacierdem/libdragon-docker/issues/47
+  if (oldImageName !== imageName) {
+    log(`Updating image from \`${oldImageName}\` to \`${imageName}\``);
+  } else {
+    log(`Updating image \`${oldImageName}\``);
+  }
+
+  // Download the new image and if it is different, re-create the container
+  if (await updateImage(libdragonInfo, imageName)) {
+    await destroyContainer(libdragonInfo);
+  }
+
+  return {
+    ...libdragonInfo,
+    imageName,
+    containerId: await start({
+      ...libdragonInfo,
+      imageName,
+    }),
+  };
+}
+
+module.exports = {
+  updateAndStart,
+};

package/modules/actions/update.js

@@ -1,18 +1,12 @@
-const path = require('path');
-
 const { log } = require('../helpers');
 const { LIBDRAGON_GIT, LIBDRAGON_BRANCH } = require('../constants');
-const { runGitMaybeHost } = require('./utils');
-const { fn: start } = require('./start');
+const { runGitMaybeHost, mustHaveProject } = require('./utils');
 const { fn: install } = require('./install');
+const { updateAndStart } = require('./update-and-start');
 
 const update = async (libdragonInfo) => {
-  const containerId = await start(libdragonInfo);
-
-  const newInfo = {
-    ...libdragonInfo,
-    containerId,
-  };
+  await mustHaveProject(libdragonInfo);
+  const newInfo = await updateAndStart(libdragonInfo);
 
   if (newInfo.vendorStrategy !== 'manual') {
     log(`Updating ${newInfo.vendorStrategy}...`);
@@ -31,18 +25,28 @@ const update = async (libdragonInfo) => {
       'subtree',
       'pull',
       '--prefix',
-      path.relative(libdragonInfo.root, libdragonInfo.vendorDirectory),
+      libdragonInfo.vendorDirectory,
       LIBDRAGON_GIT,
       LIBDRAGON_BRANCH,
       '--squash',
     ]);
   }
 
-  await install(newInfo);
+  // The second parameter forces it to skip the image update step as we already
+  // do that above.
+  return await install(newInfo, true);
 };
 
 module.exports = {
   name: 'update',
   fn: update,
   showStatus: true,
+  usage: {
+    name: 'update',
+    summary: 'Update libdragon and do an install.',
+    description: `Will update the docker image and if you are using auto-vendoring (see \`--strategy\`), will also update the submodule/subtree from the remote branch (\`trunk\`) with a merge/squash strategy and then perform a \`libdragon install\`. You can use the \`install\` action to only update all libdragon related artifacts in the container.
+
+      Must be run in an initialized libdragon project.`,
+    group: ['docker'],
+  },
 };