@plugjs/plug 0.0.14 → 0.0.16

package/dist/pipe.cjs.map

@@ -1,6 +1,6 @@
 {
   "version": 3,
   "sources": ["../src/pipe.ts"],
-  "mappings": ";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,oBAAuB;AA4BhB,IAAe,OAAf,MAAoC;AAG3C;AAIO,IAAM,WAAN,cAAoD,KAA2B;AAAA,EAC3E;AAAA,EACA;AAAA,EAET,YAAY,OAAuB,KAAU;AAC3C,UAAM;AACN,SAAK,WAAW,QAAQ,QAAQ,KAAK;AACrC,SAAK,OAAO;AAAA,EACd;AAAA,EAEA,KAAkC,KAAmD;AACnF,UAAM,OAAO,OAAO,QAAQ,aAAa,EAAE,MAAM,IAAI,IAAI;AACzD,UAAM,UAAU,KAAK,SAAS,KAAK,CAAC,UAAU;AAC5C,gCAAO,OAAO,kCAAkC;AAChD,aAAO,KAAK,KAAK,OAAO,KAAK,IAAI;AAAA,IACnC,CAAC;AACD,WAAO,IAAI,SAAS,SAAS,KAAK,IAAI;AAAA,EACxC;AAAA,EAEA,KACI,aACA,YACgB;AAClB,WAAO,KAAK,SAAS,KAAK,aAAa,UAAU;AAAA,EACnD;AAAA,EAEA,MACI,YACe;AACjB,WAAO,KAAK,SAAS,MAAM,UAAU;AAAA,EACvC;AAAA,EAEA,QACI,WACU;AACZ,WAAO,KAAK,SAAS,QAAQ,SAAS;AAAA,EACxC;AAAA,EAEA,CAAC,OAAO,eAAe;AACzB;AA+IO,SAAS,QAAmC,MAAgB,MAAe;AAGhF,WAAS,UAAsB,MAA8C;AAE3E,WAAO,KAAK,KAAK,IAAI,KAAK,GAAG,IAAI,CAAQ;AAAA,EAC3C;AAGA,SAAO,eAAe,QAAQ,QAAQ,EAAE,OAAO,KAAK,CAAC;AAGrD,SAAO,eAAe,KAAK,WAAW,MAAM,EAAE,OAAO,OAAO,CAAC;AAC/D;",
+  "mappings": ";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,mBAMO;AAEP,kBAAoB;AACpB,oBAAuB;AACvB,mBAA+B;AAC/B,mBAAsB;AACtB,kBAA4B;AAC5B,iBAAkC;AA+B3B,IAAM,UAAN,MAAc;AAAA,EAMnB,YAEoB,WAEA,UAClB;AAHkB;AAEA;AAElB,SAAK,eAAW,gCAAkB,SAAS;AAC3C,SAAK,UAAM,sBAAU,QAAQ;AAAA,EAC/B;AAAA,EAZgB;AAAA,EAEA;AAAA,EAoBhB,QAAQ,SAAiB,OAA+B;AAEtD,QAAI,QAAQ,KAAK,WAAW,GAAG,GAAG;AAEhC,YAAM,aAAa,KAAK,UAAU,CAAC,EAAE,MAAM,eAAG,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC;AACjE,iBAAO,kCAAoB,KAAK,UAAU,GAAG,YAAY,GAAG,KAAK;AAAA,IACnE;AAGA,QAAI,CAAE;AAAM,iBAAO,yCAA2B;AAG9C,eAAO,sCAAoB,yCAA2B,GAAG,MAAM,GAAG,KAAK;AAAA,EACzE;AACF;AAUA,IAAe,YAAf,MAAyB;AAEzB;AAMO,IAAM,OAAN,cAAmB,UAAU;AAAA,EAClC,YACqB,UACA,MACnB;AACA,UAAM;AAHa;AACA;AAAA,EAGrB;AAAA,EAMA,KAAK,KAA6E;AAChF,UAAM,OAAO,OAAO,QAAQ,aAAa,EAAE,MAAM,IAAI,IAAI;AAEzD,UAAM,SAAS;AACf,UAAM,UAAU,KAAK;AACrB,WAAO,IAAI,KAAK,SAAS,YAA4B;AACnD,YAAM,WAAW,MAAM,OAAO,IAAI;AAClC,YAAM,UAAU,MAAM,KAAK,KAAK,UAAU,OAAO;AACjD,gCAAO,SAAS,uBAAuB;AACvC,aAAO;AAAA,IACT,CAAC;AAAA,EACH;AAAA,EAEA,MAAsB;AACpB,WAAO,KAAK,KAAK;AAAA,EACnB;AAAA,EAmBA,OAAO,MAAM,OAAgD;AAC3D,UAAM,cAAU,6BAAe;AAC/B,WAAO,IAAI,KAAK,SAAS,YAA4B;AACnD,UAAI,MAAM,WAAW;AAAG,eAAO,mBAAM,YAAQ,yCAA2B,CAAC,EAAE,MAAM;AAEjF,YAAM,CAAE,UAAU,KAAM,IAAI,MAAM,QAAQ,IAAI,MAAM,IAAI,CAAC,SAAS;AAChE,eAAO,SAAS,OAAO,KAAK,IAAI,IAAI;AAAA,MACtC,CAAC,CAAC;AAEF,YAAM,WAAW,MAAM;AACvB,YAAM,YAAY,MAAM,IAAI,CAAC,MAAM,EAAE,SAAS;AAE9C,YAAM,gBAAY,yBAAW,UAAU,GAAG,SAAS;AAEnD,aAAO,mBAAM,QAAQ,SAAS,EAAE,MAAM,OAAO,GAAG,KAAK,EAAE,MAAM;AAAA,IAC/D,CAAC;AAAA,EACH;AACF;AAyGO,SAAS,QAGd,MAAY,MAAkB;AAE9B,WAAS,QAAyB,MAAuD;AAEvF,WAAO,KAAK,KAAK,IAAI,KAAK,GAAG,IAAI,CAAC;AAAA,EACpC;AAGA,SAAO,eAAe,MAAM,QAAQ,EAAE,OAAO,KAAK,CAAC;AAGnD,SAAO,eAAe,UAAU,WAAW,MAAM,EAAE,OAAO,KAAK,CAAC;AAClE;AAmBO,SAAS,eACZ,UACA,YACI;AAEN,QAAM,OAAO,cAAc,wBAAY;AAAA,IACrC,eAAe,MAAa;AAC1B,YAAM,YAAY,IAAI;AAAA,IACxB;AAAA,EACF;AAGA,UAAQ,UAAU,IAAI;AACxB;",
   "names": []
 }

package/dist/pipe.d.ts

@@ -1,128 +1,167 @@
-import { Files } from './files.js';
-import { Run } from './run.js';
+import { AbsolutePath } from './paths';
+import { Files } from './files';
+import { Logger } from './log';
+/** A convenience type indicating what can be returned by a {@link Plug}. */
+export declare type PlugResult = Files | undefined | void;
 /**
- * The {@link Plug} interface describes an extension mechanism for our build.
+ * The {@link Plug} interface describes _build plugin_.
+ *
+ * A {@link Plug} receives a {@link Files} instance in its input (for example
+ * a list of _source `.ts` files_) and optionally produces a possibly different
+ * list (for example the _compiled `.js` files_).
  */
-export interface Plug<T extends Files | undefined> {
-    pipe(files: Files, run: Run): T | Promise<T>;
+export interface Plug<T extends PlugResult> {
+    pipe(files: Files, context: Context): T | Promise<T>;
 }
+/** A type identifying a {@link Plug} as a `function` */
+export declare type PlugFunction<T extends PlugResult> = Plug<T>['pipe'];
 /**
- * A type identifying a {@link Plug} as a `function`
+ * The {@link Context} class defines the context in which a {@link Plug}
+ * is invoked.
  */
-export declare type PlugFunction<T extends Files | undefined> = Plug<T>['pipe'];
+export declare class Context {
+    /** The absolute file name where the task was defined. */
+    readonly buildFile: AbsolutePath;
+    /** The _name_ of the task associated with this {@link Context}. */
+    readonly taskName: string;
+    /** The directory of the file where the task was defined (convenience). */
+    readonly buildDir: AbsolutePath;
+    /** The {@link Logger} associated with this instance. */
+    readonly log: Logger;
+    constructor(
+    /** The absolute file name where the task was defined. */
+    buildFile: AbsolutePath, 
+    /** The _name_ of the task associated with this {@link Context}. */
+    taskName: string);
+    /**
+     * Resolve a (set of) path(s) in this {@link Context}.
+     *
+     * If the path (or first component thereof) starts with `@...`, then the
+     * resolved path will be relative to the directory containing the build file
+     * where the current task was defined, otherwise it will be relative to the
+     * current working directory.
+     */
+    resolve(path: string, ...paths: string[]): AbsolutePath;
+}
 /**
- * A {@link Pipe} represents a sequence of operations performed by
- * a series of {@link Plug | Plugs}.
+ * A class that will be extended by {@link Pipe} where {@link install} will
+ * add prototype properties from installed {@link Plug}s
  */
-export interface Pipe {
+declare abstract class PipeProto {
+    abstract plug(plug: Plug<PlugResult>): Pipe | Promise<undefined>;
 }
 /**
- * The {@link Pipe} abstract class exposes the prototype upon which all
- * extension plugs will be installed on.
+ * The {@link Pipe} class defines processing pipeline where multiple
+ * {@link Plug}s can transform lists of {@link Files}.
  */
-export declare abstract class Pipe implements Pipe {
-    abstract plug(plug: Plug<Files> | PlugFunction<Files>): Pipe & Promise<Files>;
-    abstract plug(plug: Plug<undefined> | PlugFunction<undefined>): Promise<undefined>;
-}
-/** Implementation of our {@link Pipe}. */
-export declare class PipeImpl<T extends Files | undefined> extends Pipe implements Promise<T> {
-    #private;
-    constructor(start: T | Promise<T>, run: Run);
-    plug<T extends Files | undefined>(arg: Plug<T> | PlugFunction<T>): Pipe & Promise<T>;
-    then<T1 = T, T2 = never>(onfulfilled?: ((value: T) => T1 | PromiseLike<T1>) | null | undefined, onrejected?: ((reason: any) => T2 | PromiseLike<T2>) | null | undefined): Promise<T1 | T2>;
-    catch<T0 = never>(onrejected?: ((reason: any) => T0 | PromiseLike<T0>) | null | undefined): Promise<T0 | T>;
-    finally(onfinally?: (() => void) | null | undefined): Promise<T>;
-    [Symbol.toStringTag]: string;
+export declare class Pipe extends PipeProto {
+    private readonly _context;
+    private readonly _run;
+    constructor(_context: Context, _run: () => 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>;
+    run(): Promise<Files>;
+    /**
+     * Merge the results of several {@link Pipe}s into a single one.
+     *
+     * Merging is performed _in parallel_. When serial execution is to be desired,
+     * we can merge the awaited _result_ of the {@link Pipe}.
+     *
+     * For example:
+     *
+     * ```
+     * const pipe: Pipe = merge([
+     *   // other tasks return `Pipe & Promise<Files>` so we can
+     *   // direcrly await their result without invoking `run()`
+     *   await this.anotherTask1(),
+     *   await this.anotherTask2(),
+     * ])
+     * ```
+     */
+    static merge(pipes: (Pipe | Files | Promise<Files>)[]): Pipe;
 }
 /** The names which can be installed as direct plugs. */
-export declare type PlugName = string & Exclude<keyof Pipe, 'plug' | keyof Promise<Files>>;
-/** A convenience type identifying a {@link Plug} constructor. */
-export declare type PlugConstructor = new (...args: any) => Plug<Files | undefined>;
-/** Convert the resulting type of a {@link Plug} for use in a {@link Pipe} */
-declare type PlugReturnForPipe<T> = T extends Plug<infer R> ? R extends Files ? Promise<Files> & Pipe : R extends undefined ? Promise<undefined> : never : never;
-/**
- * Map constructors into an array of all known overloads.
- *
- * This is a _royal_ pain in the ass, as we need to distinguish between
- * all possible number of overloads of a constructor... Limit to 5 of them!
- *
- * Also, the empty constructor (when specified in the overloads) will simply
- * match the first case (most overloads) and generate functions somewhat like
- *
- * (...args: unknown[]) => never
- * (...args: unknown[]) => never
- * (...args: unknown[]) => never
- * () => PlugReturnForPipe<R3>
- * (arg: Options) => PlugReturnForPipe<R4>
- *
- * Somehow inferring the result to `Function` or the right type and ANDing all
- * those together here doesn't work, so we create this array and we'll AND
- * all its members in the PipeExtension<...> type.
- */
-declare type PlugConstructorOverloads<T extends PlugConstructor> = T extends {
-    new (...args: infer A0): infer R0;
-    new (...args: infer A1): infer R1;
-    new (...args: infer A2): infer R2;
-    new (...args: infer A3): infer R3;
-    new (...args: infer A4): infer R4;
-} ? [
-    R0 extends Plug<Files | undefined> ? ((...args: A0) => PlugReturnForPipe<R0>) : Function,
-    R1 extends Plug<Files | undefined> ? ((...args: A1) => PlugReturnForPipe<R1>) : Function,
-    R2 extends Plug<Files | undefined> ? ((...args: A2) => PlugReturnForPipe<R2>) : Function,
-    R3 extends Plug<Files | undefined> ? ((...args: A3) => PlugReturnForPipe<R3>) : Function,
-    R4 extends Plug<Files | undefined> ? ((...args: A4) => PlugReturnForPipe<R4>) : Function
-] : T extends {
-    new (...args: infer A0): infer R0;
-    new (...args: infer A1): infer R1;
-    new (...args: infer A2): infer R2;
-    new (...args: infer A3): infer R3;
-} ? [
-    R0 extends Plug<Files | undefined> ? (...args: A0) => PlugReturnForPipe<R0> : Function,
-    R1 extends Plug<Files | undefined> ? (...args: A1) => PlugReturnForPipe<R1> : Function,
-    R2 extends Plug<Files | undefined> ? (...args: A2) => PlugReturnForPipe<R2> : Function,
-    R3 extends Plug<Files | undefined> ? (...args: A3) => PlugReturnForPipe<R3> : Function
-] : T extends {
-    new (...args: infer A0): infer R0;
-    new (...args: infer A1): infer R1;
-    new (...args: infer A2): infer R2;
-} ? [
-    R0 extends Plug<Files | undefined> ? (...args: A0) => PlugReturnForPipe<R0> : Function,
-    R1 extends Plug<Files | undefined> ? (...args: A1) => PlugReturnForPipe<R1> : Function,
-    R2 extends Plug<Files | undefined> ? (...args: A2) => PlugReturnForPipe<R2> : Function
-] : T extends {
-    new (...args: infer A0): infer R0;
-    new (...args: infer A1): infer R1;
-} ? [
-    R0 extends Plug<Files | undefined> ? (...args: A0) => PlugReturnForPipe<R0> : Function,
-    R1 extends Plug<Files | undefined> ? (...args: A1) => PlugReturnForPipe<R1> : Function
-] : T extends {
-    new (...args: infer A0): infer R0;
-} ? [
-    R0 extends Plug<Files | undefined> ? (...args: A0) => PlugReturnForPipe<R0> : Function
-] : never;
+export declare type PlugName = string & Exclude<keyof Pipe, 'plug' | 'run'>;
+/** The parameters of the plug extension with the given name */
+export declare type PipeParameters<Name extends PlugName> = PipeOverloads<Name>['args'];
+/** Extract arguments and return types from function overloads. */
+declare type PipeOverloads<Name extends PlugName> = Pipe[Name] extends {
+    (...args: infer A0): infer R0;
+    (...args: infer A1): infer R1;
+    (...args: infer A2): infer R2;
+    (...args: infer A3): infer R3;
+    (...args: infer A4): infer R4;
+} ? (R0 extends (Pipe | Promise<undefined>) ? {
+    args: A0;
+    ret: R0;
+} : never) | (R1 extends (Pipe | Promise<undefined>) ? {
+    args: A1;
+    ret: R1;
+} : never) | (R2 extends (Pipe | Promise<undefined>) ? {
+    args: A2;
+    ret: R2;
+} : never) | (R3 extends (Pipe | Promise<undefined>) ? {
+    args: A3;
+    ret: R3;
+} : never) | (R4 extends (Pipe | Promise<undefined>) ? {
+    args: A4;
+    ret: R4;
+} : never) : Pipe[Name] extends {
+    (...args: infer A0): infer R0;
+    (...args: infer A1): infer R1;
+    (...args: infer A2): infer R2;
+    (...args: infer A3): infer R3;
+} ? (R0 extends (Pipe | Promise<undefined>) ? {
+    args: A0;
+    ret: R0;
+} : never) | (R1 extends (Pipe | Promise<undefined>) ? {
+    args: A1;
+    ret: R1;
+} : never) | (R2 extends (Pipe | Promise<undefined>) ? {
+    args: A2;
+    ret: R2;
+} : never) | (R3 extends (Pipe | Promise<undefined>) ? {
+    args: A3;
+    ret: R3;
+} : never) : Pipe[Name] extends {
+    (...args: infer A0): infer R0;
+    (...args: infer A1): infer R1;
+    (...args: infer A2): infer R2;
+} ? (R0 extends (Pipe | Promise<undefined>) ? {
+    args: A0;
+    ret: R0;
+} : never) | (R1 extends (Pipe | Promise<undefined>) ? {
+    args: A1;
+    ret: R1;
+} : never) | (R2 extends (Pipe | Promise<undefined>) ? {
+    args: A2;
+    ret: R2;
+} : never) : Pipe[Name] extends {
+    (...args: infer A0): infer R0;
+    (...args: infer A1): infer R1;
+} ? (R0 extends (Pipe | Promise<undefined>) ? {
+    args: A0;
+    ret: R0;
+} : never) | (R1 extends (Pipe | Promise<undefined>) ? {
+    args: A1;
+    ret: R1;
+} : never) : Pipe[Name] extends {
+    (...args: infer A0): infer R0;
+} ? (R0 extends (Pipe | Promise<undefined>) ? {
+    args: A0;
+    ret: R0;
+} : never) : never;
+/** The parameters of the plug extension with the given name */
+declare type PipeResult<Name extends PlugName> = PipeOverloads<Name>['ret'];
 /**
- * A convenience type to easily annotate installed {@link Plug Plugs}.
- *
- * See also {@link install}.
- *
- * ```
- * export class Write implements Plug {
- *   // ... the plug implementation lives here
- * }
- *
- * install('write', Write)
- *
- * declare module '../pipe' {
- *   export interface Pipe {
- *     write: PipeExtension<typeof Write>
- *   }
- * }
- * ```
+ * A type defining the correct constructor for a {@link Plug}, inferring
+ * argument types and instance type from the definitions in {@link Pipe}.
  */
-export declare type PipeExtension<T extends PlugConstructor, A = PlugConstructorOverloads<T>> = A extends readonly [infer First, ...infer Rest] ? First & PipeExtension<T, Rest> : A extends readonly [infer Only] ? Only : Function;
+declare type PlugConstructor<Name extends PlugName> = PipeResult<Name> extends Pipe ? new (...args: PipeParameters<Name>) => Plug<Files> : PipeResult<Name> extends Promise<undefined> ? new (...args: PipeParameters<Name>) => Plug<void | undefined> : PipeResult<Name> extends (Pipe | Promise<undefined>) ? new (...args: PipeParameters<Name>) => Plug<Files | void | undefined> : never;
 /**
- * Install a {@link Plug} into our {@link Pipe} prototype, and return a static
- * creator function for the {@link Plug} itself.
+ * Install a {@link Plug} into our {@link Pipe} prototype.
  *
  * This allows our shorthand syntax for well-defined plugs such as:
  *
@@ -135,18 +174,38 @@ export declare type PipeExtension<T extends PlugConstructor, A = PlugConstructor
  * Use this alongside interface merging like:
  *
  * ```
- * export class Write implements Plug {
- *   // ... the plug implementation lives here
- * }
- *
- * install('write', Write)
- *
- * declare module '../pipe' {
+ * declare module '@plugjs/plug/pipe' {
  *   export interface Pipe {
- *     write: PipeExtension<typeof Write>
+ *     write(): Pipe
  *   }
  * }
+ *
+ * install('write', class Write implements Plug {
+ *   constructorg(...args: PipeParams<'write'>) {
+ *     // here `args` is automatically inferred by whatever was declared above
+ *   }
+ *
+ *   // ... the plug implementation lives here
+ * })
  * ```
  */
-export declare function install<C extends PlugConstructor>(name: PlugName, ctor: C): void;
+export declare function install<Name extends PlugName, Ctor extends PlugConstructor<Name>>(name: Name, ctor: Ctor): void;
+/**
+ * Install a _forking_ {@link Plug} in the {@link Pipe}, in other words
+ * execute the plug in a separate process.
+ *
+ * As a contract, if the _last non-null_ parameter of the constructor is an
+ * object and contains the key `coverageDir`, the process will be forked with
+ * the approptiately resolved `NODE_V8_COVERAGE` environment variable.
+ *
+ * Also, forking plugs require some special attention:
+ *
+ * * plug functions are not supported, only classes implementing the
+ *   {@link Plug} interface can be used with this.
+ *
+ * * the class itself _MUST_ be exported as the _default_ export for the
+ *   `scriptFile` specified below. This is to simplify interoperability between
+ *   CommonJS and ESM modules as we use dynamic `import(...)` statements.
+ */
+export declare function installForking<Name extends PlugName>(plugName: Name, scriptFile: AbsolutePath): void;
 export {};

package/dist/pipe.mjs

@@ -1,44 +1,91 @@
 // pipe.ts
+import {
+  commonPath,
+  getAbsoluteParent,
+  getCurrentWorkingDirectory,
+  resolveAbsolutePath
+} from "./paths.mjs";
+import { sep } from "path";
 import { assert } from "./assert.mjs";
-var Pipe = class {
+import { requireContext } from "./async.mjs";
+import { Files } from "./files.mjs";
+import { ForkingPlug } from "./fork.mjs";
+import { getLogger } from "./log.mjs";
+var Context = class {
+  constructor(buildFile, taskName) {
+    this.buildFile = buildFile;
+    this.taskName = taskName;
+    this.buildDir = getAbsoluteParent(buildFile);
+    this.log = getLogger(taskName);
+  }
+  buildDir;
+  log;
+  resolve(path, ...paths) {
+    if (path && path.startsWith("@")) {
+      const components = path.substring(1).split(sep).filter((s) => !!s);
+      return resolveAbsolutePath(this.buildDir, ...components, ...paths);
+    }
+    if (!path)
+      return getCurrentWorkingDirectory();
+    return resolveAbsolutePath(getCurrentWorkingDirectory(), path, ...paths);
+  }
+};
+var PipeProto = class {
 };
-var PipeImpl = class extends Pipe {
-  #promise;
-  #run;
-  constructor(start, run) {
+var Pipe = class extends PipeProto {
+  constructor(_context, _run) {
     super();
-    this.#promise = Promise.resolve(start);
-    this.#run = run;
+    this._context = _context;
+    this._run = _run;
   }
   plug(arg) {
     const plug = typeof arg === "function" ? { pipe: arg } : arg;
-    const promise = this.#promise.then((files) => {
-      assert(files, "Pipe can not be further extended");
-      return plug.pipe(files, this.#run);
+    const parent = this;
+    const context = this._context;
+    return new Pipe(context, async () => {
+      const previous = await parent.run();
+      const current = await plug.pipe(previous, context);
+      assert(current, "Unable to extend pipe");
+      return current;
     });
-    return new PipeImpl(promise, this.#run);
   }
-  then(onfulfilled, onrejected) {
-    return this.#promise.then(onfulfilled, onrejected);
+  run() {
+    return this._run();
   }
-  catch(onrejected) {
-    return this.#promise.catch(onrejected);
-  }
-  finally(onfinally) {
-    return this.#promise.finally(onfinally);
+  static merge(pipes) {
+    const context = requireContext();
+    return new Pipe(context, async () => {
+      if (pipes.length === 0)
+        return Files.builder(getCurrentWorkingDirectory()).build();
+      const [first, ...other] = await Promise.all(pipes.map((pipe) => {
+        return "run" in pipe ? pipe.run() : pipe;
+      }));
+      const firstDir = first.directory;
+      const otherDirs = other.map((f) => f.directory);
+      const directory = commonPath(firstDir, ...otherDirs);
+      return Files.builder(directory).merge(first, ...other).build();
+    });
   }
-  [Symbol.toStringTag] = "Pipe";
 };
 function install(name, ctor) {
-  function create(...args) {
+  function plug(...args) {
     return this.plug(new ctor(...args));
   }
-  Object.defineProperty(create, "name", { value: name });
-  Object.defineProperty(Pipe.prototype, name, { value: create });
+  Object.defineProperty(plug, "name", { value: name });
+  Object.defineProperty(PipeProto.prototype, name, { value: plug });
+}
+function installForking(plugName, scriptFile) {
+  const ctor = class extends ForkingPlug {
+    constructor(...args) {
+      super(scriptFile, args);
+    }
+  };
+  install(plugName, ctor);
 }
 export {
+  Context,
   Pipe,
-  PipeImpl,
-  install
+  install,
+  installForking
 };
 //# sourceMappingURL=pipe.mjs.map

package/dist/pipe.mjs.map

@@ -1,6 +1,6 @@
 {
   "version": 3,
   "sources": ["../src/pipe.ts"],
-  "mappings": ";AAAA,SAAS,cAAc;AA4BhB,IAAe,OAAf,MAAoC;AAG3C;AAIO,IAAM,WAAN,cAAoD,KAA2B;AAAA,EAC3E;AAAA,EACA;AAAA,EAET,YAAY,OAAuB,KAAU;AAC3C,UAAM;AACN,SAAK,WAAW,QAAQ,QAAQ,KAAK;AACrC,SAAK,OAAO;AAAA,EACd;AAAA,EAEA,KAAkC,KAAmD;AACnF,UAAM,OAAO,OAAO,QAAQ,aAAa,EAAE,MAAM,IAAI,IAAI;AACzD,UAAM,UAAU,KAAK,SAAS,KAAK,CAAC,UAAU;AAC5C,aAAO,OAAO,kCAAkC;AAChD,aAAO,KAAK,KAAK,OAAO,KAAK,IAAI;AAAA,IACnC,CAAC;AACD,WAAO,IAAI,SAAS,SAAS,KAAK,IAAI;AAAA,EACxC;AAAA,EAEA,KACI,aACA,YACgB;AAClB,WAAO,KAAK,SAAS,KAAK,aAAa,UAAU;AAAA,EACnD;AAAA,EAEA,MACI,YACe;AACjB,WAAO,KAAK,SAAS,MAAM,UAAU;AAAA,EACvC;AAAA,EAEA,QACI,WACU;AACZ,WAAO,KAAK,SAAS,QAAQ,SAAS;AAAA,EACxC;AAAA,EAEA,CAAC,OAAO,eAAe;AACzB;AA+IO,SAAS,QAAmC,MAAgB,MAAe;AAGhF,WAAS,UAAsB,MAA8C;AAE3E,WAAO,KAAK,KAAK,IAAI,KAAK,GAAG,IAAI,CAAQ;AAAA,EAC3C;AAGA,SAAO,eAAe,QAAQ,QAAQ,EAAE,OAAO,KAAK,CAAC;AAGrD,SAAO,eAAe,KAAK,WAAW,MAAM,EAAE,OAAO,OAAO,CAAC;AAC/D;",
+  "mappings": ";AAAA;AAAA,EAEE;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,OACK;AAEP,SAAS,WAAW;AACpB,SAAS,cAAc;AACvB,SAAS,sBAAsB;AAC/B,SAAS,aAAa;AACtB,SAAS,mBAAmB;AAC5B,SAAS,iBAAyB;AA+B3B,IAAM,UAAN,MAAc;AAAA,EAMnB,YAEoB,WAEA,UAClB;AAHkB;AAEA;AAElB,SAAK,WAAW,kBAAkB,SAAS;AAC3C,SAAK,MAAM,UAAU,QAAQ;AAAA,EAC/B;AAAA,EAZgB;AAAA,EAEA;AAAA,EAoBhB,QAAQ,SAAiB,OAA+B;AAEtD,QAAI,QAAQ,KAAK,WAAW,GAAG,GAAG;AAEhC,YAAM,aAAa,KAAK,UAAU,CAAC,EAAE,MAAM,GAAG,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC;AACjE,aAAO,oBAAoB,KAAK,UAAU,GAAG,YAAY,GAAG,KAAK;AAAA,IACnE;AAGA,QAAI,CAAE;AAAM,aAAO,2BAA2B;AAG9C,WAAO,oBAAoB,2BAA2B,GAAG,MAAM,GAAG,KAAK;AAAA,EACzE;AACF;AAUA,IAAe,YAAf,MAAyB;AAEzB;AAMO,IAAM,OAAN,cAAmB,UAAU;AAAA,EAClC,YACqB,UACA,MACnB;AACA,UAAM;AAHa;AACA;AAAA,EAGrB;AAAA,EAMA,KAAK,KAA6E;AAChF,UAAM,OAAO,OAAO,QAAQ,aAAa,EAAE,MAAM,IAAI,IAAI;AAEzD,UAAM,SAAS;AACf,UAAM,UAAU,KAAK;AACrB,WAAO,IAAI,KAAK,SAAS,YAA4B;AACnD,YAAM,WAAW,MAAM,OAAO,IAAI;AAClC,YAAM,UAAU,MAAM,KAAK,KAAK,UAAU,OAAO;AACjD,aAAO,SAAS,uBAAuB;AACvC,aAAO;AAAA,IACT,CAAC;AAAA,EACH;AAAA,EAEA,MAAsB;AACpB,WAAO,KAAK,KAAK;AAAA,EACnB;AAAA,EAmBA,OAAO,MAAM,OAAgD;AAC3D,UAAM,UAAU,eAAe;AAC/B,WAAO,IAAI,KAAK,SAAS,YAA4B;AACnD,UAAI,MAAM,WAAW;AAAG,eAAO,MAAM,QAAQ,2BAA2B,CAAC,EAAE,MAAM;AAEjF,YAAM,CAAE,UAAU,KAAM,IAAI,MAAM,QAAQ,IAAI,MAAM,IAAI,CAAC,SAAS;AAChE,eAAO,SAAS,OAAO,KAAK,IAAI,IAAI;AAAA,MACtC,CAAC,CAAC;AAEF,YAAM,WAAW,MAAM;AACvB,YAAM,YAAY,MAAM,IAAI,CAAC,MAAM,EAAE,SAAS;AAE9C,YAAM,YAAY,WAAW,UAAU,GAAG,SAAS;AAEnD,aAAO,MAAM,QAAQ,SAAS,EAAE,MAAM,OAAO,GAAG,KAAK,EAAE,MAAM;AAAA,IAC/D,CAAC;AAAA,EACH;AACF;AAyGO,SAAS,QAGd,MAAY,MAAkB;AAE9B,WAAS,QAAyB,MAAuD;AAEvF,WAAO,KAAK,KAAK,IAAI,KAAK,GAAG,IAAI,CAAC;AAAA,EACpC;AAGA,SAAO,eAAe,MAAM,QAAQ,EAAE,OAAO,KAAK,CAAC;AAGnD,SAAO,eAAe,UAAU,WAAW,MAAM,EAAE,OAAO,KAAK,CAAC;AAClE;AAmBO,SAAS,eACZ,UACA,YACI;AAEN,QAAM,OAAO,cAAc,YAAY;AAAA,IACrC,eAAe,MAAa;AAC1B,YAAM,YAAY,IAAI;AAAA,IACxB;AAAA,EACF;AAGA,UAAQ,UAAU,IAAI;AACxB;",
   "names": []
 }

package/dist/plugs/copy.cjs

@@ -3,10 +3,6 @@ var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __getOwnPropNames = Object.getOwnPropertyNames;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
-var __export = (target, all) => {
-  for (var name in all)
-    __defProp(target, name, { get: all[name], enumerable: true });
-};
 var __copyProps = (to, from, except, desc) => {
   if (from && typeof from === "object" || typeof from === "function") {
     for (let key of __getOwnPropNames(from))
@@ -19,57 +15,55 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 
 // plugs/copy.ts
 var copy_exports = {};
-__export(copy_exports, {
-  Copy: () => Copy
-});
 module.exports = __toCommonJS(copy_exports);
 var import_assert = require("../assert.cjs");
+var import_files = require("../files.cjs");
 var import_log = require("../log.cjs");
 var import_paths = require("../paths.cjs");
 var import_pipe = require("../pipe.cjs");
 var import_asyncfs = require("../utils/asyncfs.cjs");
-var Copy = class {
+(0, import_pipe.install)("copy", class Copy {
   constructor(_directory, _options = {}) {
     this._directory = _directory;
     this._options = _options;
   }
-  async pipe(files, run) {
+  async pipe(files, context) {
     const { mode, dirMode, overwrite, rename = (s) => s } = this._options;
     const flags = overwrite ? import_asyncfs.fsConstants.COPYFILE_EXCL : 0;
     const dmode = parseMode(dirMode);
     const fmode = parseMode(mode);
-    const builder = run.files(this._directory);
+    const directory = context.resolve(this._directory);
+    const builder = import_files.Files.builder(directory);
     for (const [relative, absolute] of files.pathMappings()) {
       const target = (0, import_paths.resolveAbsolutePath)(builder.directory, rename(relative));
       if (target === absolute) {
-        run.log.warn("Cowardly refusing to copy same file", (0, import_log.$p)(absolute));
+        context.log.warn("Cowardly refusing to copy same file", (0, import_log.$p)(absolute));
         continue;
       }
-      const directory = (0, import_paths.getAbsoluteParent)(target);
-      const firstParent = await (0, import_asyncfs.mkdir)(directory, { recursive: true });
+      const directory2 = (0, import_paths.getAbsoluteParent)(target);
+      const firstParent = await (0, import_asyncfs.mkdir)(directory2, { recursive: true });
       if (firstParent && dmode !== void 0) {
         (0, import_paths.assertAbsolutePath)(firstParent);
-        for (let dir = directory; ; dir = (0, import_paths.getAbsoluteParent)(dir)) {
-          run.log.trace(`Setting mode ${stringifyMode(dmode)} for directory`, (0, import_log.$p)(dir));
+        for (let dir = directory2; ; dir = (0, import_paths.getAbsoluteParent)(dir)) {
+          context.log.trace(`Setting mode ${stringifyMode(dmode)} for directory`, (0, import_log.$p)(dir));
           await (0, import_asyncfs.chmod)(dir, dmode);
           if (dir === firstParent)
             break;
         }
       }
-      run.log.trace(`Copying "${(0, import_log.$p)(absolute)}" to "${(0, import_log.$p)(target)}"`);
+      context.log.trace(`Copying "${(0, import_log.$p)(absolute)}" to "${(0, import_log.$p)(target)}"`);
       await (0, import_asyncfs.copyFile)(absolute, target, flags);
       if (fmode !== void 0) {
-        run.log.trace(`Setting mode ${stringifyMode(fmode)} for file`, (0, import_log.$p)(target));
+        context.log.trace(`Setting mode ${stringifyMode(fmode)} for file`, (0, import_log.$p)(target));
         await (0, import_asyncfs.chmod)(target, fmode);
       }
-      builder.unchecked(relative);
+      builder.add(target);
     }
     const result = builder.build();
-    run.log.info("Copied", result.length, "files to", (0, import_log.$p)(builder.directory));
+    context.log.info("Copied", result.length, "files to", (0, import_log.$p)(builder.directory));
     return result;
   }
-};
-(0, import_pipe.install)("copy", Copy);
+});
 function parseMode(mode) {
   if (mode === void 0)
     return void 0;
@@ -82,8 +76,4 @@ function parseMode(mode) {
 function stringifyMode(mode) {
   return mode.toString(8).padStart(4, "0");
 }
-// Annotate the CommonJS export names for ESM import in node:
-0 && (module.exports = {
-  Copy
-});
 //# sourceMappingURL=copy.cjs.map

package/dist/plugs/copy.cjs.map

@@ -1,6 +1,6 @@
 {
   "version": 3,
   "sources": ["../../src/plugs/copy.ts"],
-  "mappings": ";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,oBAAuB;AAEvB,iBAAmB;AACnB,mBAA2E;AAC3E,kBAA8B;AAE9B,qBAAoD;AAe7C,IAAM,OAAN,MAAkC;AAAA,EAEvC,YACqB,YACA,WAAwB,CAAC,GAC5C;AAFmB;AACA;AAAA,EAClB;AAAA,EAEH,MAAM,KAAK,OAAc,KAA0B;AAEjD,UAAM,EAAE,MAAM,SAAS,WAAW,SAAS,CAAC,MAAc,EAAE,IAAI,KAAK;AACrE,UAAM,QAAQ,YAAY,2BAAY,gBAAgB;AACtD,UAAM,QAAQ,UAAU,OAAO;AAC/B,UAAM,QAAQ,UAAU,IAAI;AAG5B,UAAM,UAAU,IAAI,MAAM,KAAK,UAAU;AAGzC,eAAW,CAAE,UAAU,QAAS,KAAK,MAAM,aAAa,GAAG;AAGzD,YAAM,aAAS,kCAAoB,QAAQ,WAAW,OAAO,QAAQ,CAAC;AAGtE,UAAI,WAAW,UAAU;AACvB,YAAI,IAAI,KAAK,2CAAuC,eAAG,QAAQ,CAAC;AAChE;AAAA,MACF;AAGA,YAAM,gBAAY,gCAAkB,MAAM;AAC1C,YAAM,cAAc,UAAM,sBAAM,WAAW,EAAE,WAAW,KAAK,CAAC;AAG9D,UAAI,eAAgB,UAAU,QAAY;AACxC,6CAAmB,WAAW;AAC9B,iBAAS,MAAM,aAAa,UAAM,gCAAkB,GAAG,GAAG;AACxD,cAAI,IAAI,MAAM,gBAAgB,cAAc,KAAK,uBAAmB,eAAG,GAAG,CAAC;AAC3E,oBAAM,sBAAM,KAAK,KAAK;AACtB,cAAI,QAAQ;AAAa;AAAA,QAC3B;AAAA,MACF;AAGA,UAAI,IAAI,MAAM,gBAAY,eAAG,QAAQ,cAAU,eAAG,MAAM,IAAI;AAC5D,gBAAM,yBAAS,UAAU,QAAQ,KAAK;AAGtC,UAAI,UAAU,QAAW;AACvB,YAAI,IAAI,MAAM,gBAAgB,cAAc,KAAK,kBAAc,eAAG,MAAM,CAAC;AACzE,kBAAM,sBAAM,QAAQ,KAAK;AAAA,MAC3B;AAGA,cAAQ,UAAU,QAAQ;AAAA,IAC5B;AAEA,UAAM,SAAS,QAAQ,MAAM;AAC7B,QAAI,IAAI,KAAK,UAAU,OAAO,QAAQ,gBAAY,eAAG,QAAQ,SAAS,CAAC;AACvE,WAAO;AAAA,EACT;AACF;AAAA,IAMA,qBAAQ,QAAQ,IAAI;AAapB,SAAS,UAAU,MAAuD;AACxE,MAAI,SAAS;AAAW,WAAO;AAC/B,MAAI,OAAO,SAAS;AAAU,WAAO;AACrC,QAAM,SAAS,SAAS,MAAM,CAAC;AAC/B,4BAAO,CAAE,MAAM,MAAM,GAAG,iBAAiB,OAAO;AAChD,SAAO;AACT;AAEA,SAAS,cAAc,MAAsB;AAC3C,SAAO,KAAK,SAAS,CAAC,EAAE,SAAS,GAAG,GAAG;AACzC;",
-  "names": []
+  "mappings": ";;;;;;;;;;;;;;;;AAAA;AAAA;AAAA,oBAAuB;AACvB,mBAAsB;AACtB,iBAAmB;AACnB,mBAA2E;AAC3E,kBAAuD;AACvD,qBAAoD;AAAA,IAqCpD,qBAAQ,QAAQ,MAAM,KAA4B;AAAA,EAEhD,YACqB,YACA,WAAwB,CAAC,GAC5C;AAFmB;AACA;AAAA,EAClB;AAAA,EAEH,MAAM,KAAK,OAAc,SAAkC;AAEzD,UAAM,EAAE,MAAM,SAAS,WAAW,SAAS,CAAC,MAAc,EAAE,IAAI,KAAK;AACrE,UAAM,QAAQ,YAAY,2BAAY,gBAAgB;AACtD,UAAM,QAAQ,UAAU,OAAO;AAC/B,UAAM,QAAQ,UAAU,IAAI;AAG5B,UAAM,YAAY,QAAQ,QAAQ,KAAK,UAAU;AACjD,UAAM,UAAU,mBAAM,QAAQ,SAAS;AAGvC,eAAW,CAAE,UAAU,QAAS,KAAK,MAAM,aAAa,GAAG;AAGzD,YAAM,aAAS,kCAAoB,QAAQ,WAAW,OAAO,QAAQ,CAAC;AAGtE,UAAI,WAAW,UAAU;AACvB,gBAAQ,IAAI,KAAK,2CAAuC,eAAG,QAAQ,CAAC;AACpE;AAAA,MACF;AAGA,YAAMA,iBAAY,gCAAkB,MAAM;AAC1C,YAAM,cAAc,UAAM,sBAAMA,YAAW,EAAE,WAAW,KAAK,CAAC;AAG9D,UAAI,eAAgB,UAAU,QAAY;AACxC,6CAAmB,WAAW;AAC9B,iBAAS,MAAMA,cAAa,UAAM,gCAAkB,GAAG,GAAG;AACxD,kBAAQ,IAAI,MAAM,gBAAgB,cAAc,KAAK,uBAAmB,eAAG,GAAG,CAAC;AAC/E,oBAAM,sBAAM,KAAK,KAAK;AACtB,cAAI,QAAQ;AAAa;AAAA,QAC3B;AAAA,MACF;AAGA,cAAQ,IAAI,MAAM,gBAAY,eAAG,QAAQ,cAAU,eAAG,MAAM,IAAI;AAChE,gBAAM,yBAAS,UAAU,QAAQ,KAAK;AAGtC,UAAI,UAAU,QAAW;AACvB,gBAAQ,IAAI,MAAM,gBAAgB,cAAc,KAAK,kBAAc,eAAG,MAAM,CAAC;AAC7E,kBAAM,sBAAM,QAAQ,KAAK;AAAA,MAC3B;AAGA,cAAQ,IAAI,MAAM;AAAA,IACpB;AAEA,UAAM,SAAS,QAAQ,MAAM;AAC7B,YAAQ,IAAI,KAAK,UAAU,OAAO,QAAQ,gBAAY,eAAG,QAAQ,SAAS,CAAC;AAC3E,WAAO;AAAA,EACT;AACF,CAAC;AAMD,SAAS,UAAU,MAAuD;AACxE,MAAI,SAAS;AAAW,WAAO;AAC/B,MAAI,OAAO,SAAS;AAAU,WAAO;AACrC,QAAM,SAAS,SAAS,MAAM,CAAC;AAC/B,4BAAO,CAAE,MAAM,MAAM,GAAG,iBAAiB,OAAO;AAChD,SAAO;AACT;AAEA,SAAS,cAAc,MAAsB;AAC3C,SAAO,KAAK,SAAS,CAAC,EAAE,SAAS,GAAG,GAAG;AACzC;",
+  "names": ["directory"]
 }

package/dist/plugs/copy.d.ts

@@ -1,6 +1,3 @@
-import { Files } from '../files.js';
-import { Plug } from '../pipe.js';
-import { Run } from '../run.js';
 /** Options for copying files */
 export interface CopyOptions {
     /** Whether to allow overwriting or not (default `false`). */
@@ -12,16 +9,20 @@ export interface CopyOptions {
     /** If specified, this function will be invoked to rename files. */
     rename?: (relative: string) => string;
 }
-/** Copy the curent {@link Files} to a different directory */
-export declare class Copy implements Plug<Files> {
-    private readonly _directory;
-    private readonly _options;
-    constructor(directory: string, options?: CopyOptions);
-    pipe(files: Files, run: Run): Promise<Files>;
-}
-declare module '../pipe.js' {
+declare module '../pipe' {
     interface Pipe {
-        /** Copy the curent {@link Files} to a different directory */
-        copy: PipeExtension<typeof Copy>;
+        /**
+         * Copy the curent {@link Files} to a different directory
+         *
+         * @param directory The target directory where files will be copied to
+         */
+        copy(directory: string): Pipe;
+        /**
+         * Copy the curent {@link Files} to a different directory
+         *
+         * @param directory The target directory where files will be copied to
+         * @param options Extra {@link CopyOptions | options} for the copy operation
+         */
+        copy(directory: string, options: CopyOptions): Pipe;
     }
 }