js-build-tools 6.1.0 → 6.2.0

package/README.md

@@ -11,7 +11,9 @@ Using this tool suite, you can:
 * Bundle your distribution files to be used in a browser environment.
 * Run tests and watch for changes.
 * Generate jsdoc readme files.
-* Generate HTML documentation straight from your TypeScript source (with TypeDoc), with a module for each of your folders.
+* Generate real HTML documentation straight from your source - TypeDoc for a TypeScript project (a module for
+  each of your folders), or jsdoc with a modern theme for a plain JavaScript one.
+* Copy files (a bundle, or anything else) to another location, on demand.
 
 ## Installation
 
@@ -281,10 +283,12 @@ module.exports = {
 }
 ```
 
-### Configure HTML JS Documentation (optional)
+### Configure HTML JS Documentation, full manual control (optional, advanced)
 
-It may be desirable to generate HTML documentation for your JS files.
-(For a TypeScript project, see 'Configure TypeScript documentation' instead.)
+For most projects, `docs.enabled` with `docs.method: 'jsdoc'` (see 'Configure HTML documentation' below) is the
+simpler path - no `.jsdoc.conf.js` file to maintain by hand, wired straight into `gulp build`/`gulp docs`. This
+section is for when you want full, direct control over jsdoc's own config instead (a plugin or option this
+project's own generated config does not expose, for example).
 
 Create a `.jsdoc.conf.js` file and add the following:
 
@@ -376,6 +380,33 @@ exports if you want it documented this cleanly:
 }
 ```
 
+### Configure copy files (optional)
+
+Copy files (a bundle, or anything else) to another location - any number of entries, each independent. Unlike
+every other task here, this is never run automatically as part of `gulp build` - what this copies is often the
+live, publicly-reachable version of something, so publishing it should be a deliberate step your own script
+opts into, not a side effect of a routine local build.
+
+Add the following to the exports in your `build-tools.config.json`:
+
+```json
+{
+  "copyFiles": [
+    {
+      // The glob pattern(s) of files to copy
+      "from": "browser/**/*.js",
+      // The directory to copy them into
+      "to": "../my-other-project/vendor",
+      // Optional - preserves this glob's own subdirectory structure in the destination, instead of flattening it
+      "base": "browser"
+    }
+  ]
+}
+```
+
+If you also export `copyFiles` from your gulpfile you can run it on its own with `gulp copyFiles`, and can then
+add your own script for it, for example `"publish:bundle": "gulp copyFiles"`.
+
 ### Configure move fonts (optional)
 
 Be able to copy a source directory of fonts into the distribution path.
@@ -498,32 +529,46 @@ babelConfig.presets.push('@babel/preset-typescript')
 module.exports = babelConfig
 ```
 
-### Configure TypeScript documentation (optional)
-
-`jsdoc-to-markdown` only reads `.js` files, so the types in your `.ts` files (and the comments on them) do not reach
-the readme it generates. Instead, this can generate HTML documentation straight from the TypeScript source with
-[TypeDoc](https://typedoc.org/). Every folder in your source directory becomes a module of the documentation, the default
-export of each file (one function per file) is listed under the name of the file, and everything else a file exports (for
-example the types in a `types.ts`) is listed as it is. Index files, tests and declaration files are left out. A file
-which sits directly in the source directory, beside the folders, is a module of its own (unless it is `index` or
-`main`). The first comment of a folder's `index.ts` (or the header comment of such a file) describes its module. The
-comments on your code are the documentation, and the types come from the code itself, so `@module`, `@memberOf`,
-`@typedef` and the `{Type}` of `@param` are not needed.
-
-`typedoc` is an optional peer dependency (like `typescript`), install it in your project with
-`npm install --save-dev typedoc` (this needs a `typescript` version it supports).
+### Configure HTML documentation (optional)
+
+`jsdoc-to-markdown` (the readme generator) only reads `.js` files, so the types in your `.ts` files (and the
+comments on them) never reach the readme it generates, and even for a plain JavaScript project a single
+markdown readme is a thinner result than a real browsable site. Instead, `docs.enabled` generates real HTML
+documentation straight from your source, with either engine:
+
+* **TypeDoc** (for a TypeScript project) - every folder in your source directory becomes a module of the
+  documentation, the default export of each file (one function per file) is listed under the name of the file,
+  and everything else a file exports (for example the types in a `types.ts`) is listed as it is. Index files,
+  tests and declaration files are left out. A file which sits directly in the source directory, beside the
+  folders, is a module of its own (unless it is `index` or `main`). The first comment of a folder's `index.ts`
+  (or the header comment of such a file) describes its module. The comments on your code are the documentation,
+  and the types come from the code itself, so `@module`, `@memberOf`, `@typedef` and the `{Type}` of `@param`
+  are not needed. `typedoc` is an optional peer dependency (like `typescript`), install it in your project with
+  `npm install --save-dev typedoc` (this needs a `typescript` version it supports).
+* **jsdoc** (for a plain JavaScript project, where TypeDoc has no real types to read) - scans your source
+  recursively with jsdoc itself, rendered with a modern theme (`clean-jsdoc-theme` by default, used instead of
+  jsdoc's own classic default template) instead of the manual `.jsdoc.conf.js` setup described further below.
+  `jsdoc` and whichever theme you configure are optional peer dependencies, install them with
+  `npm install --save-dev jsdoc clean-jsdoc-theme` (or your own chosen theme package).
 
 Add the following to the exports in your `build-tools.config.json`:
 
 ```json
 {
   "docs": {
-    // Generate the documentation from the TypeScript source
+    // Generate the documentation from the source
     "enabled": true,
-    // The directory holding the TypeScript source, each folder in it becomes a module
+    // The directory holding the source, each folder in it becomes a module (TypeDoc) or is scanned recursively (jsdoc)
     "from": "src",
     // The markdown file used as the front page of the documentation (a short overview of your project)
     "index": "MAIN.md",
+    // 'typedoc' or 'jsdoc'. Left out (or false), it's inferred from typescript.enabled - 'typedoc' when your
+    // project is TypeScript, 'jsdoc' when it is not - so most projects never need to set this at all. Set it
+    // explicitly to override that inference either way.
+    "method": false,
+    // Only meaningful when method is (or resolves to) 'jsdoc' - the theme package to render with. TypeDoc
+    // always keeps its own default regardless of this setting.
+    "theme": "clean-jsdoc-theme",
     // Where the HTML is generated (the directory is cleared first)
     "to": "docs"
   }
@@ -569,6 +614,7 @@ In your `package.json` file, add the following scripts:
     "dev": "gulp",
     "docs": "gulp docs",
     "htmldocs": "jsdoc -R MAIN.md -c ./.jsdoc.conf.js -d docs",
+    "publish:bundle": "gulp copyFiles",
     "readme": "gulp readme",
     "sass": "gulp sass",
     "test": "gulp testFull",
@@ -629,6 +675,7 @@ Modify these configurations to match your project specifications.
         * [~JestTestFlags](#module_gulpConfig..JestTestFlags) : <code>FlagsSetting</code>
         * [~StringSetting](#module_gulpConfig..StringSetting) : <code>string</code>
         * [~Setting](#module_gulpConfig..Setting) : <code>ArrayableSetting</code> \| <code>BooleanSetting</code> \| <code>FlagsSetting</code> \| <code>StringSetting</code>
+        * [~CopyFilesEntry](#module_gulpConfig..CopyFilesEntry) : <code>Object</code>
         * [~BrowserConfig](#module_gulpConfig..BrowserConfig) : <code>Object.&lt;string, Setting&gt;</code>
         * [~AdditionalBundleConfig](#module_gulpConfig..AdditionalBundleConfig) : <code>Object.&lt;string, Setting&gt;</code>
         * [~DistConfig](#module_gulpConfig..DistConfig) : <code>Object.&lt;string, Setting&gt;</code>
@@ -722,6 +769,20 @@ A setting that may only be a string.
 Any single configuration option is a Setting.
 
 **Kind**: inner typedef of [<code>gulpConfig</code>](#module_gulpConfig)  
+<a name="module_gulpConfig..CopyFilesEntry"></a>
+
+### gulpConfig~CopyFilesEntry : <code>Object</code>
+One copy-files entry: a glob (or array of globs) to copy, and where to copy it.
+
+**Kind**: inner typedef of [<code>gulpConfig</code>](#module_gulpConfig)  
+**Properties**
+
+| Name | Type | Description |
+| --- | --- | --- |
+| from | <code>ArrayableSetting</code> | The glob pattern(s) of files to copy. |
+| to | <code>StringSetting</code> | The directory to copy them into. |
+| base | <code>FlagStringSetting</code> | Optional base for gulp's own src(pattern, {base}), to preserve a glob's own subdirectory structure in the destination instead of flattening it. false (the default) uses gulp's own default base behaviour. |
+
 <a name="module_gulpConfig..BrowserConfig"></a>
 
 ### gulpConfig~BrowserConfig : <code>Object.&lt;string, Setting&gt;</code>
@@ -829,20 +890,22 @@ Configurations to compile and generate the Readme file.
 <a name="module_gulpConfig..DocsConfig"></a>
 
 ### gulpConfig~DocsConfig : <code>Object.&lt;string, Setting&gt;</code>
-Configurations for generating the HTML documentation of a TypeScript project (with TypeDoc, from the source).
+Configurations for generating the HTML documentation of a project's own source, with either TypeDoc (real
 
 **Kind**: inner typedef of [<code>gulpConfig</code>](#module_gulpConfig)  
 **Properties**
 
 | Name | Type | Description |
 | --- | --- | --- |
-| enabled | <code>BooleanSetting</code> | Toggle generating the documentation from the TypeScript source. When it is on the build does this instead of generating the readme from the jsdoc comments of the compiled files. |
-| from | <code>StringSetting</code> | The directory holding the TypeScript source, each folder in it becomes a module. |
+| enabled | <code>BooleanSetting</code> | Toggle generating the documentation from the source. When it is on the build does this instead of generating the readme from the jsdoc comments of the compiled files. |
+| from | <code>StringSetting</code> | The directory holding the source, each folder in it becomes a module (TypeDoc) or is scanned recursively (jsdoc). |
 | index | <code>StringSetting</code> | The markdown file used as the front page of the documentation. |
-| logLevel | <code>StringSetting</code> | How much TypeDoc reports: Verbose, Info, Warn, Error or None. |
+| logLevel | <code>StringSetting</code> | How much TypeDoc reports: Verbose, Info, Warn, Error or None. Not used by jsdoc. |
+| method | <code>FlagStringSetting</code> | 'typedoc' or 'jsdoc'. False (the default) infers it from typescript.enabled - 'typedoc' when on, 'jsdoc' when off - so an existing TypeScript project's config needs no change to keep working exactly as it already does; set this explicitly to override that inference either way. |
+| theme | <code>StringSetting</code> | The jsdoc theme package to use (only meaningful when method is 'jsdoc' - TypeDoc keeps its own default regardless). Defaults to 'clean-jsdoc-theme'. |
 | title | <code>StringSetting</code> | The name of the documentation, defaults to the name in the package.json. |
 | to | <code>StringSetting</code> | The directory to generate the documentation in (it is cleared first). |
-| tsconfig | <code>FlagStringSetting</code> | The tsconfig file to read the source with, defaults to the one of typescript.config. |
+| tsconfig | <code>FlagStringSetting</code> | The tsconfig file to read the source with (TypeDoc only), defaults to the one of typescript.config. |
 
 <a name="module_gulpConfig..SassConfig"></a>
 
@@ -900,6 +963,7 @@ A set of Configurations options defined by Settings.
 | --- | --- | --- |
 | browser | <code>BrowserConfig</code> | Browser bundling configuration group. |
 | cleanPaths | <code>ArrayableSetting</code> | The paths for directories to delete before build. |
+| copyFiles | <code>Array.&lt;CopyFilesEntry&gt;</code> | Files to copy elsewhere, run via the copyFiles task - never automatically as part of build, since what this copies is often the live, publicly-reachable version of something (e.g. a bundle), and publishing it should be a deliberate step. |
 | dist | <code>DistConfig</code> | Distribution file generation configuration group. |
 | docs | <code>DocsConfig</code> | Generate the documentation of a TypeScript project configuration group. |
 | fonts | <code>FontConfig</code> | Fonts copy configuration group. |

package/dist/build.js

@@ -1,70 +1,75 @@
-"use strict";
-
-require("core-js/modules/esnext.weak-map.delete-all.js");
-Object.defineProperty(exports, "__esModule", {
-  value: true
-});
-exports.build = void 0;
-var _bundle = require("./bundle.js");
-var _bundleMinify = require("./bundleMinify.js");
-var _partials = require("./partials.js");
-var _compileReadme = require("./compileReadme.js");
-var _typeDocs = require("./typeDocs.js");
-var _distMinify = require("./distMinify.js");
-var _sourceLint = require("./sourceLint.js");
-var _gulp = require("gulp");
-var gulpConfig = _interopRequireWildcard(require("../gulp.config.js"));
-var _copyFonts = require("./copyFonts.js");
-var _images = require("./images.js");
-var _sass = require("./sass.js");
-var _testFull = require("./testFull.js");
-var cache;
-function _interopRequireWildcard(e, t) { if (!t && e && e.__esModule) return e; var r, c, a = Object.defineProperty, n = { __proto__: null, default: e }; if (Object(e) !== e) return n; if (cache || "function" != typeof WeakMap || (cache = new WeakMap()), cache) { if (cache.has(e)) return cache.get(e); cache.set(e, n); } for (c in e) "default" !== c && {}.hasOwnProperty.call(e, c) && ((r = a && Object.getOwnPropertyDescriptor(e, c)) && (r.get || r.set) ? a(n, c, r) : n[c] = e[c]); return n; }
+"use strict";
+
+require("core-js/modules/esnext.weak-map.delete-all.js");
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.build = void 0;
+var _bundle = require("./bundle.js");
+var _bundleMinify = require("./bundleMinify.js");
+var _partials = require("./partials.js");
+var _compileReadme = require("./compileReadme.js");
+var _typeDocs = require("./typeDocs.js");
+var _jsdocDocs = require("./jsdocDocs.js");
+var _distMinify = require("./distMinify.js");
+var _sourceLint = require("./sourceLint.js");
+var _gulp = require("gulp");
+var gulpConfig = _interopRequireWildcard(require("../gulp.config.js"));
+var _copyFonts = require("./copyFonts.js");
+var _images = require("./images.js");
+var _sass = require("./sass.js");
+var _testFull = require("./testFull.js");
+var cache;
+function _interopRequireWildcard(e, t) { if (!t && e && e.__esModule) return e; var r, c, a = Object.defineProperty, n = { __proto__: null, default: e }; if (Object(e) !== e) return n; if (cache || "function" != typeof WeakMap || (cache = new WeakMap()), cache) { if (cache.has(e)) return cache.get(e); cache.set(e, n); } for (c in e) "default" !== c && {}.hasOwnProperty.call(e, c) && ((r = a && Object.getOwnPropertyDescriptor(e, c)) && (r.get || r.set) ? a(n, c, r) : n[c] = e[c]); return n; }
 /**
  * Runs several processes to build and validate the project.
  * Cleans and lints the source, distributes and minifies, bundles and minifies, creates the readme, then runs the
  * tests.
  * @memberOf module:js-build-tools
  * @returns {stream.Stream}
- */
-const build = (done = null) => {
-  const buildActions = [(0, _partials.distSeries)(), _distMinify.distMinify];
-  const generateDocs = gulpConfig.get('docs.enabled');
-  if (generateDocs) {
-    // The documentation is generated from the TypeScript source itself, the readme is written by hand
-    buildActions.push(_typeDocs.typeDocs);
-  } else if (gulpConfig.get('typescript.enabled')) {
-    // For ts usage, we need to run the readme on the dist directly since that is where the .js files are located
-    buildActions.push(_compileReadme.compileReadme);
-  }
-  if (gulpConfig.get('browser.enabled')) {
-    // If not 'nodeOnly' then we also want to bundle for browser after we complete the dist directory
-    buildActions.push(_bundle.bundle);
-    buildActions.push(_bundleMinify.bundleMinify);
-  }
-  const runActions = [(0, _gulp.series)(...buildActions)];
-  if (!generateDocs && !gulpConfig.get('typescript.enabled')) {
-    // Since we didn't run this in series after dist because of typescript, we need to run it now. Potentially faster here.
-    runActions.push(_compileReadme.compileReadme);
-  }
-  runActions.push(_testFull.testFull);
-  if (gulpConfig.get('fonts.enabled')) {
-    // Conditionally add Fonts process
-    runActions.push(_copyFonts.copyFonts);
-  }
-  if (gulpConfig.get('images.enabled')) {
-    // Conditionally add Images process
-    runActions.push(_images.images);
-  }
-  if (gulpConfig.get('sass.enabled')) {
-    // Conditionally add SASS process
-    runActions.push(_sass.sass);
-  }
-  // clean has to finish before anything writes into the output folders - images, fonts and sass all write into
-  // browser/, so running clean in parallel with them races (ENOTEMPTY errors from clean, or output deleted mid-write).
-  // sourceLint fixes the real source in place before anything compiles from it (distSeries, tsFor inside it), so a
-  // build never reads a mix of pre- and post-fix content; clean only touches dist/browser output, so the two can
-  // run alongside each other.
-  return (0, _gulp.series)((0, _gulp.parallel)(_partials.clean, _sourceLint.sourceLint), (0, _gulp.parallel)(...runActions))(done);
-};
+ */
+const build = (done = null) => {
+  const buildActions = [(0, _partials.distSeries)(), _distMinify.distMinify];
+  const generateDocs = gulpConfig.get('docs.enabled');
+  // docs.method picks the engine explicitly; left unset (false, the default), it's inferred from
+  // typescript.enabled - every existing TypeScript project's config, which never sets method, keeps producing
+  // TypeDoc output exactly as it always has.
+  const docsMethod = gulpConfig.get('docs.method') || (gulpConfig.get('typescript.enabled') ? 'typedoc' : 'jsdoc');
+  if (generateDocs) {
+    // The documentation is generated from the source itself, the readme is written by hand
+    buildActions.push(docsMethod === 'jsdoc' ? _jsdocDocs.jsdocDocs : _typeDocs.typeDocs);
+  } else if (gulpConfig.get('typescript.enabled')) {
+    // For ts usage, we need to run the readme on the dist directly since that is where the .js files are located
+    buildActions.push(_compileReadme.compileReadme);
+  }
+  if (gulpConfig.get('browser.enabled')) {
+    // If not 'nodeOnly' then we also want to bundle for browser after we complete the dist directory
+    buildActions.push(_bundle.bundle);
+    buildActions.push(_bundleMinify.bundleMinify);
+  }
+  const runActions = [(0, _gulp.series)(...buildActions)];
+  if (!generateDocs && !gulpConfig.get('typescript.enabled')) {
+    // Since we didn't run this in series after dist because of typescript, we need to run it now. Potentially faster here.
+    runActions.push(_compileReadme.compileReadme);
+  }
+  runActions.push(_testFull.testFull);
+  if (gulpConfig.get('fonts.enabled')) {
+    // Conditionally add Fonts process
+    runActions.push(_copyFonts.copyFonts);
+  }
+  if (gulpConfig.get('images.enabled')) {
+    // Conditionally add Images process
+    runActions.push(_images.images);
+  }
+  if (gulpConfig.get('sass.enabled')) {
+    // Conditionally add SASS process
+    runActions.push(_sass.sass);
+  }
+  // clean has to finish before anything writes into the output folders - images, fonts and sass all write into
+  // browser/, so running clean in parallel with them races (ENOTEMPTY errors from clean, or output deleted mid-write).
+  // sourceLint fixes the real source in place before anything compiles from it (distSeries, tsFor inside it), so a
+  // build never reads a mix of pre- and post-fix content; clean only touches dist/browser output, so the two can
+  // run alongside each other.
+  return (0, _gulp.series)((0, _gulp.parallel)(_partials.clean, _sourceLint.sourceLint), (0, _gulp.parallel)(...runActions))(done);
+};
 exports.build = build;

package/dist/build.min.js

@@ -1 +1 @@
-"use strict";require("core-js/modules/esnext.weak-map.delete-all.js"),Object.defineProperty(exports,"__esModule",{value:!0}),exports.build=void 0;var cache,_bundle=require("./bundle.js"),_bundleMinify=require("./bundleMinify.js"),_partials=require("./partials.js"),_compileReadme=require("./compileReadme.js"),_typeDocs=require("./typeDocs.js"),_distMinify=require("./distMinify.js"),_sourceLint=require("./sourceLint.js"),_gulp=require("gulp"),gulpConfig=_interopRequireWildcard(require("../gulp.config.js")),_copyFonts=require("./copyFonts.js"),_images=require("./images.js"),_sass=require("./sass.js"),_testFull=require("./testFull.js");function _interopRequireWildcard(e,s){if(!s&&e&&e.__esModule)return e;var i,r,t=Object.defineProperty,l={__proto__:null,default:e};if(Object(e)!==e)return l;if(cache||"function"!=typeof WeakMap||(cache=new WeakMap),cache){if(cache.has(e))return cache.get(e);cache.set(e,l)}for(r in e)"default"!==r&&{}.hasOwnProperty.call(e,r)&&((i=t&&Object.getOwnPropertyDescriptor(e,r))&&(i.get||i.set)?t(l,r,i):l[r]=e[r]);return l}const build=(e=null)=>{const s=[(0,_partials.distSeries)(),_distMinify.distMinify],i=gulpConfig.get("docs.enabled");i?s.push(_typeDocs.typeDocs):gulpConfig.get("typescript.enabled")&&s.push(_compileReadme.compileReadme),gulpConfig.get("browser.enabled")&&(s.push(_bundle.bundle),s.push(_bundleMinify.bundleMinify));const r=[(0,_gulp.series)(...s)];return i||gulpConfig.get("typescript.enabled")||r.push(_compileReadme.compileReadme),r.push(_testFull.testFull),gulpConfig.get("fonts.enabled")&&r.push(_copyFonts.copyFonts),gulpConfig.get("images.enabled")&&r.push(_images.images),gulpConfig.get("sass.enabled")&&r.push(_sass.sass),(0,_gulp.series)((0,_gulp.parallel)(_partials.clean,_sourceLint.sourceLint),(0,_gulp.parallel)(...r))(e)};exports.build=build;
+"use strict";require("core-js/modules/esnext.weak-map.delete-all.js"),Object.defineProperty(exports,"__esModule",{value:!0}),exports.build=void 0;var cache,_bundle=require("./bundle.js"),_bundleMinify=require("./bundleMinify.js"),_partials=require("./partials.js"),_compileReadme=require("./compileReadme.js"),_typeDocs=require("./typeDocs.js"),_jsdocDocs=require("./jsdocDocs.js"),_distMinify=require("./distMinify.js"),_sourceLint=require("./sourceLint.js"),_gulp=require("gulp"),gulpConfig=_interopRequireWildcard(require("../gulp.config.js")),_copyFonts=require("./copyFonts.js"),_images=require("./images.js"),_sass=require("./sass.js"),_testFull=require("./testFull.js");function _interopRequireWildcard(e,s){if(!s&&e&&e.__esModule)return e;var i,t,r=Object.defineProperty,l={__proto__:null,default:e};if(Object(e)!==e)return l;if(cache||"function"!=typeof WeakMap||(cache=new WeakMap),cache){if(cache.has(e))return cache.get(e);cache.set(e,l)}for(t in e)"default"!==t&&{}.hasOwnProperty.call(e,t)&&((i=r&&Object.getOwnPropertyDescriptor(e,t))&&(i.get||i.set)?r(l,t,i):l[t]=e[t]);return l}const build=(e=null)=>{const s=[(0,_partials.distSeries)(),_distMinify.distMinify],i=gulpConfig.get("docs.enabled"),t=gulpConfig.get("docs.method")||(gulpConfig.get("typescript.enabled")?"typedoc":"jsdoc");i?s.push("jsdoc"===t?_jsdocDocs.jsdocDocs:_typeDocs.typeDocs):gulpConfig.get("typescript.enabled")&&s.push(_compileReadme.compileReadme),gulpConfig.get("browser.enabled")&&(s.push(_bundle.bundle),s.push(_bundleMinify.bundleMinify));const r=[(0,_gulp.series)(...s)];return i||gulpConfig.get("typescript.enabled")||r.push(_compileReadme.compileReadme),r.push(_testFull.testFull),gulpConfig.get("fonts.enabled")&&r.push(_copyFonts.copyFonts),gulpConfig.get("images.enabled")&&r.push(_images.images),gulpConfig.get("sass.enabled")&&r.push(_sass.sass),(0,_gulp.series)((0,_gulp.parallel)(_partials.clean,_sourceLint.sourceLint),(0,_gulp.parallel)(...r))(e)};exports.build=build;

package/dist/bundle.js

@@ -1,21 +1,21 @@
-"use strict";
-
-require("core-js/modules/esnext.weak-map.delete-all.js");
-Object.defineProperty(exports, "__esModule", {
-  value: true
-});
-exports.bundle = void 0;
-require("core-js/modules/esnext.iterator.constructor.js");
-require("core-js/modules/esnext.iterator.map.js");
-var _browserify = _interopRequireDefault(require("browserify"));
-var _gulp = require("gulp");
-var _mergeStream = _interopRequireDefault(require("merge-stream"));
-var gulpConfig = _interopRequireWildcard(require("../gulp.config.js"));
-var _vinylSourceStream = _interopRequireDefault(require("vinyl-source-stream"));
-var _getBundleConfigs = require("./utilities/getBundleConfigs.js");
-var cache;
-function _interopRequireWildcard(e, t) { if (!t && e && e.__esModule) return e; var r, c, a = Object.defineProperty, n = { __proto__: null, default: e }; if (Object(e) !== e) return n; if (cache || "function" != typeof WeakMap || (cache = new WeakMap()), cache) { if (cache.has(e)) return cache.get(e); cache.set(e, n); } for (c in e) "default" !== c && {}.hasOwnProperty.call(e, c) && ((r = a && Object.getOwnPropertyDescriptor(e, c)) && (r.get || r.set) ? a(n, c, r) : n[c] = e[c]); return n; }
-function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
+"use strict";
+
+require("core-js/modules/esnext.weak-map.delete-all.js");
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.bundle = void 0;
+require("core-js/modules/esnext.iterator.constructor.js");
+require("core-js/modules/esnext.iterator.map.js");
+var _browserify = _interopRequireDefault(require("browserify"));
+var _gulp = require("gulp");
+var _mergeStream = _interopRequireDefault(require("merge-stream"));
+var gulpConfig = _interopRequireWildcard(require("../gulp.config.js"));
+var _vinylSourceStream = _interopRequireDefault(require("vinyl-source-stream"));
+var _getBundleConfigs = require("./utilities/getBundleConfigs.js");
+var cache;
+function _interopRequireWildcard(e, t) { if (!t && e && e.__esModule) return e; var r, c, a = Object.defineProperty, n = { __proto__: null, default: e }; if (Object(e) !== e) return n; if (cache || "function" != typeof WeakMap || (cache = new WeakMap()), cache) { if (cache.has(e)) return cache.get(e); cache.set(e, n); } for (c in e) "default" !== c && {}.hasOwnProperty.call(e, c) && ((r = a && Object.getOwnPropertyDescriptor(e, c)) && (r.get || r.set) ? a(n, c, r) : n[c] = e[c]); return n; }
+function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
 /**
  * Starting at each bundle's own entry point (dist.main for the primary bundle, or its own
  * override from browser.bundles), bundle all the reachable files into a single file per bundle and
@@ -35,26 +35,26 @@ function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e
  * code must not require it, or provide it another way, such as a separate script tag).
  * @memberOf module:js-build-tools
  * @returns {stream.Stream}
- */
-const bundle = () => (0, _mergeStream.default)((0, _getBundleConfigs.getBundleConfigs)().map(({
-  name,
-  main,
-  ignore,
-  exclude
-}) => {
-  const bundler = (0, _browserify.default)(main, {
-    standalone: name
-  });
-  if (ignore.length) {
-    bundler.ignore(ignore);
-  }
-  if (exclude.length) {
-    bundler.exclude(exclude);
-  }
-  return bundler.bundle().pipe((0, _vinylSourceStream.default)(`${name}.js`));
-})
-// One shared dest() for every bundle, not one per bundle - vinyl-fs's dest() races against
-// itself (a real "write after end" failure) when two separate dest() streams target the same
-// directory concurrently, which every additional bundle's own dest() call otherwise would.
-).pipe((0, _gulp.dest)(gulpConfig.get('browser.to')));
+ */
+const bundle = () => (0, _mergeStream.default)((0, _getBundleConfigs.getBundleConfigs)().map(({
+  name,
+  main,
+  ignore,
+  exclude
+}) => {
+  const bundler = (0, _browserify.default)(main, {
+    standalone: name
+  });
+  if (ignore.length) {
+    bundler.ignore(ignore);
+  }
+  if (exclude.length) {
+    bundler.exclude(exclude);
+  }
+  return bundler.bundle().pipe((0, _vinylSourceStream.default)(`${name}.js`));
+})
+// One shared dest() for every bundle, not one per bundle - vinyl-fs's dest() races against
+// itself (a real "write after end" failure) when two separate dest() streams target the same
+// directory concurrently, which every additional bundle's own dest() call otherwise would.
+).pipe((0, _gulp.dest)(gulpConfig.get('browser.to')));
 exports.bundle = bundle;

package/dist/bundleMinify.js

@@ -1,17 +1,17 @@
-"use strict";
-
-require("core-js/modules/esnext.weak-map.delete-all.js");
-Object.defineProperty(exports, "__esModule", {
-  value: true
-});
-exports.bundleMinify = void 0;
-require("core-js/modules/esnext.iterator.constructor.js");
-require("core-js/modules/esnext.iterator.map.js");
-var gulpConfig = _interopRequireWildcard(require("../gulp.config.js"));
-var _minifyFor = require("./partials/minifyFor.js");
-var _getBundleConfigs = require("./utilities/getBundleConfigs.js");
-var cache;
-function _interopRequireWildcard(e, t) { if (!t && e && e.__esModule) return e; var r, c, a = Object.defineProperty, n = { __proto__: null, default: e }; if (Object(e) !== e) return n; if (cache || "function" != typeof WeakMap || (cache = new WeakMap()), cache) { if (cache.has(e)) return cache.get(e); cache.set(e, n); } for (c in e) "default" !== c && {}.hasOwnProperty.call(e, c) && ((r = a && Object.getOwnPropertyDescriptor(e, c)) && (r.get || r.set) ? a(n, c, r) : n[c] = e[c]); return n; }
+"use strict";
+
+require("core-js/modules/esnext.weak-map.delete-all.js");
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.bundleMinify = void 0;
+require("core-js/modules/esnext.iterator.constructor.js");
+require("core-js/modules/esnext.iterator.map.js");
+var gulpConfig = _interopRequireWildcard(require("../gulp.config.js"));
+var _minifyFor = require("./partials/minifyFor.js");
+var _getBundleConfigs = require("./utilities/getBundleConfigs.js");
+var cache;
+function _interopRequireWildcard(e, t) { if (!t && e && e.__esModule) return e; var r, c, a = Object.defineProperty, n = { __proto__: null, default: e }; if (Object(e) !== e) return n; if (cache || "function" != typeof WeakMap || (cache = new WeakMap()), cache) { if (cache.has(e)) return cache.get(e); cache.set(e, n); } for (c in e) "default" !== c && {}.hasOwnProperty.call(e, c) && ((r = a && Object.getOwnPropertyDescriptor(e, c)) && (r.get || r.set) ? a(n, c, r) : n[c] = e[c]); return n; }
 /**
  * Creates the minified file for every bundle (the primary bundle, plus any additional ones from
  * browser.bundles). The minify step itself never varies per bundle, so this is one shared
@@ -19,8 +19,8 @@ function _interopRequireWildcard(e, t) { if (!t && e && e.__esModule) return e;
  * pipeline per bundle - gulp's src() accepts an array of paths natively.
  * @memberOf module:js-build-tools
  * @returns {*}
- */
-const bundleMinify = () => (0, _minifyFor.minifyFor)((0, _getBundleConfigs.getBundleConfigs)().map(({
-  name
-}) => `${gulpConfig.get('browser.to')}/${name}.js`), gulpConfig.get('browser.to'));
+ */
+const bundleMinify = () => (0, _minifyFor.minifyFor)((0, _getBundleConfigs.getBundleConfigs)().map(({
+  name
+}) => `${gulpConfig.get('browser.to')}/${name}.js`), gulpConfig.get('browser.to'));
 exports.bundleMinify = bundleMinify;

package/dist/copyFiles.js

@@ -0,0 +1,47 @@
+"use strict";
+
+require("core-js/modules/esnext.weak-map.delete-all.js");
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.copyFiles = void 0;
+require("core-js/modules/esnext.iterator.constructor.js");
+require("core-js/modules/esnext.iterator.map.js");
+var _copyFor = require("./partials/copyFor.js");
+var gulpConfig = _interopRequireWildcard(require("../gulp.config.js"));
+var cache;
+function _interopRequireWildcard(e, t) { if (!t && e && e.__esModule) return e; var r, c, a = Object.defineProperty, n = { __proto__: null, default: e }; if (Object(e) !== e) return n; if (cache || "function" != typeof WeakMap || (cache = new WeakMap()), cache) { if (cache.has(e)) return cache.get(e); cache.set(e, n); } for (c in e) "default" !== c && {}.hasOwnProperty.call(e, c) && ((r = a && Object.getOwnPropertyDescriptor(e, c)) && (r.get || r.set) ? a(n, c, r) : n[c] = e[c]); return n; }
+/**
+ * Copy files from one place to another - any number of { from, to, base? } entries, configured via copyFiles.
+ * A project with no copyFiles entries gets a task that does nothing. Meant to be run explicitly (its own script,
+ * e.g. `gulp copyFiles`), not folded into the default build - a bundle (or any other file this copies) is often
+ * the live, publicly-reachable version of something, so publishing it elsewhere should be a deliberate step, not
+ * a side effect of every routine local build.
+ *
+ * Reuses copyFor (already shared with copyFonts) rather than a fresh src()/dest() pair - that keeps its existing
+ * encoding: false fix (Gulp 5's default utf8 handling corrupts binary files such as fonts or a minified bundle)
+ * instead of silently losing it in a parallel implementation.
+ *
+ * Each entry runs as its own independent copyFor(), awaited via Promise.all rather than merged into one combined
+ * stream (mergeStream, the pattern bundle.mjs uses) - that pattern assumes every merged stream ends up at the
+ * same shared destination; here, each entry can have a genuinely different one, and merging streams that each
+ * already terminate at their own separate dest() hit a real "write after end" error in practice.
+ * @memberOf module:js-build-tools
+ * @returns {Promise<void>}
+ */
+const copyFiles = () => {
+  const copies = gulpConfig.get('copyFiles', []);
+  if (!copies.length) {
+    return Promise.resolve();
+  }
+  return Promise.all(copies.map(({
+    from,
+    to,
+    base
+  }) => new Promise((resolve, reject) => {
+    (0, _copyFor.copyFor)(from, to, {
+      base
+    }).on('finish', resolve).on('error', reject);
+  }))).then(() => {});
+};
+exports.copyFiles = copyFiles;

package/dist/copyFiles.min.js

@@ -0,0 +1 @@
+"use strict";require("core-js/modules/esnext.weak-map.delete-all.js"),Object.defineProperty(exports,"__esModule",{value:!0}),exports.copyFiles=void 0,require("core-js/modules/esnext.iterator.constructor.js"),require("core-js/modules/esnext.iterator.map.js");var cache,_copyFor=require("./partials/copyFor.js"),gulpConfig=_interopRequireWildcard(require("../gulp.config.js"));function _interopRequireWildcard(e,r){if(!r&&e&&e.__esModule)return e;var o,t,c=Object.defineProperty,s={__proto__:null,default:e};if(Object(e)!==e)return s;if(cache||"function"!=typeof WeakMap||(cache=new WeakMap),cache){if(cache.has(e))return cache.get(e);cache.set(e,s)}for(t in e)"default"!==t&&{}.hasOwnProperty.call(e,t)&&((o=c&&Object.getOwnPropertyDescriptor(e,t))&&(o.get||o.set)?c(s,t,o):s[t]=e[t]);return s}const copyFiles=()=>{const e=gulpConfig.get("copyFiles",[]);return e.length?Promise.all(e.map(({from:e,to:r,base:o})=>new Promise((t,c)=>{(0,_copyFor.copyFor)(e,r,{base:o}).on("finish",t).on("error",c)}))).then(()=>{}):Promise.resolve()};exports.copyFiles=copyFiles;

package/dist/copyFonts.js

@@ -1,18 +1,18 @@
-"use strict";
-
-require("core-js/modules/esnext.weak-map.delete-all.js");
-Object.defineProperty(exports, "__esModule", {
-  value: true
-});
-exports.copyFonts = void 0;
-var _copyFor = require("./partials/copyFor.js");
-var gulpConfig = _interopRequireWildcard(require("../gulp.config.js"));
-var cache;
-function _interopRequireWildcard(e, t) { if (!t && e && e.__esModule) return e; var r, c, a = Object.defineProperty, n = { __proto__: null, default: e }; if (Object(e) !== e) return n; if (cache || "function" != typeof WeakMap || (cache = new WeakMap()), cache) { if (cache.has(e)) return cache.get(e); cache.set(e, n); } for (c in e) "default" !== c && {}.hasOwnProperty.call(e, c) && ((r = a && Object.getOwnPropertyDescriptor(e, c)) && (r.get || r.set) ? a(n, c, r) : n[c] = e[c]); return n; }
+"use strict";
+
+require("core-js/modules/esnext.weak-map.delete-all.js");
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.copyFonts = void 0;
+var _copyFor = require("./partials/copyFor.js");
+var gulpConfig = _interopRequireWildcard(require("../gulp.config.js"));
+var cache;
+function _interopRequireWildcard(e, t) { if (!t && e && e.__esModule) return e; var r, c, a = Object.defineProperty, n = { __proto__: null, default: e }; if (Object(e) !== e) return n; if (cache || "function" != typeof WeakMap || (cache = new WeakMap()), cache) { if (cache.has(e)) return cache.get(e); cache.set(e, n); } for (c in e) "default" !== c && {}.hasOwnProperty.call(e, c) && ((r = a && Object.getOwnPropertyDescriptor(e, c)) && (r.get || r.set) ? a(n, c, r) : n[c] = e[c]); return n; }
 /**
  * Move the font files into the browser directory.
  * @memberOf module:js-build-tools
  * @return {stream.Stream}
- */
-const copyFonts = () => (0, _copyFor.copyFor)(gulpConfig.get('fonts.from'), gulpConfig.get('fonts.to'));
+ */
+const copyFonts = () => (0, _copyFor.copyFor)(gulpConfig.get('fonts.from'), gulpConfig.get('fonts.to'));
 exports.copyFonts = copyFonts;

package/dist/default.js

@@ -1,21 +1,21 @@
-"use strict";
-
-require("core-js/modules/esnext.weak-map.delete-all.js");
-Object.defineProperty(exports, "__esModule", {
-  value: true
-});
-exports.defaultCmd = void 0;
-var _dist = require("./dist.js");
-var _bundle = require("./bundle.js");
-var gulpConfig = _interopRequireWildcard(require("../gulp.config.js"));
-var _gulp = require("gulp");
-var cache;
-function _interopRequireWildcard(e, t) { if (!t && e && e.__esModule) return e; var r, c, a = Object.defineProperty, n = { __proto__: null, default: e }; if (Object(e) !== e) return n; if (cache || "function" != typeof WeakMap || (cache = new WeakMap()), cache) { if (cache.has(e)) return cache.get(e); cache.set(e, n); } for (c in e) "default" !== c && {}.hasOwnProperty.call(e, c) && ((r = a && Object.getOwnPropertyDescriptor(e, c)) && (r.get || r.set) ? a(n, c, r) : n[c] = e[c]); return n; }
+"use strict";
+
+require("core-js/modules/esnext.weak-map.delete-all.js");
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.defaultCmd = void 0;
+var _dist = require("./dist.js");
+var _bundle = require("./bundle.js");
+var gulpConfig = _interopRequireWildcard(require("../gulp.config.js"));
+var _gulp = require("gulp");
+var cache;
+function _interopRequireWildcard(e, t) { if (!t && e && e.__esModule) return e; var r, c, a = Object.defineProperty, n = { __proto__: null, default: e }; if (Object(e) !== e) return n; if (cache || "function" != typeof WeakMap || (cache = new WeakMap()), cache) { if (cache.has(e)) return cache.get(e); cache.set(e, n); } for (c in e) "default" !== c && {}.hasOwnProperty.call(e, c) && ((r = a && Object.getOwnPropertyDescriptor(e, c)) && (r.get || r.set) ? a(n, c, r) : n[c] = e[c]); return n; }
 /**
  * Recommended as the default task, runs the simple dist and bundle tasks.
  * @memberOf module:js-build-tools
  * @param {function} [done=null]
  * @returns {stream.Stream}
- */
-const defaultCmd = (done = null) => gulpConfig.get('browser.enabled') ? (0, _gulp.series)(_dist.dist, _bundle.bundle)(done) : (0, _gulp.series)(_dist.dist)(done);
+ */
+const defaultCmd = (done = null) => gulpConfig.get('browser.enabled') ? (0, _gulp.series)(_dist.dist, _bundle.bundle)(done) : (0, _gulp.series)(_dist.dist)(done);
 exports.defaultCmd = defaultCmd;