copy-folder-util 0.2.0

package/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2022 Individual contributors to copy-folder-util
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,92 @@
+# copy-folder-util
+<img src=https://centerkey.com/graphics/center-key-logo.svg align=right width=200 alt=logo>
+
+_Recursively copy a folder (CLI tool designed for use in npm scripts)_
+
+[![License:MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://github.com/center-key/copy-folder-util/blob/main/LICENSE.txt)
+[![npm](https://img.shields.io/npm/v/copy-folder-util.svg)](https://www.npmjs.com/package/copy-folder-util)
+[![Vulnerabilities](https://snyk.io/test/github/center-key/copy-folder-util/badge.svg)](https://snyk.io/test/github/center-key/copy-folder-util)
+[![Build](https://github.com/center-key/copy-folder-util/workflows/build/badge.svg)](https://github.com/center-key/copy-folder-util/actions/workflows/run-spec-on-push.yaml)
+
+**copy-folder-util** takes a source folder and copies its files and subfolders to a new destination.&nbsp;
+The command's console output includes a timestamp and formatting helpful in build systems.
+
+<img src=https://raw.githubusercontent.com/center-key/copy-folder-util/main/screenshot.png
+width=800 alt=screenshot>
+
+## A) Setup
+Install package for node:
+```shell
+$ npm install --save-dev copy-folder-util
+```
+
+## B) Usage
+### 1. npm scripts
+Run `copy-folder` from the `"scripts"` section of your **package.json** file.
+
+Parameters:
+* The **first** parameter is the *source* folder.
+* The **second** parameter is the *target* folder.
+
+Example **package.json** scripts:
+```json
+   "scripts": {
+      "make-dist": "copy-folder build dist",
+      "make-docs": "copy-folder src/web --ext=.html docs/api-manual"
+   },
+```
+Try out the first script with the command: `npm run make-dist`
+
+### 2. Global
+You can install **copy-folder-util** globally and then run it anywhere directly from the terminal.
+
+Example terminal commands:
+```shell
+$ npm install --global copy-folder-util
+$ copy-folder src/web ext=.html docs/api-manual
+```
+
+### 3. CLI Flags
+Command-line flags:
+| Flag         | Description                                           | Value      |
+| ------------ | ----------------------------------------------------- | ---------- |
+| `--basename` | Filter files by filename ignoring the file extension. | **string** |
+| `--cd`       | Change working directory before starting copy.        | **string** |
+| `--ext`      | Filter files by file extension, such as `.js`.<br>Use a comma to specify multiple extensions. | **string** |
+| `--quiet`    | Suppress informational messages.                      | N/A        |
+| `--summary`  | Only print out the single line summary message.       | N/A        |
+
+Examples:
+   - `copy-folder build --basename=index dist`  &nbsp; Only copy files with filenames matching `index.*`.
+   - `copy-folder -cd=spec fixtures mock1`      &nbsp; Copy the folder **spec/fixtures** to **spec/mock1**.
+   - `copy-folder build dist --summary`         &nbsp; Displays the summary but not the individual files copied.
+   - `copy-folder src/web --ext=.js,.html docs` &nbsp; Copy only the JavaScript and HTML files to the **docs** folder.
+
+## C) Application Code
+Even though **copy-folder-util** is primarily intended for build scripts, the package can easily be used programmatically in ESM and TypeScript projects.
+
+Example:
+``` typescript
+import { copyFolder } from 'copy-folder-util';
+const options = { fileExtensions: ['.html', '.js'] };
+const results = copyFolder.cp('src/web', 'docs/api-manual', options);
+console.log('Number of files copied:', results.count);
+```
+
+See the **TypeScript Declarations** at the top of [copy-folder.ts](copy-folder.ts) for documentation.
+
+<br>
+
+---
+**CLI Build Tools**
+   - 🎋 [add-dist-header](https://github.com/center-key/add-dist-header):&nbsp; _Prepend a one-line banner comment (with license notice) to distribution files_
+   - 📄 [copy-file-util](https://github.com/center-key/copy-file-util):&nbsp; _Copy or rename a file_
+   - 📂 [copy-folder-util](https://github.com/center-key/copy-folder-util):&nbsp; _Recursively copy the files in a folder_
+   - 🔍 [replacer-util](https://github.com/center-key/replacer-util):&nbsp; _Find and replace strings or template outputs in text files_
+   - 🔢 [rev-web-assets](https://github.com/center-key/rev-web-assets):&nbsp; _Revision web asset filenames with cache busting content hash fingerprints_
+   - 🚦 [w3c-html-validator](https://github.com/center-key/w3c-html-validator):&nbsp; _Check the markup validity of HTML files using the W3C validator_
+
+Feel free to submit questions at:<br>
+[github.com/center-key/copy-folder-util/issues](https://github.com/center-key/copy-folder-util/issues)
+
+[MIT License](LICENSE.txt)

package/bin/cli.js

@@ -0,0 +1,70 @@
+#!/usr/bin/env node
+//////////////////////
+// copy-folder-util //
+// MIT License      //
+//////////////////////
+
+// Usage in package.json:
+//    "scripts": {
+//       "make-dist": "copy-folder build dist"
+//    },
+//
+// Usage from command line:
+//    $ npm install --global copy-folder-util
+//    $ copy-folder build dist
+//    $ copy-folder src/web --ext=.js,.html docs
+//
+// Contributors to this project:
+//    $ cd copy-folder-util
+//    $ npm install
+//    $ npm test
+//    $ node bin/cli.js --cd=spec/fixtures source --ext=.js target/ext-js
+
+// Imports
+import { copyFolder } from '../dist/copy-folder.js';
+import chalk from 'chalk';
+import log   from 'fancy-log';
+
+// Parameters
+const validFlags =  ['cd', 'ext', 'quiet', 'summary'];
+const args =        process.argv.slice(2);
+const flags =       args.filter(arg => /^--/.test(arg));
+const flagMap =     Object.fromEntries(flags.map(flag => flag.replace(/^--/, '').split('=')));
+const flagOn =      Object.fromEntries(validFlags.map(flag => [flag, flag in flagMap]));
+const invalidFlag = Object.keys(flagMap).find(key => !validFlags.includes(key));
+const params =      args.filter(arg => !/^--/.test(arg));
+
+// Data
+const source = params[0];
+const target = params[1];
+
+// Reporting
+const printReport = (results) => {
+   const name =      chalk.gray('copy-folder');
+   const source =    chalk.blue.bold(results.source);
+   const target =    chalk.magenta(results.target);
+   const arrow =     { big: chalk.gray.bold('➤➤➤'), little: chalk.gray.bold(' ⟹  ') };  //extra space for alignment
+   const infoColor = results.count ? chalk.white : chalk.red.bold;
+   const info =      infoColor(`(files: ${results.count}, ${results.duration}ms)`);
+   const logFile =   (file) => log(name, chalk.white(file.origin), arrow.little, chalk.green(file.dest));
+   log(name, source, arrow.big, target, info);
+   if (!flagOn.summary)
+      results.files.forEach(logFile);
+   };
+
+// Copy Folder
+const error =
+   invalidFlag ?       'Invalid flag: ' + invalidFlag :
+   !source ?           'Missing source folder.' :
+   !target ?           'Missing target folder.' :
+   params.length > 2 ? 'Extraneous parameter: ' + params[2] :
+   null;
+if (error)
+   throw Error('[copy-folder-util] ' + error);
+const options = {
+   cd:             flagMap.cd ?? null,
+   fileExtensions: flagMap.ext?.split(',') ?? [],
+   };
+const results = copyFolder.cp(source, target, options);
+if (!flagOn.quiet)
+   printReport(results);

package/dist/copy-folder.d.ts

@@ -0,0 +1,22 @@
+//! copy-folder-util v0.2.0 ~~ https://github.com/center-key/copy-folder-util ~~ MIT License
+
+export declare type Settings = {
+    basename: string;
+    cd: string;
+    fileExtensions: string[];
+};
+export declare type Options = Partial<Settings>;
+export declare type Results = {
+    source: string;
+    target: string;
+    count: number;
+    duration: number;
+    files: {
+        origin: string;
+        dest: string;
+    }[];
+};
+declare const copyFolder: {
+    cp(sourceFolder: string, targetFolder: string, options?: Options): Results;
+};
+export { copyFolder };

package/dist/copy-folder.js

@@ -0,0 +1,63 @@
+//! copy-folder-util v0.2.0 ~~ https://github.com/center-key/copy-folder-util ~~ MIT License
+
+import fs from 'fs';
+import path from 'path';
+import slash from 'slash';
+const extraneousFiles = ['.DS_Store', 'Thumbs.db', 'desktop.ini'];
+const extraneousFolders = ['.git', 'node_modules'];
+const copyFolder = {
+    cp(sourceFolder, targetFolder, options) {
+        const defaults = {
+            basename: null,
+            cd: null,
+            fileExtensions: [],
+        };
+        const settings = Object.assign(Object.assign({}, defaults), options);
+        const startTime = Date.now();
+        const normalize = (folder) => !folder ? '' : slash(path.normalize(folder)).replace(/\/$/, '');
+        const startFolder = settings.cd ? normalize(settings.cd) + '/' : '';
+        const source = normalize(startFolder + sourceFolder);
+        const target = normalize(startFolder + targetFolder);
+        if (targetFolder)
+            fs.mkdirSync(target, { recursive: true });
+        const errorMessage = !sourceFolder ? 'Must specify the source folder path.' :
+            !targetFolder ? 'Must specify the target folder path.' :
+                !fs.existsSync(source) ? 'Source folder does not exist: ' + source :
+                    !fs.existsSync(target) ? 'Target folder cannot be created: ' + target :
+                        !fs.statSync(source).isDirectory() ? 'Source is not a folder: ' + source :
+                            !fs.statSync(target).isDirectory() ? 'Target is not a folder: ' + target :
+                                null;
+        if (errorMessage)
+            throw Error('[copy-folder-util] ' + errorMessage);
+        const filterOff = {
+            base: !settings.basename,
+            ext: !settings.fileExtensions || settings.fileExtensions.length === 0,
+        };
+        const files = [];
+        const filter = (origin, dest) => {
+            const isFile = fs.statSync(origin).isFile();
+            const name = path.basename(origin);
+            const ext = path.extname(origin);
+            const keepFolder = !isFile && !extraneousFolders.includes(name);
+            const keepFile = isFile &&
+                (filterOff.base || name.replace(/[.].*/, '') === settings.basename) &&
+                (filterOff.ext || settings.fileExtensions.includes(ext)) &&
+                !extraneousFiles.includes(name);
+            if (keepFile)
+                files.push({
+                    origin: origin.substring(source.length + 1),
+                    dest: dest.substring(target.length + 1),
+                });
+            return keepFolder || keepFile;
+        };
+        fs.cpSync(source, target, { filter: filter, recursive: true });
+        return {
+            source: source,
+            target: target,
+            count: files.length,
+            duration: Date.now() - startTime,
+            files: files,
+        };
+    },
+};
+export { copyFolder };

package/dist/copy-folder.umd.cjs

@@ -0,0 +1,79 @@
+//! copy-folder-util v0.2.0 ~~ https://github.com/center-key/copy-folder-util ~~ MIT License
+
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+(function (factory) {
+    if (typeof module === "object" && typeof module.exports === "object") {
+        var v = factory(require, exports);
+        if (v !== undefined) module.exports = v;
+    }
+    else if (typeof define === "function" && define.amd) {
+        define(["require", "exports", "fs", "path", "slash"], factory);
+    }
+})(function (require, exports) {
+    "use strict";
+    Object.defineProperty(exports, "__esModule", { value: true });
+    exports.copyFolder = void 0;
+    const fs_1 = __importDefault(require("fs"));
+    const path_1 = __importDefault(require("path"));
+    const slash_1 = __importDefault(require("slash"));
+    const extraneousFiles = ['.DS_Store', 'Thumbs.db', 'desktop.ini'];
+    const extraneousFolders = ['.git', 'node_modules'];
+    const copyFolder = {
+        cp(sourceFolder, targetFolder, options) {
+            const defaults = {
+                basename: null,
+                cd: null,
+                fileExtensions: [],
+            };
+            const settings = Object.assign(Object.assign({}, defaults), options);
+            const startTime = Date.now();
+            const normalize = (folder) => !folder ? '' : (0, slash_1.default)(path_1.default.normalize(folder)).replace(/\/$/, '');
+            const startFolder = settings.cd ? normalize(settings.cd) + '/' : '';
+            const source = normalize(startFolder + sourceFolder);
+            const target = normalize(startFolder + targetFolder);
+            if (targetFolder)
+                fs_1.default.mkdirSync(target, { recursive: true });
+            const errorMessage = !sourceFolder ? 'Must specify the source folder path.' :
+                !targetFolder ? 'Must specify the target folder path.' :
+                    !fs_1.default.existsSync(source) ? 'Source folder does not exist: ' + source :
+                        !fs_1.default.existsSync(target) ? 'Target folder cannot be created: ' + target :
+                            !fs_1.default.statSync(source).isDirectory() ? 'Source is not a folder: ' + source :
+                                !fs_1.default.statSync(target).isDirectory() ? 'Target is not a folder: ' + target :
+                                    null;
+            if (errorMessage)
+                throw Error('[copy-folder-util] ' + errorMessage);
+            const filterOff = {
+                base: !settings.basename,
+                ext: !settings.fileExtensions || settings.fileExtensions.length === 0,
+            };
+            const files = [];
+            const filter = (origin, dest) => {
+                const isFile = fs_1.default.statSync(origin).isFile();
+                const name = path_1.default.basename(origin);
+                const ext = path_1.default.extname(origin);
+                const keepFolder = !isFile && !extraneousFolders.includes(name);
+                const keepFile = isFile &&
+                    (filterOff.base || name.replace(/[.].*/, '') === settings.basename) &&
+                    (filterOff.ext || settings.fileExtensions.includes(ext)) &&
+                    !extraneousFiles.includes(name);
+                if (keepFile)
+                    files.push({
+                        origin: origin.substring(source.length + 1),
+                        dest: dest.substring(target.length + 1),
+                    });
+                return keepFolder || keepFile;
+            };
+            fs_1.default.cpSync(source, target, { filter: filter, recursive: true });
+            return {
+                source: source,
+                target: target,
+                count: files.length,
+                duration: Date.now() - startTime,
+                files: files,
+            };
+        },
+    };
+    exports.copyFolder = copyFolder;
+});

package/package.json

@@ -0,0 +1,101 @@
+{
+   "name": "copy-folder-util",
+   "version": "0.2.0",
+   "description": "Recursively copy a folder (CLI tool designed for use in npm scripts)",
+   "license": "MIT",
+   "type": "module",
+   "module": "dist/copy-folder.js",
+   "main": "dist/copy-folder.umd.cjs",
+   "types": "dist/copy-folder.d.ts",
+   "files": [
+      "dist"
+   ],
+   "exports": {
+      ".": {
+         "import": "./dist/copy-folder.js",
+         "require": "./dist/copy-folder.umd.cjs"
+      },
+      "./": "./dist/"
+   },
+   "bin": {
+      "copy-folder": "bin/cli.js",
+      "copy-folder-util": "bin/cli.js"
+   },
+   "repository": "github:center-key/copy-folder-util",
+   "homepage": "https://github.com/center-key/copy-folder-util",
+   "bugs": "https://github.com/center-key/copy-folder-util/issues",
+   "docs": "https://github.com/center-key/copy-folder-util#readme",
+   "author": "Center Key (https://centerkey.com)",
+   "keywords": [
+      "cli",
+      "copy",
+      "cp",
+      "dir",
+      "directory",
+      "files",
+      "folder",
+      "recursive",
+      "scripts"
+   ],
+   "jshintConfig": {
+      "esversion": 11,
+      "strict": "implied",
+      "eqeqeq": true,
+      "undef": true,
+      "unused": true,
+      "varstmt": true,
+      "node": true,
+      "mocha": true
+   },
+   "eslintConfig": {
+      "ignorePatterns": [
+         "build",
+         "dist",
+         "node_modules"
+      ],
+      "root": true,
+      "parser": "@typescript-eslint/parser",
+      "plugins": [
+         "@typescript-eslint"
+      ],
+      "extends": [
+         "eslint:recommended",
+         "plugin:@typescript-eslint/recommended"
+      ],
+      "rules": {
+         "@typescript-eslint/no-non-null-assertion": "off"
+      }
+   },
+   "scripts": {
+      "step:01": "rimraf build dist spec/fixtures/target **/.DS_Store",
+      "step:02": "jshint . --exclude-path .gitignore",
+      "step:03": "eslint --max-warnings 0 . --ext .ts",
+      "step:04": "tsc",
+      "step:05": "tsc --module UMD --outDir build/umd",
+      "step:06": "copy-file build/umd/copy-folder.js build/copy-folder.umd.cjs",
+      "step:07": "add-dist-header build dist",
+      "pretest": "npm-run-all step:*",
+      "test": "mocha spec/*.spec.js"
+   },
+   "dependencies": {
+      "chalk": "~5.1",
+      "fancy-log": "~2.0",
+      "slash": "~5.0"
+   },
+   "devDependencies": {
+      "@types/fancy-log": "~2.0",
+      "@types/node": "~18.8",
+      "@typescript-eslint/eslint-plugin": "~5.40",
+      "@typescript-eslint/parser": "~5.40",
+      "add-dist-header": "~0.3",
+      "assert-deep-strict-equal": "~1.0",
+      "copy-file-util": "~0.1",
+      "eslint": "~8.25",
+      "jshint": "~2.13",
+      "mocha": "~10.0",
+      "npm-run-all2": "~6.0",
+      "rev-web-assets": "~0.1",
+      "rimraf": "~3.0",
+      "typescript": "~4.8"
+   }
+}