W5S Managed Script (@w5s/managed-script)

CLI tool to manage project scripts. Standardize, remove duplication.

Installation

npm install --save-dev @w5s/managed-script

Usage

Simple example

1. Setup a global configuration

// package.json
{
  "managed-script": {
    "scripts": {
      "my-script": "echo 'Hello world!'"
    }
  }
}

2. Forward execution to managed-script

When you want to use the managed-script configuration simply execute the cli to forward to the configured command. managed-script

// package.json, **/packages.json, etc.
{
  "scripts": {
    "my-script": "managed-script" // > 'Hello world'
  }
}

Global shared configuration (npm)

// package.json
{
  "managed-script": {
    "extends": ["@acme/managed-script-config"], // Extend one or more configuration installed as node package
    "scripts": {
      "my-script": "echo 'Hello world!'" // Configuration can still be overridden
    }
  }
}

Miscellaneous

Working directory and config origins

Use --cwd to choose the directory used to resolve configuration and run the selected script. The equivalent environment variable is MANAGED_SCRIPT_CWD; the CLI option takes precedence over the environment variable, which takes precedence over the current process directory.

Dry run

Use --dry-run,-n to print the resolved command instead of executing it. This is a CLI-only flag; it is not part of the configuration.

Logging

Use --loglevel <level> to control status messages, with silent, error, warn, info (default) and debug levels. --silent,-s and --verbose,-v are shortcuts for --loglevel silent and --loglevel debug; --silent takes precedence if both are passed. Status messages are written to stderr, keeping stdout free for --dry-run output.

The equivalent environment variable is MANAGED_SCRIPT_LOGLEVEL; the CLI option takes precedence over the environment variable. This is a CLI-only flag; it is not part of the configuration.

Scripts receive these environment variables:

• MANAGED_SCRIPT_NAME: the resolved script name.
• MANAGED_SCRIPT_CWD: the invocation directory used to resolve configuration and spawn the script.
• MANAGED_SCRIPT_CONFIG_FILE: the root configuration file, when one was found.
• MANAGED_SCRIPT_CONFIG_DIR: the directory of the configuration layer that declared the selected script.
• MANAGED_SCRIPT_LOGLEVEL: the resolved log level, so the invoked script can match its own verbosity.

The spawn directory always remains MANAGED_SCRIPT_CWD. This lets a shared configuration package ship scripts and locate files beside its config without changing the project's execution context.

Writing scripts with zx

Scripts launched by managed-script can import a $ preset that applies those environment variables as zx defaults (cwd, env, verbose / quiet, inherited stdio, and command logging):

import { $ } from '@w5s/managed-script/zx';

await $`pnpm test`;

Use create$() when you need an explicit context (tests, nested runners) instead of the process environment.

License

MIT © Julien Polo [email protected]