@liquicode/devops
v0.0.20
Published
A utility for devops, CI/CD, and general automation.
Downloads
52
Maintainers
Readme
@liquicode/devops
Home: http://devops.liquicode.com
Version: 0.0.20
A utility for devops, CI/CD, and general automation.
Quick Start
Install with NPM:
# Install locally into your project:
npm install --save @liquicode/devops
# - or -
# Install globally onto your machine for all your projects:
npm install --global @liquicode/devops
Run from the command line
# Use the npx command to resolve the installation of devops and run it.
# This works if installed locally or globally.
# This works even if not installed. Npx will find the latest version online and run it.
npx @liquicode/devops <taskfile>
See below for more command line options.
Overview
devops
is a command runner that executes commands that are defined as Javascript objects and are stored within a json/js "tasks" file.
Commands, Steps, and Tasks
Commands perform actions on your environment such as copying files or running a shell command.
Each command has specific parameters that provide the command with specific details of what to do.
For example, the $CopyFile
command requires from
and to
paramteters to tell it which file to copy and to where
Each command specifies its parameters as a Javascript object.
{ $CopyFile: { from: 'readme.md', to: 'docs/readme.md' } } // A single step
Commands are grouped together as steps within a task.
Tasks provide logical units that can be executed directly via the devops
command line,
making tasks runnable from batch/shell files or other types of tools.
Each task defines an array of steos.
{
clear_folder: [ // <-- A Task
{ $RemoveFolder: { folder: 'data/temp', force: true } }, // <-- Steps in a task
{ $EnsureFolder: { folder: 'data/temp' } }, // <-- Steps in a task
],
}
The Tasks File
Multiple tasks can be defined within a single tasks file.
You can use the $RunTask
command in one task to run another task within the same file.
{
clear_folder: [
{ $RemoveFolder: { folder: 'data/temp', force: true } },
{ $EnsureFolder: { folder: 'data/temp' } },
],
build_docs: [
{ $RunTask: { task: 'clear_folder' } },
...
],
}
The Task Context
Each task file maintains a Context
object that is shared among all tasks and steps within a file.
Many of the devops
commands have the ability to read and write values into the Context
object.
You can specify an initial context within the tasks file.
{
// Initial context values for this file
Context: {
message: 'Hello World!',
},
// Tasks ...
default: [
{ $PrintContext: { context: 'message', out: { console: true } } },
],
}
// Prints: Hello World!
Context variables can be referenced within string values by using the ${variable-name}
notation.
{
Context: { temp_folder: 'files/temp' },
default: [
{ $CopyFile: { from: 'data.json', to: '${temp_folder}/data.json' } },
],
}
Task File Structure
The .js
version of a tasks file:
module.exports = {
// Optional context initialization.
Context: {
message: 'Hello World!',
},
// Tasks ...
Task1: [
// Steps ...
{ $CopyFile: { from: 'file1.json', to: 'data.json' } },
Step2,
Step3,
...
],
Task2: [ ... ],
...
};
Command Line Parameters
When devops
runs, it loads a tasks file and executes all commands in relation to the current working directory.
All command line parameters are optional.
execution_folder
: Makes this folder the current working directory during execution. Defaults to the process' current working directory.package_filename
: Apackage.json
file to load and store into the Context aspackage
. Will also change theexecution_folder
to this folder. (Aliases:package
orp
)tasks_filename
: The tasks file containing commands to execute. If this is not specified,devops
looks for adevops.tasks.js
or adevops.tasks.json
file. (Aliases:tasks
ort
)task_name
: The name of the task within the tasks file to run. If not specified, a task calleddefault
will be run.
Command Listing
See the Command Reference for full command documentation.
Child Process Commands
$Shell
Execute a command line.
11 Fields :
command
,halt_on_error
,out.as
,out.console
,out.log
,out.filename
,out.context
,err.console
,err.log
,err.filename
,err.context
Context Commands
$LoadJsModule
Loads (requires) a Javascript module (.js) file into a context variable.
6 Fields :
filename
,out.as
,out.console
,out.log
,out.filename
,out.context
$PrintContext
Prints a context variable value to the output.
6 Fields :
context
,out.as
,out.console
,out.log
,out.filename
,out.context
$SemverInc
Increments a semver formatted version number stored in the context.
1 Fields :
context
$SetContext
Sets a field in the context.
2 Fields :
context
,value
File System Commands
$AppendTextFile
Appends text to a file. The file is created if it does not exist.
2 Fields :
filename
,value
$ClearFolder
Removes all files from a folder.
2 Fields :
folder
,recurse
$CopyFile
Copies a file from one folder to another. If the destination path does not exist, it will be created
2 Fields :
from
,to
$CopyFolder
Copies a folder and its contents from one path to another.
2 Fields :
from
,to
$EnsureFolder
Makes sure that the specified folder exists. Creates the folder and any intermediate folders if needed.
1 Fields :
folder
$PrependTextFile
Inserts text into the beginning of a file. The file is created if it does not exist.
2 Fields :
filename
,value
$ReadJsonFile
Reads the contents of a json file or field.
7 Fields :
filename
,field
,out.as
,out.console
,out.log
,out.filename
,out.context
$ReadTextFile
Reads the contents of a text file.
6 Fields :
filename
,out.as
,out.console
,out.log
,out.filename
,out.context
$RemoveFolder
Removes a folder.
2 Fields :
folder
,force
Flow Control Commands
$Halt
Halts execution of the current task.
No Fields
$If
Conditionally execute steps based on the state of the Context.
3 Fields :
criteria
,then
,else
$Noop
Performs no operation and is ignored.
No Fields
$RunSteps
Runs a set of steps defined within this step.
1 Fields :
steps
$RunTask
Runs another task found in the same devops task file.
1 Fields :
task
Internet Commands
$GetResource
Downloads a resource from the internet and stores it to a file and/or Context variable.
7 Fields :
url
,as
,out.as
,out.console
,out.log
,out.filename
,out.context
Scripting Commands
$ExecuteEjs
Processes a document file or string containing Embedded Javascript (ejs) code.
15 Fields :
ejs_file
,ejs_string
,ejs_start
,ejs_end
,use_eval
,debug_script.as
,debug_script.console
,debug_script.log
,debug_script.filename
,debug_script.context
,out.as
,out.console
,out.log
,out.filename
,out.context
$ExecuteJs
Executes Javascript code within a string or a file.
8 Fields :
code_file
,code_string
,use_eval
,out.as
,out.console
,out.log
,out.filename
,out.context