@wizulus/dev-term

dev-term README

This library is a utility for running and managing development tasks in an ANSI enabled terminal. The tool allows you to define a set of tasks and execute them in a specific order. Each task is defined by a set of directives that dictate how it should be run and how it interacts with other tasks.

When the script is running, certain keys will perform different tasks:

• <Left> and <Right>: Select a running task.
• K: Kill the selected task.
• R: Restart the selected task.
• Q or Ctrl-C: Kill all tasks and exit.

Directives

await <name>: [cwd] <command line>

This directive runs a process and waits for it to exit before proceeding. <name> is a unique identifier for the task, [cwd] is an optional current working directory for the process, and <command line> is the command to be executed.

await build: ./project/ npm run build
start server: ./project/ node server.js

---

task <name>: [cwd] <command line>

This directive creates a task but doesn't run it right away. Use restart <name> to start the task. <name> is a unique identifier for the task, [cwd] is an optional current working directory for the process, and <command line> is the command to be executed.

task watch: ./project/ npm run watch
restart watch

---

start <name>: [cwd] <command line>

This directive runs a process and continues with the script. <name> is a unique identifier for the task, [cwd] is an optional current working directory for the process, and <command line> is the command to be executed.

start server: ./project/ node server.js

---

once <otherNames>: <text>

This directive listens for text to be emitted from other processes, then triggers child script once. <otherNames> is a comma-separated list of unique identifiers for the tasks to be listened to, and <text> is the text to be matched.

once build: Compilation complete.
start server: ./project/ node server.js

---

when <otherNames>: <text>

This directive listens for text to be emitted from other processes, and triggers child script each time. <otherNames> is a comma-separated list of unique identifiers for the tasks to be listened to, and <text> is the text to be matched.

when tests: PASS
start server: ./project/ node server.js

---

after <name>: <otherNames>

This directive references when and once directives. After each of them has triggered at least once, triggers child script. <name> is a unique identifier for the task, and <otherNames> is a comma-separated list of unique identifiers for the tasks that should have already triggered.

when tests: PASS
once build: Compilation complete.
after start: tests,build
start server: ./project/ node server.js

---

restart <otherNames>

This directive triggers other script directives to restart. For script directives that run processes, existing processes are killed. For script directives that listen for text, resets their tracking. <otherNames> is a comma-separated list of unique identifiers for the tasks to be restarted.

start server: ./project/ node server.js
when server: [FATAL]
  restart server

group <name>:

This directive provides a logical grouping for script organization. Runs child script immediately. <name> is a unique identifier for the group.

group database:
  start postgres: ./database/ postgres
  start redis: ./database/ redis
start server: ./project/ node server.js

kill <otherNames>

This directive kills a running process. <otherNames> is a comma-separated list of unique identifiers for the tasks to be killed.

start server: ./project/ node server.js
kill server

Sample Script

1. Run npm install --save-dev @wizulus/dev-term to install this library.
2. Create a dev.mjs in your project directory.
3. Run chmod +x dev.mjs
4. Define your script:

#!/usr/bin/env node
import { script } from '@wizulus/dev-term/main.mjs'

script`
  await install: ./project/ npm install
  task build: ./project/ npm run build
  when build: Compilation complete.
  after start: build
  group database:
    start postgres: ./database/ postgres
    start redis: ./database/ redis
  start server: ./project/ node server.js
  group error-check:
    when server: Error listening on port 3000.
      restart server
    when build: ERROR
      kill server
`

5. Run ./dev.mjs to run your script.

The sample script performs the following steps:

1. Waits for dependencies to be installed in the ./project/ directory.
2. Defines a build task that runs the build command in the ./project/ directory but doesn't start it yet.
3. Waits for the build task to emit the message Compilation complete. before proceeding.
4. Defines an after directive that waits for the build task to complete before starting the rest of the script.
5. Defines a database group that starts the postgres and redis services in the ./database/ directory.
6. Starts the server.js script in the ./project/ directory and waits for it to emit the message Server listening on port 3000.
7. Defines an error-check group that listens for error messages from the server.js script and the build task.
8. If the server.js script emits the message Error listening on port 3000., the server.js script is restarted.
9. If the build task emits the message ERROR, the server.js script is killed.

Overall, this script demonstrates the use of various directives to manage a set of development tasks. The await directive is used to wait for dependencies to be installed, while the task directive is used to define a task that can be restarted later. The when and after directives are used to control the order in which tasks are executed, and the group directive is used to organize tasks into logical groups. Finally, the kill and restart directives are used within a child script to handle errors that may occur during the execution of the main script.