@plugjs/plug 0.0.26 → 0.1.0

package/src/{assert.ts → asserts.ts}

@@ -2,7 +2,42 @@
  * BUILD FAILURES                                                             *
  * ========================================================================== */
 
-import { BuildFailure } from './failure'
+/** A symbol marking {@link BuildFailure} instances */
+const buildFailure = Symbol.for('plugjs:buildFailure')
+
+/** Check if the specified argument is a {@link BuildFailure} */
+export function isBuildFailure(arg: any): arg is BuildFailure {
+  return arg && arg[buildFailure] === buildFailure
+}
+
+/** A {@link BuildFailure} represents an error _already logged_ in our build. */
+export class BuildFailure extends Error {
+  readonly errors!: readonly any[]
+
+  /** Construct a {@link BuildFailure} */
+  private constructor(message: string | undefined, errors: any[]) {
+    super(message || '')
+
+    /* Basic error setup, stack and marker */
+    Error.captureStackTrace(this, BuildFailure)
+    Object.defineProperties(this, {
+      'errors': { value: Object.freeze([ ...errors ]) },
+      [buildFailure]: { value: buildFailure },
+    })
+  }
+
+  static fail(): BuildFailure {
+    return new BuildFailure(undefined, [])
+  }
+
+  static withMessage(message: string): BuildFailure {
+    return new BuildFailure(message || undefined, [])
+  }
+
+  static withErrors(errors: any[]): BuildFailure {
+    return new BuildFailure(undefined, errors)
+  }
+}
 
 /** Await and assert that all specified promises were fulfilled */
 export async function assertPromises<T>(promises: (T | Promise<T>)[]): Promise<T[]> {

package/src/async.ts

@@ -1,5 +1,7 @@
 import { AsyncLocalStorage } from 'node:async_hooks'
 
+import { assert } from './asserts'
+
 import type { Context } from './pipe'
 
 
@@ -40,7 +42,7 @@ export function currentContext(): Context | undefined {
  */
 export function requireContext(): Context {
   const context = storage.getStore()
-  if (! context) throw new Error('Unable to retrieve current context')
+  assert(context, 'Unable to retrieve current context')
   return context
 }
 

package/src/files.ts

@@ -1,5 +1,5 @@
+import { mkdir, writeFile } from './fs'
 import { assertRelativeChildPath, getAbsoluteParent, resolveAbsolutePath } from './paths'
-import { mkdir, writeFile } from './utils/asyncfs'
 
 import type { AbsolutePath } from './paths'
 

package/src/fork.ts

@@ -1,14 +1,13 @@
 import { fork } from 'node:child_process'
 
-import { assert } from './assert'
+import { assert, BuildFailure } from './asserts'
 import { runAsync } from './async'
-import { BuildFailure } from './failure'
 import { Files } from './files'
-import { $gry, $p, logOptions } from './log'
+import { $gry, $p, logOptions } from './logging'
 import { requireFilename, resolveFile } from './paths'
 import { Context, install } from './pipe'
 
-import type { LogOptions } from './log'
+import type { LogOptions } from './logging'
 import type { AbsolutePath } from './paths'
 import type { Plug, PlugName, PlugResult } from './pipe'
 
@@ -16,6 +15,8 @@ import type { Plug, PlugName, PlugResult } from './pipe'
 export interface ForkData {
   /** Script name for the Plug to execute */
   scriptFile: AbsolutePath,
+  /** Export name in the script for the Plug to execute */
+  exportName: string,
   /** Plug constructor arguments */
   constructorArgs: any[],
   /** Task name (for logs) */
@@ -48,11 +49,13 @@ export abstract class ForkingPlug implements Plug<PlugResult> {
   constructor(
       private readonly _scriptFile: AbsolutePath,
       private readonly _arguments: any[],
+      private readonly _exportName: string,
   ) {}
 
   pipe(files: Files, context: Context): Promise<PlugResult> {
     const message: ForkData = {
       scriptFile: this._scriptFile,
+      exportName: this._exportName,
       constructorArgs: this._arguments,
       taskName: context.taskName,
       buildFile: context.buildFile,
@@ -167,6 +170,7 @@ if ((process.argv[1] === requireFilename(__fileurl)) && (process.send)) {
 
     const {
       scriptFile,
+      exportName,
       constructorArgs,
       taskName,
       buildFile,
@@ -189,12 +193,15 @@ if ((process.argv[1] === requireFilename(__fileurl)) && (process.send)) {
       const script = await import(scriptFile)
 
       /* Figure out the constructor, in the "default" chain */
-      let Ctor = script
-      while (Ctor && (typeof Ctor !== 'function')) Ctor = Ctor.default
-
-      /* Check that we have a proper constructor */
-      assert(typeof Ctor === 'function',
-          `Script ${$p(scriptFile)} does not export a default constructor`)
+      let Ctor
+      if (exportName === 'default') {
+        Ctor = script
+        while (Ctor && (typeof Ctor !== 'function')) Ctor = Ctor.default
+        assert(typeof Ctor === 'function', `Script ${$p(scriptFile)} does not export a default constructor`)
+      } else {
+        Ctor = script[exportName]
+        assert(typeof Ctor === 'function', `Script ${$p(scriptFile)} does not export "${exportName}"`)
+      }
 
       /* Create the Plug instance and our Files instance */
       const plug = new Ctor(...constructorArgs) as Plug<PlugResult>
@@ -250,11 +257,12 @@ if ((process.argv[1] === requireFilename(__fileurl)) && (process.send)) {
 export function installForking<Name extends PlugName>(
     plugName: Name,
     scriptFile: AbsolutePath,
+    exportName: string = 'default',
 ): void {
   /** Extend out our ForkingPlug below */
   const ctor = class extends ForkingPlug {
     constructor(...args: any[]) {
-      super(scriptFile, args)
+      super(scriptFile, args, exportName)
     }
   }
 

package/src/{utils/asyncfs.ts → fs.ts}

@@ -1,5 +1,5 @@
-import { constants } from 'node:fs'
 import fsp from 'node:fs/promises'
+import { constants } from 'node:fs'
 
 type FsPromises = typeof fsp
 

package/src/helpers.ts

@@ -1,14 +1,17 @@
-import { assert, assertPromises } from './assert'
+import { assert, assertPromises } from './asserts'
 import { requireContext } from './async'
 import { Files } from './files'
-import { $p, log } from './log'
+import { rm } from './fs'
+import { $p, log } from './logging'
 import { commonPath, getCurrentWorkingDirectory, resolveDirectory, resolveFile } from './paths'
-import { Pipe } from './pipe'
-import { rm } from './utils/asyncfs'
+import { PipeImpl } from './pipe'
+import { execChild } from './utils/exec'
 import { parseOptions } from './utils/options'
 import { walk } from './utils/walk'
 
+import type { Pipe } from './index'
 import type { AbsolutePath } from './paths'
+import type { ExecChildOptions } from './utils/exec'
 import type { ParseOptions } from './utils/options'
 import type { WalkOptions } from './utils/walk'
 
@@ -35,7 +38,7 @@ export function find(...args: ParseOptions<FindOptions>): Pipe {
   const { params: globs, options } = parseOptions(args, {})
 
   const context = requireContext()
-  return new Pipe(context, Promise.resolve().then(async () => {
+  return new PipeImpl(context, Promise.resolve().then(async () => {
     const directory = options.directory ?
       context.resolve(options.directory) :
       getCurrentWorkingDirectory()
@@ -88,7 +91,7 @@ export async function rmrf(directory: string): Promise<void> {
  */
 export function merge(pipes: (Pipe | Files | Promise<Files>)[]): Pipe {
   const context = requireContext()
-  return new Pipe(context, Promise.resolve().then(async () => {
+  return new PipeImpl(context, Promise.resolve().then(async () => {
     // No pipes? Just send off an empty pipe...
     if (pipes.length === 0) return Files.builder(getCurrentWorkingDirectory()).build()
 
@@ -97,7 +100,7 @@ export function merge(pipes: (Pipe | Files | Promise<Files>)[]): Pipe {
 
     // Find the common directory between all the Files instances
     const [ firstDir, ...otherDirs ] = results.map((f) => f.directory)
-    const directory = commonPath(firstDir, ...otherDirs)
+    const directory = commonPath(firstDir!, ...otherDirs)
 
     // Build our new files instance merging all the results
     return Files.builder(directory).merge(...results).build()
@@ -121,7 +124,7 @@ export function merge(pipes: (Pipe | Files | Promise<Files>)[]): Pipe {
 export function noop(): Pipe {
   const context = requireContext()
   const files = new Files(getCurrentWorkingDirectory())
-  return new Pipe(context, Promise.resolve(files))
+  return new PipeImpl(context, Promise.resolve(files))
 }
 
 /**
@@ -155,3 +158,32 @@ export function isDirectory(...paths: [ string, ...string[] ]): AbsolutePath | u
   const path = requireContext().resolve(...paths)
   return resolveDirectory(path)
 }
+
+/**
+ * Execute a command and await for its result from within a task.
+ *
+ * For example:
+ *
+ * ```
+ * import { exec } from '@plugjs/plugjs'
+ *
+ * export default build({
+ *   async runme() {
+ *     await exec('ls', '-la', '/')
+ *     // or similarly letting the shell interpret the command
+ *     await exec('ls -la /', { shell: true })
+ *   },
+ * })
+ * ```
+ *
+ * @param cmd The command to execute
+ * @param args Any additional argument for the command to execute
+ * @param options Extra {@link ExecChildOptions | options} for process execution
+ */
+export function exec(
+    cmd: string,
+    ...args: [ ...args: string[] ] | [ ...args: string[], options: ExecChildOptions ]
+): Promise<void> {
+  const { params, options } = parseOptions(args)
+  return execChild(cmd, params, options, requireContext())
+}

package/src/index.ts

@@ -1,18 +1,40 @@
 // Reference our extra "webassembly" type fix here. As we're using esbuild
 // everywhere, we want our dependants to have this type known...
-/// <reference path="../types/webassembly.d.ts" />
+/// <reference path="../types/plugjs.d.ts" />
 
-export type { AbsolutePath } from './paths'
-export type { Files, FilesBuilder } from './files'
+// This is a main constituent of our build system!
+import type { Files } from './files'
+import type { Plug, PlugFunction } from './pipe'
 
-export { BuildFailure } from './failure'
-export type { Pipe } from './pipe'
+/**
+ * The {@link Pipe} interface defines a processing pipeline where multiple
+ * {@link Plug}s can transform lists of {@link Files}.
+ */
+export interface Pipe extends Promise<Files> {
+  plug(plug: Plug<Files>): Pipe
+  plug(plug: PlugFunction<Files>): Pipe
+  plug(plug: Plug<void | undefined>): Promise<undefined>
+  plug(plug: PlugFunction<void | undefined>): Promise<undefined>
+  plug(plug: Plug<Files | void | undefined>): Pipe | Promise<undefined>
+  plug(plug: PlugFunction<Files | void | undefined>): Pipe | Promise<undefined>
+}
+
+// Submodule exports (our package.json exports)
+export * as asserts from './asserts'
+export * as files from './files'
+export * as fork from './fork'
+export * as fs from './fs'
+export * as logging from './logging'
+export * as paths from './paths'
+export * as pipe from './pipe'
+export * as utils from './utils'
+
+// Individual utilities
+export { log } from './logging'
+export { assert } from './asserts'
 
 // Our minimal exports
-export * from './assert'
 export * from './build'
-export * from './fork'
 export * from './helpers'
-export * from './log'
 export * from './plugs'
 export * from './types'

package/src/{log → logging}/emit.ts

@@ -120,7 +120,6 @@ export const emitPlain: LogEmitter = (options: LogEmitterOptions, args: any[]):
 
   /* Write each individual line out */
   for (const line of message.split('\n')) {
-    _output.write(zapSpinner)
     _output.write(linePrefix)
     _output.write(line)
     _output.write('\n')

package/src/{log → logging}/logger.ts

@@ -1,4 +1,4 @@
-import { BuildFailure, isBuildFailure } from '../failure'
+import { BuildFailure, isBuildFailure } from '../asserts'
 import { emitColor, emitPlain } from './emit'
 import { DEBUG, ERROR, INFO, NOTICE, TRACE, WARN } from './levels'
 import { logOptions } from './options'
@@ -74,6 +74,8 @@ export function getLogger(task: string = _defaultTaskName): Logger {
 
 /** Cache of loggers by task-name. */
 const _loggers = new Map<string, Logger>()
+/** Weak set of already logged build failures */
+const _loggedFailures = new WeakSet<BuildFailure>()
 
 /** Default implementation of the {@link Logger} interface. */
 class LoggerImpl implements Logger {
@@ -93,14 +95,21 @@ class LoggerImpl implements Logger {
     const params = args.filter((arg) => {
       if (isBuildFailure(arg)) {
         // Filter out any previously logged build failure and mark
-        if (arg.logged) return false
-        arg.logged = true
+        if (_loggedFailures.has(arg)) return false
+        _loggedFailures.add(arg)
 
         // If the build failure has any root cause, log those
         arg.errors.forEach((error) => this._emit(level, [ error ]))
 
         // Log this only if it has a message
-        return !! arg.message
+        if (! arg.message) return false
+
+        // Log the full error (with stack) if the _default_ level is DEBUG
+        if (_level < INFO) return true
+
+        // Log only the message in other cases
+        this._emit(level, [ arg.message ])
+        return false
       } else {
         return true
       }

package/src/{log → logging}/options.ts

@@ -2,9 +2,9 @@ import { EventEmitter } from 'node:events'
 
 import { getLevelNumber, NOTICE } from './levels'
 
-import type { LogLevel, LogLevelString } from './levels'
 import type { Writable } from 'node:stream'
 import type { InspectOptions } from 'node:util'
+import type { LogLevel, LogLevelString } from './levels'
 
 /* ========================================================================== */
 
@@ -54,8 +54,10 @@ class LogOptionsImpl extends EventEmitter implements LogOptions {
   private _output: Writable = process.stderr
   private _level: LogLevel = NOTICE
   private _colors = (<NodeJS.WriteStream> this._output).isTTY
+  private _colorsSet = false // have colors been set manually?
   private _spinner = true // by default, the spinner is enabled
   private _lineLength = (<NodeJS.WriteStream> this._output).columns || 80
+  private _lineLengthSet = false // has line length been set manually?
   private _showSources = true // by default, always show source snippets
   private _inspectOptions: InspectOptions = {}
   private _defaultTaskName = ''
@@ -70,10 +72,10 @@ class LogOptionsImpl extends EventEmitter implements LogOptions {
       this._level = getLevelNumber(process.env.LOG_LEVEL as LogLevelString)
     }
 
-    /* If the `LOG_COLOR` variable is specified, it should be `true` or `false` */
-    if (process.env.LOG_COLOR) {
-      if (process.env.LOG_COLOR.toLowerCase() === 'true') this.colors = true
-      if (process.env.LOG_COLOR.toLowerCase() === 'false') this.colors = false
+    /* If the `LOG_COLORS` variable is specified, it should be `true` or `false` */
+    if (process.env.LOG_COLORS) {
+      if (process.env.LOG_COLORS.toLowerCase() === 'true') this.colors = true
+      if (process.env.LOG_COLORS.toLowerCase() === 'false') this.colors = false
       // Other values don't change the value of `options.colors`
     }
 
@@ -106,8 +108,8 @@ class LogOptionsImpl extends EventEmitter implements LogOptions {
 
   set output(output: Writable) {
     this._output = output
-    this._colors = !! (<NodeJS.WriteStream> output).isTTY
-    this._lineLength = (<NodeJS.WriteStream> output).columns
+    if (! this._colorsSet) this._colors = !! (<NodeJS.WriteStream> output).isTTY
+    if (! this._lineLengthSet) this._lineLength = (<NodeJS.WriteStream> output).columns
     this._notifyListeners()
   }
 
@@ -126,6 +128,7 @@ class LogOptionsImpl extends EventEmitter implements LogOptions {
 
   set colors(color: boolean) {
     this._colors = color
+    this._colorsSet = true
     this._notifyListeners()
   }
 
@@ -144,6 +147,7 @@ class LogOptionsImpl extends EventEmitter implements LogOptions {
 
   set lineLength(lineLength: number) {
     this._lineLength = lineLength
+    this._lineLengthSet = true
     this._notifyListeners()
   }
 

package/src/{log → logging}/report.ts

@@ -1,5 +1,5 @@
-import { BuildFailure } from '../failure'
-import { readFile } from '../utils/asyncfs'
+import { BuildFailure } from '../asserts'
+import { readFile } from '../fs'
 import { $blu, $cyn, $gry, $red, $und, $wht, $ylw } from './colors'
 import { ERROR, NOTICE, WARN } from './levels'
 import { logOptions } from './options'
@@ -336,7 +336,7 @@ export class ReportImpl implements Report {
 
     /* Iterate through all our [file,reports] tuple */
     for (let f = 0; f < entries.length; f ++) {
-      const { file, records, annotation } = entries[f]
+      const { file, records, annotation } = entries[f]!
       const source = file && file != nul && this._sources.get(file)
 
       if ((f === 0) || entries[f - 1]?.records.length) {
@@ -358,7 +358,7 @@ export class ReportImpl implements Report {
 
       /* Now get each message and do our magic */
       for (let r = 0; r < records.length; r ++) {
-        const { level, messages, tags, line, column, length = 1 } = records[r]
+        const { level, messages, tags, line, column, length = 1 } = records[r]!
 
         /* Prefix includes line and column */
         let pfx: string
@@ -382,13 +382,13 @@ export class ReportImpl implements Report {
 
         /* Print out our messages, one by one */
         if (messages.length === 1) {
-          this._emitter({ ...options, level }, [ $gry(pfx), messages[0].padEnd(mPad), tag ])
+          this._emitter({ ...options, level }, [ $gry(pfx), messages[0]!.padEnd(mPad), tag ])
         } else {
           for (let m = 0; m < messages.length; m ++) {
             if (! m) { // first line
               this._emitter({ ...options, level }, [ $gry(pfx), messages[m] ])
             } else if (m === messages.length - 1) { // last line
-              this._emitter({ ...options, level, prefix }, [ messages[m].padEnd(mPad), tag ])
+              this._emitter({ ...options, level, prefix }, [ messages[m]!.padEnd(mPad), tag ])
             } else { // in between lines
               this._emitter({ ...options, level, prefix }, [ messages[m] ])
             }
@@ -400,9 +400,10 @@ export class ReportImpl implements Report {
           if (column) {
             const $col = level === NOTICE ? $blu : level === WARN ? $ylw : $red
             const offset = column - 1
-            const head = $gry(source[line - 1].substring(0, offset))
-            const body = $und($col(source[line - 1].substring(offset, offset + length)))
-            const tail = $gry(source[line - 1].substring(offset + length))
+            const text = source[line - 1] || ''
+            const head = $gry(text.substring(0, offset))
+            const body = $und($col(text.substring(offset, offset + length)))
+            const tail = $gry(text.substring(offset + length))
 
             this._emitter({ ...options, level, prefix }, [ $gry(`| ${head}${body}${tail}`) ])
           } else {

package/src/{log.ts → logging.ts}

@@ -1,12 +1,12 @@
 import { currentContext } from './async'
-import { getLogger, type Log } from './log/logger'
-import { setupSpinner } from './log/spinner'
+import { getLogger, type Log } from './logging/logger'
+import { setupSpinner } from './logging/spinner'
 
-export * from './log/colors'
-export * from './log/levels'
-export * from './log/logger'
-export * from './log/options'
-export * from './log/report'
+export * from './logging/colors'
+export * from './logging/levels'
+export * from './logging/logger'
+export * from './logging/options'
+export * from './logging/report'
 
 /* ========================================================================== *
  * INITIALIZATION                                                             *

package/src/paths.ts

@@ -3,7 +3,7 @@ import { createRequire } from 'node:module'
 import { dirname, extname, isAbsolute, join, normalize, relative, resolve, sep } from 'node:path'
 import { fileURLToPath, pathToFileURL } from 'node:url'
 
-import { assert } from './assert'
+import { assert } from './asserts'
 
 /** A _branded_ `string` representing an _absolute_ path name */
 export type AbsolutePath = string & { __brand_absolute_path: never }

package/src/pipe.ts

@@ -1,13 +1,14 @@
 import { sep } from 'node:path'
 
-import { assert, assertPromises } from './assert'
-import { getLogger } from './log'
+import { assert, assertPromises } from './asserts'
+import { getLogger } from './logging'
 import { getAbsoluteParent, getCurrentWorkingDirectory, resolveAbsolutePath } from './paths'
 
 import type { Files } from './files'
-import type { Logger } from './log'
+import type { Logger } from './logging'
 import type { AbsolutePath } from './paths'
 import type { Result } from './types'
+import type { Pipe } from './index'
 
 /* ========================================================================== *
  * PLUGS                                                                      *
@@ -138,27 +139,19 @@ export class ContextPromises {
   }
 }
 
-/**
- * A class that will be extended by {@link Pipe} where {@link install} will
- * add prototype properties from installed {@link Plug}s
- */
-abstract class PipeProto {
-  abstract plug(plug: Plug<PlugResult>): Pipe | Promise<undefined>
+/** The default implementation of the {@link Pipe} interface. */
+export interface PipeImpl extends Pipe {
+  // used simply for merging types
 }
 
-/**
- * The {@link Pipe} class defines processing pipeline where multiple
- * {@link Plug}s can transform lists of {@link Files}.
- */
-export class Pipe extends PipeProto implements Promise<Files> {
+/** The default implementation of the {@link Pipe} interface. */
+export class PipeImpl implements Pipe {
   readonly [Symbol.toStringTag] = 'Pipe'
 
   constructor(
       private readonly _context: Context,
       private readonly _promise: Promise<Result>,
   ) {
-    super()
-
     // New "Pipe", remember the promise!
     ContextPromises.get(_context).hot(_promise)
   }
@@ -218,7 +211,7 @@ export class Pipe extends PipeProto implements Promise<Files> {
     ContextPromises.get(this._context).cold(this._promise)
 
     // Create and return the new Pipe
-    return new Pipe(this._context, this._promise.then(async (result) => {
+    return new PipeImpl(this._context, this._promise.then(async (result) => {
       assert(result, 'Unable to extend pipe')
       const result2 = await plug.pipe(result, this._context)
       return result2 || undefined
@@ -335,14 +328,14 @@ export function install<
   Ctor extends PlugConstructor<Name>,
 >(name: Name, ctor: Ctor): void {
   /* The function plugging the newly constructed plug in a pipe */
-  function plug(this: PipeProto, ...args: PipeParameters<Name>): Pipe | Promise<undefined> {
+  function plug(this: PipeImpl, ...args: PipeParameters<Name>): Pipe | Promise<undefined> {
     // eslint-disable-next-line new-cap
-    return this.plug(new ctor(...args))
+    return this.plug(new ctor(...args) as any)
   }
 
   /* Setup name so that stack traces look better */
   Object.defineProperty(plug, 'name', { value: name })
 
   /* Inject the create function in the Pipe's prototype */
-  Object.defineProperty(PipeProto.prototype, name, { value: plug })
+  void Object.defineProperty(PipeImpl.prototype, name, { value: plug })
 }

package/src/plugs/copy.ts

@@ -1,9 +1,9 @@
-import { assert } from '../assert'
+import { assert } from '../asserts'
 import { Files } from '../files'
-import { $p } from '../log'
+import { chmod, copyFile, fsConstants, mkdir } from '../fs'
+import { $p } from '../logging'
 import { assertAbsolutePath, getAbsoluteParent, resolveAbsolutePath } from '../paths'
 import { install } from '../pipe'
-import { chmod, copyFile, fsConstants, mkdir } from '../utils/asyncfs'
 
 import type { Context, PipeParameters, Plug } from '../pipe'
 
@@ -19,7 +19,7 @@ export interface CopyOptions {
   rename?: (relative: string) => string
 }
 
-declare module '../pipe' {
+declare module '../index' {
   export interface Pipe {
     /**
      * Copy the curent {@link Files} to a different directory

package/src/plugs/debug.ts

@@ -1,10 +1,10 @@
-import { $gry, $p, $und, $ylw } from '../log'
+import { $gry, $p, $und, $ylw } from '../logging'
 import { install } from '../pipe'
 
 import type { Files } from '../files'
 import type { Context, PipeParameters, Plug } from '../pipe'
 
-declare module '../pipe' {
+declare module '../index' {
   export interface Pipe {
     /** Log some info about the current {@link Files} being passed around. */
     debug(title?: string): Pipe

package/src/plugs/edit.ts

@@ -0,0 +1,34 @@
+import { readFile, writeFile } from '../fs'
+import { install } from '../pipe'
+
+import type { Files } from '../files'
+import type { PipeParameters, Plug } from '../pipe'
+
+declare module '../index' {
+  export interface Pipe {
+    /** Edits the content of all files in a pipeline. */
+    edit(callback: (content: string) => string | void | Promise<string | void>): Pipe
+  }
+}
+
+/* ========================================================================== *
+ * INSTALLATION / IMPLEMENTATION                                              *
+ * ========================================================================== */
+
+/** Edits the content of all files in a pipeline. */
+install('edit', class Edit implements Plug<Files> {
+  private readonly _callback: (content: string) => string | void | Promise<string | void>
+
+  constructor(...args: PipeParameters<'edit'>) {
+    this._callback = args[0]
+  }
+
+  async pipe(files: Files): Promise<Files> {
+    for (const file of files.absolutePaths()) {
+      const data = await readFile(file, 'utf-8')
+      const edited = await this._callback(data)
+      if (edited !== undefined) await writeFile(file, edited, 'utf-8')
+    }
+    return files
+  }
+})