feat: add run and exec commands for executing commands in monorepo packages (#1151)

The only reason we keep lerna about is for running scripts and commands
in monorepo packages. Unlike npm it's clever enough to figure out the
dependency graph of monorepo packages before running the commands or
scripts in order to ensure that they've been run in a modules
dependencies before being run in that module.

This PR adds two new commands to aegir that do the same thing:

1. exec - this will run a binary command in each monorepo package
2. run - this will run one or more npm scripts in each package

E.g. run `ls` in every package

```console
$ aegir exec ls
```

E.g. clean and build every package

```console
$ aegir run clean build
```

Both commands support forwarding args:

E.g. lint every package, fixing errors

```console
$ aegir run lint -- --fix
```

Author: achingbrain

src/cmds/exec.js

@@ -0,0 +1,42 @@
+import { loadUserConfig } from '../config/user.js'
+import execCmd from '../exec.js'
+
+/**
+ * @typedef {import("yargs").Argv} Argv
+ * @typedef {import("yargs").Arguments} Arguments
+ * @typedef {import("yargs").CommandModule} CommandModule
+ */
+
+const EPILOG = `Example:
+
+$ aegir exec david -- update
+`
+
+/** @type {CommandModule} */
+export default {
+  command: 'exec <command>',
+  describe: 'Run a command in each project of a monorepo',
+  /**
+   * @param {Argv} yargs
+   */
+  builder: async (yargs) => {
+    const userConfig = await loadUserConfig()
+
+    return yargs
+      .epilog(EPILOG)
+      .options({
+        bail: {
+          type: 'boolean',
+          describe: '',
+          default: userConfig.build.bundle
+        }
+      })
+  },
+
+  /**
+   * @param {any} argv
+   */
+  async handler (argv) {
+    await execCmd.run(argv)
+  }
+}

src/cmds/run.js

@@ -0,0 +1,45 @@
+import { loadUserConfig } from '../config/user.js'
+import runCmd from '../run.js'
+
+/**
+ * @typedef {import("yargs").Argv} Argv
+ * @typedef {import("yargs").Arguments} Arguments
+ * @typedef {import("yargs").CommandModule} CommandModule
+ */
+
+const EPILOG = `Example:
+
+$ aegir run clean build
+`
+
+/** @type {CommandModule} */
+export default {
+  command: 'run <scripts..>',
+  describe: 'Run one or more npm scripts in each project of a monorepo',
+  /**
+   * @param {Argv} yargs
+   */
+  builder: async (yargs) => {
+    const userConfig = await loadUserConfig()
+
+    return yargs
+      .epilog(EPILOG)
+      .options({
+        bail: {
+          type: 'boolean',
+          describe: '',
+          default: userConfig.build.bundle
+        }
+      })
+      .positional('script', {
+        array: true
+      })
+  },
+
+  /**
+   * @param {any} argv
+   */
+  async handler (argv) {
+    await runCmd.run(argv)
+  }
+}

src/config/user.js

@@ -131,6 +131,12 @@ const defaults = {
       '@types/*',
       'aegir'
     ]
+  },
+  exec: {
+    bail: true
+  },
+  run: {
+    bail: true
   }
 }
 

src/exec.js

@@ -0,0 +1,36 @@
+import { everyMonorepoProject } from './utils.js'
+import { execa } from 'execa'
+import kleur from 'kleur'
+
+/**
+ * @typedef {import("./types").GlobalOptions} GlobalOptions
+ * @typedef {import("./types").ExecOptions} ExecOptions
+ */
+
+export default {
+  /**
+   * @param {GlobalOptions & ExecOptions & { command: string }} ctx
+   */
+  async run (ctx) {
+    const forwardOptions = ctx['--'] ? ctx['--'] : []
+
+    await everyMonorepoProject(process.cwd(), async (project) => {
+      console.info('') // eslint-disable-line no-console
+      console.info(kleur.grey(`${project.manifest.name} > ${ctx.command} ${forwardOptions.join(' ')}`)) // eslint-disable-line no-console
+
+      try {
+        await execa(ctx.command, forwardOptions, {
+          cwd: project.dir,
+          stderr: 'inherit',
+          stdout: 'inherit'
+        })
+      } catch (/** @type {any} */ err) {
+        if (ctx.bail !== false) {
+          throw err
+        }
+
+        console.info(kleur.red(err.stack)) // eslint-disable-line no-console
+      }
+    })
+  }
+}

src/index.js

@@ -17,6 +17,8 @@ import releaseCmd from './cmds/release.js'
 import testDependantCmd from './cmds/test-dependant.js'
 import testCmd from './cmds/test.js'
 import docsCmd from './cmds/docs.js'
+import execCmd from './cmds/exec.js'
+import runCmd from './cmds/run.js'
 
 /**
  * @typedef {import('./types').BuildOptions} BuildOptions
@@ -89,6 +91,8 @@ async function main () {
   res.command(releaseCmd)
   res.command(testDependantCmd)
   res.command(testCmd)
+  res.command(execCmd)
+  res.command(runCmd)
 
   try {
     await res.parse()

src/run.js

@@ -0,0 +1,48 @@
+import { everyMonorepoProject } from './utils.js'
+import { execa } from 'execa'
+import kleur from 'kleur'
+
+/**
+ * @typedef {import("./types").GlobalOptions} GlobalOptions
+ * @typedef {import("./types").RunOptions} RunOptions
+ */
+
+export default {
+  /**
+   * @param {GlobalOptions & RunOptions & { scripts: string[] }} ctx
+   */
+  async run (ctx) {
+    const scripts = ctx.scripts
+
+    if (scripts == null || scripts.length === 0) {
+      throw new Error('Please specify a script')
+    }
+
+    const forwardArgs = ctx['--'] == null ? [] : ['--', ...ctx['--']]
+
+    await everyMonorepoProject(process.cwd(), async (project) => {
+      for (const script of scripts) {
+        if (project.manifest.scripts[script] == null) {
+          continue
+        }
+
+        console.info('') // eslint-disable-line no-console
+        console.info(kleur.grey(`${project.manifest.name} > npm run ${script} ${forwardArgs.join(' ')}`)) // eslint-disable-line no-console
+
+        try {
+          await execa('npm', ['run', script, ...forwardArgs], {
+            cwd: project.dir,
+            stderr: 'inherit',
+            stdout: 'inherit'
+          })
+        } catch (/** @type {any} */ err) {
+          if (ctx.bail !== false) {
+            throw err
+          }
+
+          console.info(kleur.red(err.stack)) // eslint-disable-line no-console
+        }
+      }
+    })
+  }
+}

src/types.ts

@@ -32,6 +32,14 @@ interface Options extends GlobalOptions {
    * Options for the `dependency-check` command
    */
   dependencyCheck: DependencyCheckOptions
+  /**
+   * Options for the `exec` command
+   */
+  exec: ExecOptions
+  /**
+   * Options for the `run` command
+   */
+  run: RunOptions
 }
 
 /**
@@ -309,6 +317,20 @@ interface DependencyCheckOptions {
   productionInput: string[]
 }
 
+interface ExecOptions {
+  /**
+   * If false, the command will continue to be run in other packages
+   */
+  bail?: boolean
+}
+
+interface RunOptions {
+  /**
+   * If false, the command will continue to be run in other packages
+   */
+  bail?: boolean
+}
+
 export type {
   PartialOptions,
   Options,
@@ -319,5 +341,7 @@ export type {
   LintOptions,
   TestOptions,
   ReleaseOptions,
-  DependencyCheckOptions
+  DependencyCheckOptions,
+  ExecOptions,
+  RunOptions
 }

src/utils.js

@@ -20,6 +20,7 @@ import envPaths from 'env-paths'
 import lockfile from 'proper-lockfile'
 import { fileURLToPath } from 'url'
 import Listr from 'listr'
+import glob from 'it-glob'
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url))
 const EnvPaths = envPaths('aegir', { suffix: '' })
@@ -300,3 +301,150 @@ export function findBinary (bin) {
   // let shell work it out or error
   return bin
 }
+
+/**
+ * @typedef {object} Project
+ * @property {any} manifest
+ * @property {string} dir
+ * @property {string[]} siblingDependencies
+ * @property {string[]} dependencies
+ * @property {boolean} run
+ */
+
+/**
+ * @param {string} projectDir
+ * @param {(project: Project) => Promise<void>} fn
+ */
+export async function everyMonorepoProject (projectDir, fn) {
+  const manifest = fs.readJSONSync(path.join(projectDir, 'package.json'))
+  const workspaces = manifest.workspaces
+
+  if (!workspaces || !Array.isArray(workspaces)) {
+    throw new Error('No monorepo workspaces found')
+  }
+
+  /** @type {Record<string, Project>} */
+  const projects = await parseProjects(projectDir, workspaces)
+
+  checkForCircularDependencies(projects)
+
+  /**
+   * @param {Project} project
+   */
+  async function run (project) {
+    if (project.run) {
+      return
+    }
+
+    for (const siblingDep of project.siblingDependencies) {
+      await run(projects[siblingDep])
+    }
+
+    if (project.run) {
+      return
+    }
+
+    project.run = true
+    await fn(project)
+  }
+
+  for (const project of Object.values(projects)) {
+    await run(project)
+  }
+}
+
+/**
+ *
+ * @param {string} projectDir
+ * @param {string[]} workspaces
+ */
+async function parseProjects (projectDir, workspaces) {
+  /** @type {Record<string, Project>} */
+  const projects = {}
+
+  for (const workspace of workspaces) {
+    for await (const subProjectDir of glob('.', workspace, {
+      cwd: projectDir,
+      absolute: true
+    })) {
+      const pkg = fs.readJSONSync(path.join(subProjectDir, 'package.json'))
+
+      projects[pkg.name] = {
+        manifest: pkg,
+        dir: subProjectDir,
+        siblingDependencies: [],
+        run: false,
+        dependencies: [
+          ...Object.keys(pkg.dependencies ?? {}),
+          ...Object.keys(pkg.devDependencies ?? {}),
+          ...Object.keys(pkg.optionalDependencies ?? {}),
+          ...Object.keys(pkg.peerDependencies ?? {})
+        ]
+      }
+    }
+  }
+
+  for (const project of Object.values(projects)) {
+    for (const dep of project.dependencies) {
+      if (projects[dep] != null) {
+        project.siblingDependencies.push(dep)
+      }
+    }
+  }
+
+  return projects
+}
+
+/**
+ * @param {Record<string, Project>} projects
+ */
+function checkForCircularDependencies (projects) {
+  /**
+   * @param {Project} project
+   * @param {string} target
+   * @param {Set<string>} checked
+   * @param {string[]} chain
+   * @returns {string[] | undefined}
+   */
+  function dependsOn (project, target, checked, chain) {
+    chain = [...chain, project.manifest.name]
+
+    if (project.manifest.name === target) {
+      return chain
+    }
+
+    for (const dep of project.siblingDependencies) {
+      if (checked.has(dep)) {
+        // already checked this dep
+        return
+      }
+
+      checked.add(dep)
+
+      if (dep === target) {
+        // circular dependency detected
+        chain.push(target)
+        return chain
+      }
+
+      const subChain = dependsOn(projects[dep], target, checked, chain)
+
+      if (subChain != null) {
+        return subChain
+      }
+    }
+  }
+
+  // check for circular dependencies
+  for (const project of Object.values(projects)) {
+    for (const siblingDep of project.siblingDependencies) {
+      const sibling = projects[siblingDep]
+
+      const chain = dependsOn(sibling, project.manifest.name, new Set([sibling.manifest.name]), [project.manifest.name])
+
+      if (chain != null) {
+        throw new Error(`Circular dependency detected: ${chain.join(' -> ')}`)
+      }
+    }
+  }
+}