rafamel
kpo
A task runner that goes where npm scripts won't, for the true capo.
Install
Run npm install -g kpo for a global install.
Table of Contents
Usage
kpo can be used programmatically or with its CLI.
Tasks (see definition) are plain synchronous or asynchronous functions that take a Context as an argument.
Tasks can be used in an exclusively programmatic manner or with kpo's CLI. The CLI expects a kpo.tasks.js file exporting a a Task.Record as a default.
Contexts are used by tasks to determine things such as the current working directory, environment variables, cancellation state, logging level, or stdio streams. In that sense, tasks, at least those created with kpo's creation functions, are independent of the process current state and can be cancelled. A task's context can in turn be manipulated to be different only for certain tasks, even within a group of serial or parallel tasks.
Programmatic Usage
- Tasks
- Creation
- Aggregate
- Exception
- Filesystem
- Process
exec: spawns a process.
- Schedule
- Stdio
log: prints a message with a given logging level.print: prints a message.clear: clears the stdout.silence: suppresses the stdio for a task.announce: logs a task route before execution and/or upon success.interactive: marks a task as interactive to error or run an alternate task on non-interactive environments.progress: shows a spinner while the task is in progress.prompt: prompts for a user response.confirm: executes a task in response to user confirmation or rejection.select: executes a task in response to user selection.
- Reflection
- Utils
run: runs a task.style: styles a string.fetch: fetches a file with a tasks record as a default export.recreate: maps all tasks in a tasks record.isCI: indicates whether a context environment variables indicate it's running in a CI.isCancelled: resolves with the current cancellation state for a context.isInteractive: indicates whether a context is that of an interactive environment.isLevelActive: indicates whether a logging level is enabled for a context.
CLI Usage
Common options
These are common options for all kpo subcommands. They must always be passed before any subcommand or scope.
Usage:
$ kpo [options] [command]
Options:
-f, --file <path> Configuration file
-d, --dir <path> Project directory
-e, --env <value> Environment variables
--level <value> Logging level
--prefix Prefix tasks output with their route
-h, --help Show help
-v, --version Show version number
Commands:
:run Runs tasks (default)
:watch Watch paths and run tasks on change events
:list List available tasks
:lift Lift tasks to package
Examples:
$ kpo foo bar baz
$ kpo -e NODE_ENV=development -e BABEL_ENV=node :run fookpo :run
Runs tasks.
kpo :run doesn't take additional options, other than the common options.
Note that the :run command can be omitted. When no command is passed, kpo will assume you're passing it tasks to run. Hence, kpo :run foo bar and kpo foo bar are equivalent.
kpo :watch
Watch a path and run tasks on change events
Usage:
$ kpo :watch [options] -- [args]
Options:
-g, --glob Parse globs in paths
-p, --prime Runs the task once when ready to wait for changes
-f, --fail Finalizes the watch effort if a given task fails
-c, --clear Clear stdout before tasks execution
-i, --include <value> Paths to include
-e, --exclude <value> Paths to exclude
-s, --symlinks Follow symlinks
--parallel Don't cancel running tasks
--debounce <number> Avoid rapid task restarts (ms)
--depth <number> Limit subdirectories to traverse
--poll <number> Use polling for every ms interval
-h, --help Show help
Examples:
$ kpo :watch -i ./src foo bar baz
$ kpo :watch -i ./src -i ./test foo
$ kpo -e NODE_ENV=development :watch -i ./src barkpo :list
List available tasks
Usage:
$ kpo :list [options]
Options:
--defaults List default tasks and subtasks by their own
-h, --help Show helpkpo :lift
Lift tasks to a package.json
Usage:
$ kpo :lift [options]
Options:
--purge Purge all non-kpo scripts
--defaults Lift default tasks and subtasks by their own
--mode <value> Lift mode of operation (confirm, fix, dry, audit)
-h, --help Show help