@adobe/aio-run-detached

Helper command for the Adobe I/O CLI App Plugin and Adobe Developer App Builder.

This command runs another command in a detached process, and reports to the parent process that calls it, the detached process' pid for cleanup in the future.

You would run your command in a detached process if it is a long running process, and the use case for it is running a command in an App Builder Event Hook.

Usage

You will need to add @adobe/aio-run-detached as a dependency in your project:

npm install @adobe/aio-run-detached

For example, if you have a long running command called long-running-process.sh, and you want to run it in the pre-app-run app hook, you prefix your command with aio-run-detached like so in your app's package.json:

{
  "scripts": {
    "pre-app-run": "aio-run-detached long-running-process.sh"
  }
}

aio-run-detached will report back to the App plugin the process id of the detached process, so that the App plugin can terminate the detached process when the App plugin command exits.

The first argument after aio-run-detached must be an executable. Any subsequent arguments that use shell operators must be quote escaped. See the Shell Operators Must Be Quoted section below.

Logging

Since it is a detached process, logs from stdout and stderr are not available in the terminal. Instead, the logs are written out to disk.

For example:

{
  "scripts": {
    "pre-app-run": "aio-run-detached long-running-process.sh"
  }
}

Log file name format: {processname}.out.log and {processname}.err.log.

In this example, your stdout log will be called long-running-process.sh.out.log and your stderr log will be called long-running-process.sh.err.log.

Both files will be appended to, and will be created if they don't exist, and both will be created inside a logs folder in your current working folder. Make sure you put your logs folder in your .gitignore in case there are secrets being logged. Newly generated templates will have this folder added in .gitignore.

On every run, a timestamp is logged to the log file to differentiate runs.

Shell Operators Must Be Quoted

As an example, pipe, redirection and logical operators must be quoted. This includes other shell operators. If not, the operators will apply to aio-run-detached itself and not to the executable that aio-run-detached will run.

Pipe operator example:

{
  "scripts": {
    "pre-app-run": "aio-run-detached cat package.json '|' jq .version"
  }
}

Redirection operator example:

{
  "scripts": {
    "pre-app-run": "aio-run-detached echo this is fine '>' someFile.txt"
  }
}

Logical operator example:

{
  "scripts": {
    "pre-app-run": "aio-run-detached echo this is ok '&&' echo this is fine"
  }
}

Contributing

Contributions are welcome! Read the Contributing Guide for more information.

Licensing

This project is licensed under the Apache V2 License. See LICENSE for more information.