feat(log): enhance cmd highlighter and make it configurable

.size-limit.json

@@ -16,7 +16,7 @@
   {
     "name": "dts libdefs",
     "path": "build/*.d.ts",
-    "limit": "39 kB",
+    "limit": "39.15 kB",
     "brotli": false,
     "gzip": false
   },
@@ -30,7 +30,7 @@
   {
     "name": "all",
     "path": "build/*",
-    "limit": "851.1 kB",
+    "limit": "850.8 kB",
     "brotli": false,
     "gzip": false
   }

docs/configuration.md

@@ -84,7 +84,7 @@ all `$` processes use `process.cwd()` by default (same as `spawn` behavior).
 
 ## `$.log`
 
-Specifies a [logging function](src/core.ts).
+Specifies a [logging function](src/log.ts).
 
 ```ts
 import {LogEntry, log} from 'zx/core'
@@ -101,6 +101,19 @@ $.log = (entry: LogEntry) => {
 }
 ```
 
+Log mostly acts like a debugger, so by default it uses `process.error` for output.
+Set `log.output` to change the stream.
+
+```ts
+$.log.output = process.stdout
+```
+
+Set `log.formatCmd` to customize the command highlighter:
+
+```ts
+$.log.formatCmd = (cmd: string) => chalk.bgRedBright.black(cmd)
+```
+
 ## `$.timeout`
 
 Specifies a timeout for the command execution.

package.json

@@ -63,7 +63,7 @@
     "fmt": "prettier --write .",
     "fmt:check": "prettier --check .",
     "build": "npm run build:js && npm run build:dts && npm run build:tests",
-    "build:js": "node scripts/build-js.mjs --format=cjs --hybrid --entry=src/*.ts:!src/error.ts:!src/repl.ts:!src/md.ts && npm run build:vendor",
+    "build:js": "node scripts/build-js.mjs --format=cjs --hybrid --entry=src/*.ts:!src/error.ts:!src/repl.ts:!src/md.ts:!src/log.ts && npm run build:vendor",
     "build:vendor": "node scripts/build-js.mjs --format=cjs --entry=src/vendor-*.ts --bundle=all",
     "build:tests": "node scripts/build-tests.mjs",
     "build:dts": "tsc --project tsconfig.json && rm build/error.d.ts build/repl.d.ts && node scripts/build-dts.mjs",

src/core.ts

@@ -44,7 +44,6 @@ import {
 } from './vendor-core.ts'
 import {
   type Duration,
-  log,
   isString,
   isStringLiteral,
   getLast,
@@ -62,7 +61,9 @@ import {
   bufArrJoin,
 } from './util.ts'
 
-export { log, type LogEntry } from './util.ts'
+import { log } from './log.ts'
+
+export { log, type LogEntry } from './log.ts'
 
 const CWD = Symbol('processCwd')
 const SYNC = Symbol('syncExec')

src/log.ts

@@ -0,0 +1,187 @@
+// Copyright 2025 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     https://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+import { chalk, type RequestInfo, type RequestInit } from './vendor-core.ts'
+import { inspect } from 'node:util'
+
+export type LogEntry = {
+  verbose?: boolean
+} & (
+  | {
+      kind: 'cmd'
+      cmd: string
+      id: string
+    }
+  | {
+      kind: 'stdout' | 'stderr'
+      data: Buffer
+      id: string
+    }
+  | {
+      kind: 'end'
+      exitCode: number | null
+      signal: NodeJS.Signals | null
+      duration: number
+      error: null | Error
+      id: string
+    }
+  | {
+      kind: 'cd'
+      dir: string
+    }
+  | {
+      kind: 'fetch'
+      url: RequestInfo
+      init?: RequestInit
+    }
+  | {
+      kind: 'retry'
+      attempt: number
+      total: number
+      delay: number
+      exception: unknown
+      error?: string
+    }
+  | {
+      kind: 'custom'
+      data: any
+    }
+)
+
+type LogFormatter = (cmd?: string) => string
+type Log = {
+  (entry: LogEntry): void
+  formatCmd?: LogFormatter
+  output?: NodeJS.WriteStream
+}
+export const log: Log = function (entry) {
+  if (!entry.verbose) return
+  const stream = log.output || process.stderr
+  switch (entry.kind) {
+    case 'cmd':
+      stream.write((log.formatCmd || formatCmd)(entry.cmd))
+      break
+    case 'stdout':
+    case 'stderr':
+    case 'custom':
+      stream.write(entry.data)
+      break
+    case 'cd':
+      stream.write('$ ' + chalk.greenBright('cd') + ` ${entry.dir}\n`)
+      break
+    case 'fetch':
+      const init = entry.init ? ' ' + inspect(entry.init) : ''
+      stream.write('$ ' + chalk.greenBright('fetch') + ` ${entry.url}${init}\n`)
+      break
+    case 'retry':
+      stream.write(
+        chalk.bgRed.white(' FAIL ') +
+          ` Attempt: ${entry.attempt}${entry.total == Infinity ? '' : `/${entry.total}`}` +
+          (entry.delay > 0 ? `; next in ${entry.delay}ms` : '') +
+          '\n'
+      )
+  }
+}
+
+const SYNTAX = '()[]{}<>;:+|&='
+const CMD_BREAK = new Set(['|', '&', ';', '>', '<'])
+const SPACE_RE = /\s/
+const RESERVED_WORDS = new Set([
+  'if',
+  'then',
+  'else',
+  'elif',
+  'fi',
+  'case',
+  'esac',
+  'for',
+  'select',
+  'while',
+  'until',
+  'do',
+  'done',
+  'in',
+  'EOF',
+])
+
+export const formatCmd: LogFormatter = function (cmd) {
+  if (cmd == undefined) return chalk.grey('undefined')
+  let q = ''
+  let out = '$ '
+  let buf = ''
+  let mode: 'syntax' | 'quote' | 'dollar' | '' = ''
+  let pos = 0
+  const cap = () => {
+    const word = buf.trim()
+    if (word) {
+      pos++
+      if (mode === 'syntax') {
+        if (CMD_BREAK.has(word)) {
+          pos = 0
+        }
+        out += chalk.red(buf)
+      } else if (mode === 'quote' || mode === 'dollar') {
+        out += chalk.yellowBright(buf)
+      } else if (RESERVED_WORDS.has(word)) {
+        out += chalk.cyanBright(buf)
+      } else if (pos === 1) {
+        out += chalk.greenBright(buf)
+        pos = Infinity
+      } else {
+        out += buf
+      }
+    } else {
+      out += buf
+    }
+    mode = ''
+    buf = ''
+  }
+
+  for (const c of [...cmd]) {
+    if (!q) {
+      if (c === '$') {
+        cap()
+        mode = 'dollar'
+        buf += c
+        cap()
+      } else if (c === "'" || c === '"') {
+        cap()
+        mode = 'quote'
+        q = c
+        buf += c
+      } else if (SPACE_RE.test(c)) {
+        cap()
+        buf += c
+      } else if (SYNTAX.includes(c)) {
+        const isEnv = c === '=' && pos === 0
+        isEnv && (pos = 1)
+        cap()
+        mode = 'syntax'
+        buf += c
+        cap()
+        isEnv && (pos = -1)
+      } else {
+        buf += c
+      }
+    } else {
+      buf += c
+      if (c === q) {
+        cap()
+        q = ''
+      }
+    }
+  }
+  cap()
+  return out.replaceAll('\n', chalk.reset('\n> ')) + '\n'
+}