feat: argument placeholders

Author: bubkoo

README.md

@@ -72,7 +72,7 @@ Then we can use `run-shared-scripts` to define and run these similar `"scripts"`
     "build:esm": "tsc --module esnext --target es2015 --outDir ./es",
     "build:cjs": "tsc --module commonjs --target es5 --outDir ./lib",
     "build:umd": "rollup -c",
-    "build:style": { 
+    "build:style": {
       "file": "./scripts/build-style.js" // path relative to monorepo's root directory
     },
     "build": "run-p build:style build:cjs build:esm build:umd",
@@ -118,11 +118,58 @@ The `rss` command run the same named(the key of `"scripts"`) task by default. We
 
 ### Run with arguments
 
-Any arguments following `--` will pass to task.
+Arguments before `--` separator are `rss` command args.
 
 ```json
   "scripts": {
-    "test": "rss -- --watch" // run jest in watch mode
+    "test": "rss --dry-run" // run in dry-run model
+  }
+```
+
+Arguments after  `--` separator will pass to task.
+
+```json
+  "scripts": {
+    "test": "rss -- --watch" // will run "jest --watch"
+  }
+```
+
+### Argument placeholders
+
+We can use placeholders to define the `"rss"` scripts.
+
+- `{1}`, `{2}`, ... -- An argument. `{1}` is the 1st argument. `{2}` is the 2nd.
+- `{@}` -- All arguments.
+- `{*}` -- All arguments as combined.
+- `{n=defaultValue}` -- An argument with default value. `n` is the n-th argument.
+
+```json
+  "rss": {
+    "s1": "server --port {1}",
+    "s2": "server -a {1} --port {2}",
+    "s3": "server {@}",
+    "s4": "server {*}",
+    "s5": "server --port {1=8080}",
+    "s6": "server --port1 {1=8080} --port2 {1}",
+    "s7": "server -a {1=0.0.0.0} --port {2=8080}"
+  }
+```
+
+Then pass your args in the `"scripts"`.
+
+```json
+  "scripts": {
+    "s1": "rss -- 8080",         // => "server --port 8080"
+    "s2": "rss -- 0.0.0.0 8080", // => "server -a 0.0.0.0 --port 8080"
+    "s3": "rss -- -a 0.0.0.0 --port 8080", // => "server -a 0.0.0.0 --port 8080"
+    "s4": "rss -- -a 0.0.0.0 --port 8080", // => "server '-a 0.0.0.0 --port 8080'"
+    "s5-1": "rss s5",         // => "server --port 8080"
+    "s5-2": "rss s5 -- 9090", // => "server --port 9090"
+    "s6-1": "rss s6",         // => "server --port1 8080 --port2 8080"
+    "s6-1": "rss s6 -- 9090", // => "server --port1 9090 --port2 9090"
+    "s7-1": "rss s7",                    // => "server -a 0.0.0.0 --port 8080"
+    "s7-2": "rss s7 -- '' 9090",         // => "server -a 0.0.0.0 --port 9090"
+    "s7-3": "rss s7 -- 127.0.0.1 9090",  // => "server -a 127.0.0.1 --port 9090"
   }
 ```
 

example/package.json

@@ -19,7 +19,14 @@
     "test": {
       "file": "./scripts/test.js"
     },
-    "pretest": "run-s -s clean:coverage"
+    "pretest": "run-s -s clean:coverage",
+    "start:1": "server --port {1}",
+    "start:2": "server -a {1} --port {2}",
+    "start:3": "server {@}",
+    "start:4": "server {*}",
+    "start:5": "server --port {1=8080}",
+    "start:6": "server --port1 {1=8080} --port2 {1}",
+    "start:7": "server -a {1=0.0.0.0} --port {2=8080}"
   },
   "dependencies": {
     "@babel/core": "^7.20.2",

example/packages/package-a/package.json

@@ -7,11 +7,24 @@
     "clean": "rss",
     "build:esm": "rss",
     "build:cjs": "rss",
+    "build:cjs:watch": "rss build:cjs -- -w",
     "build:umd": "rss",
     "build:dev": "rss",
     "build": "rss",
     "prebuild": "rss",
     "test": "rss",
-    "pretest": "rss"
+    "pretest": "rss",
+    "start:1": "rss --dry-run -- 8080",
+    "start:2": "rss --dry-run -- 0.0.0.0 8080",
+    "start:3": "rss --dry-run -- -a 0.0.0.0 --port 8080",
+    "start:4": "rss --dry-run -- -a 0.0.0.0 --port 8080",
+    "start:5:1": "rss start:5 --dry-run",
+    "start:5:2": "rss start:5 --dry-run -- 9090",
+    "start:6:1": "rss start:6 --dry-run",
+    "start:6:2": "rss start:6 --dry-run -- 9090",
+    "start:7:1": "rss start:7 --dry-run",
+    "start:7:2": "rss start:7 --dry-run -- '' 9090",
+    "start:7:3": "rss start:7 --dry-run -- 127.0.0.1 9090",
+    "start": "run-s -s start:**"
   }
 }

lib/index.js

@@ -3,6 +3,7 @@ import fse from 'fs-extra'
 import path from 'path'
 import crypto from 'crypto'
 import chalk from 'chalk'
+import { quote } from 'shell-quote'
 import { closest } from 'fastest-levenshtein'
 import { findMonorepoRoot } from 'find-monorepo-root'
 import { spawn } from './spawn.js'
@@ -18,7 +19,46 @@ async function ensureTargetDir(root) {
   return targetDir
 }
 
-async function makeExecFile(root, task, cmd, args) {
+function makeExecMain(cmd, args) {
+  const usedPos = []
+  const defaults = []
+  const main = cmd
+    // collect default values
+    .replace(/\{([1-9]\d?)=([^}]+)}/g, (whole, id, defaultValue) => {
+      const pos = id - 1
+      defaults[pos] = defaultValue
+      return `{${id}}`
+    })
+    // replace placeholder
+    .replace(/\{([*@]|[1-9]\d?)}/g, (whole, id) => {
+      if (id === "@" || id === '*') {
+        usedPos.push(...args.map((_, i) => i))
+        return id === '@' ? quote(args) : quote([args.join(' ')])
+      }
+
+
+      const pos = id - 1
+      if (pos >= 0 && pos < args.length) {
+        usedPos.push(pos)
+
+        const arg = args[pos]
+        if (arg && arg.trim()) {
+          return quote([arg])
+        }
+      }
+
+      if (defaults[pos] != null) {
+        return quote([defaults[pos]])
+      }
+
+      return ''
+    })
+
+  const others = args.filter((_, i) => !usedPos.includes(i))
+  return `${main} ${quote(others)}`
+}
+
+async function makeExecFile(root, task, main) {
   const targetDir = await ensureTargetDir(root)
 
   const win32 = process.platform === 'win32'
@@ -35,7 +75,6 @@ async function makeExecFile(root, task, cmd, args) {
   } while (exist)
 
 
-  const main = args.length ? `${cmd} ${args.join(' ')}` : cmd
   const declare = win32 ? '@ECHO OFF' : '#!/usr/bin/env sh'
 
   await fse.writeFile(filePath, `${declare}\n\n${main}`)
@@ -71,6 +110,7 @@ export async function run(task, args, options) {
 
   if (cmd) {
     const isFile = typeof cmd === 'object' && cmd.file != null
+    const main = isFile ? cmd.file : makeExecMain(cmd, args)
 
     let log = '> '
     const eventColor = closest(task, [
@@ -83,18 +123,18 @@ export async function run(task, args, options) {
     ])
     log += chalk[eventColor](`[${task}]`)
     log += ' '
-    log += isFile ? cmd.file : `${cmd}`
+    log += main
     console.log(log)
 
     if (!options.dryRun) {
       const exe = isFile
-        ? fixFilePath(root, cmd.file)
-        : await makeExecFile(root, task, cmd, args)
+        ? fixFilePath(root, main)
+        : await makeExecFile(root, task, main)
 
       const child = spawn(exe, isFile ? args : [], { stdio: 'inherit' })
 
       if (!isFile) {
-        child.on('exit', () => { fse.rmSync(exe) })
+        child.on('exit', () => { fse.rm(exe) })
       }
     }
   } else {

package.json

@@ -59,7 +59,8 @@
     "find-monorepo-root": "^1.0.2",
     "fs-extra": "^10.1.0",
     "meow": "^11.0.0",
-    "pidtree": "^0.6.0"
+    "pidtree": "^0.6.0",
+    "shell-quote": "^1.7.4"
   },
   "devDependencies": {
     "@bubkoo/semantic-release-config": "^1.4.0",