command-workflow

Configurable command workflow that executes specific tasks based on commands. Simple, flexible, and easily expandable.

English|中文文档

Installation

npm install command-workflow -D

Usage

Basic Usage

```bash
# create config file
touch cwf.config.js

// cwf.config.js
import { defineConfig } from 'command-workflow'

const filename = new Date().getTime()

export default defineConfig({
  steps: [
    'ls',
    {
      command: 'touch #{filename}',
      tags: {
        filename: () => {
          console.log('filename:', filename)
          return filename
        }
      }
    }, {
      command: 'vim #{filename}',
      tags: {
        filename: () => {
          return filename
        }
      }
    }],
})

# Run command 
npx cwf
# Run log
$ cwf
11:03:10 AM [CWF] Run command: ls
cwf.config.js           node_modules            package-lock.json       package.json
filename: 1690340590431
11:03:10 AM [CWF] Run command: touch 1690340590431
11:03:10 AM [CWF] Run command: vim 1690340590431
✨  Done in 1.99s.

CWF allows you to use the #{tag} format in the command field to pass custom tags. You can use the tag names as keys in the tags field and pass methods or strings as values to CWF. CWF will parse these tags, apply them to the command, and execute the corresponding operations.
Of course, CWF also provides some built-in tags for your convenience. View

Advanced Usage

# create config file
touch cwf.config.js

// cwf.config.js
import { defineConfig } from 'command-workflow'

const filename = new Date().getTime()

export default defineConfig({
  firstCommand: {
    steps: [{
      command: 'ls',
    }, {
      command: 'touch #{filename}',
      tags: {
        filename: () => {
          console.log('filename:', filename)
          return filename
        }
      }
    }, {
      command: 'vim #{filename}',
      tags: {
        filename: () => {
          return filename
        }
      }
    }],
  }
})

# Run command 
npx cwf firstCommand
# Run log
$ cwf
11:03:10 AM [CWF] Run command: ls
cwf.config.js           node_modules            package-lock.json       package.json
filename: 1690340590431
11:03:10 AM [CWF] Run command: touch 1690340590431
11:03:10 AM [CWF] Run command: vim 1690340590431
✨  Done in 1.99s.

You can customize CWF sub-commands in the configuration file and implement multiple command workflows by appending custom sub-commands after the CWF command. As shown above, by defining a sub-command named firstCommand in the configuration file, you can execute the specified workflow by running the cwf firstCommand command. This way, you can easily configure and execute multiple command workflows according to your needs.

Specify Steps

You can define unikey in steps, and then specify the steps to be executed through the command line.
Use cwf -s 'xxx' to specify the steps to be executed. The value is the unikey you set, use , split.

// cwf.config.js
import { defineConfig } from 'command-workflow'

let gitUser = ''

export default defineConfig({
  steps: [{
    command: 'ls',
    unikey: '1'
  }, {
    unikey: '2',
    command: 'touch #{git_user_name}',
    before: (command, tags) => {
      console.log('before command: ', command)
      console.log('before tags: ', tags)
      gitUser = tags.git_user_name
    },
    after: (command, exec) => {
      console.log('after real command: ', command)
      console.log('after exec: ', exec)
    }
  }, {
    unikey: '3',
    command: 'echo #{user}',
    tags: {
      user: () => gitUser
    }
  }],
})

# Run command 
npx cwf -s '2,3,1'
# Run log
$ cwf -s '2,3,1'
before command:  touch murong
before tags:  { git_user_name: 'murong' }
4:22:41 PM [CWF] Run command: touch murong
after real command:  touch murong
after exec:  null
4:22:41 PM [CWF] Run command: echo murong
murong
4:22:41 PM [CWF] Run command: ls
cwf.config.js           node_modules            package-lock.json       
package.json            murong
✨  Done in 2.21s.

Use hooks

• before: Before executing the command, a callback function can be used to modify the command and tag collection. This callback function takes the command and tag collection as parameters and allows for modifications to the command during execution. Once the callback function has completed, the program will execute the modified command returned by the callback function.
• after: After the command is executed, you can retrieve the executed command and the execution result through a callback function. The callback function takes the command and execution result as parameters, and it does not have a return value. This allows you to conveniently view the final executed command and its corresponding execution result.
• error: When an error occurs during command execution, you can use a callback function to handle the error. The callback function takes the error as a parameter and does not have a return value. This allows you to conveniently handle errors that occur during command execution.

// cwf.config.js
export default defineConfig({
  steps: [{
    command: 'ls',
  }, {
    command: 'touch #{git_user_name}',
    before: (command, tags) => {
      console.log('before command: ', command)
      console.log('before tags: ', tags)
      return `${command}-murong`
    },
    after: (command, exec) => {
      console.log('after real command: ', command)
      console.log('after exec: ', exec)
    },
    // eslint-disable-next-line n/handle-callback-err
    error: (err) => {
      console.log('error:', error)
    }
  }],
})

Built-in tag

Tag	Description	Example
#{timestamp}	Timestamp	touch #{timestamp}
#{current_git_branch}	Current git branch	git checkout -b #{current_git_branch}
#{current_git_commit}	Current git commit hash	git commit -m #{current_git_commit}
#{current_git_commit_message}	Current git commit message	git commit -m #{current_git_commit_message}
#{current_git_tag}	Current git tag	git tag #{current_git_tag}
#{current_git_repo}	Current git repo	git clone #{current_git_repo}
#{current_git_repo_url}	Current git repo url	git clone #{current_git_repo_url}
#{current_git_repo_name}	Current git repo name	echo #{current_git_repo_name}
#{current_git_repo_owner}	Current git repo owner	echo #{current_git_repo_owner}
#{git_user_name}	Local git user name	echo #{git_user_name}
#{git_user_email}	Local git user email	echo #{git_user_email}

Config

UserConfig

Name	Description	Type	Default	Required
steps	workflow step	Step[]		✅
logLevel	log level	error warn info silent	info	❌
logTime	log time options			❌
isSkipError	Whether to skip the error log	boolean	false	❌
isThrowErrorBreak	Do not continue execution if an error occurs	boolean	false	❌

Step

Name	Description	Type	Default	Required
command	command to execute	string		✅
tags	tags map	[x: string]: (() => string)	string
disabled	Whether to disabled command to run	boolean ((command: string, tags: Record<string, any>) => boolean)	false	❌
error	error callback, no return value	(error: Error) => void		❌
before	Callback before the command is executed, the return value is the command you expect to be executed eventually, the return value is not required	(command: string, tags: Record<string, any>) => string		❌
after	Callback after the command is executed, no return value	(command: string, buffer: Buffer) => void		❌

CLI Options

Option	Description	Example
-c, --config <file>	Path to config file	cwf -c cwf.custom.config.js
-r, --root <root>	Path to config root.	cwf -r /Users/murong/documents
-t, --tags <tags>	Global tags for command	cwf --tags 'tag1=1|tag2=2|tag3=3'
-s, --specify-steps <steps>	Specify steps to run, the value is the unikey you set.	cwf -s '1,3,2'