quackage 1.0.0

package/.vscode/launch.json

@@ -0,0 +1,18 @@
+{
+    // Use IntelliSense to learn about possible attributes.
+    // Hover to view descriptions of existing attributes.
+    // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
+    "version": "0.2.0",
+    "configurations": [
+        {
+            "type": "node",
+            "request": "launch",
+            "name": "Launch Program",
+            "skipFiles": [
+                "<node_internals>/**"
+            ],
+            "program": "${workspaceFolder}/source/Quackage.js",
+            "args":["build"]
+        }
+    ]
+}

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 Steven Velozo
+
+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,46 @@
+# Quackage
+
+Package.  Test.  Duck.  Name a more iconic trio.
+
+Who doesn't love managing configuration and tooling?  I can tell you who doesn't love it.  I don't love it.
+
+This standardizes:
+
+1. Building an app for a browser
+2. Transpiling an app for ... older browsers
+3. Running unit tests
+
+## Usage
+
+First you need to install the thing.  The easy way is npm or whatever you use to get your packages, which installs the package and puts a couple commands in your node_modules/.bin folder.  You run it either with `quack` or `q` for short.
+
+```shell
+npm install --save-dev quackage
+```
+
+Second, quack like a duck.  
+
+### For instance, you can check your build configurations:
+
+```shell
+npx quack check-build
+```
+
+
+### You can build the app
+
+```shell
+npx quack build
+```
+
+### You can test
+
+```shell
+npx quack test
+```
+
+## If you hate this, you can always inject commands into your `package.json` file:
+
+```shell
+npx quack enhance-my-package
+```

package/debug/.browserslistrc-BACKUP

@@ -0,0 +1 @@
+since 2018

package/debug/Harness.js

@@ -0,0 +1 @@
+console.log('Fancy debug harness here.  Shame if it would get quacked.

package/debug/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "quackage-debug",
+  "version": "1.0.0",
+  "description": "",
+  "main": "Harness.js",
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "keywords": [
+    "Small",
+    "official",
+    "different."
+  ],
+  "author": "steven velozo",
+  "license": "MIT"
+}

package/gulp/Quackage-Gulpfile.js

@@ -0,0 +1,140 @@
+'use strict';
+
+/*
+  After hours of reading and trying various ways of using gulp-env, environment variables
+  and babel browesrslistrc / package.json environments it is clear that the state of using
+  these tools is a mess.  There are ways of getting it to work but none of them feel like
+  they will work well in the long term (all of the examples seem to be in bands of about
+  a year or two of working before the pattern changes entirely).
+
+  WHY did we need such a crazy compatible version?  wkhtmltopdf is why.  It uses a very
+  old incompatible version of the QT browser.
+
+  Therefore, we will use a very old and simple method.
+
+	1) There is a config file (gulpfile-config.json), documented here, describing the inputs and outputs for the build operation.
+
+		const _CONFIG = (
+			{
+				// The input source file that should be passed to browserify:
+				// (if you need to auto-instantiate an object, for instance)
+				EntrypointInputSourceFile: `${__dirname}/source/Fable-Browser-Shim.js`,
+
+				// The name of the packaged object to be passed to browserify:
+				// (browserify sets this to global scope and window.SOMEOBJECTNAMEHERE where SOMEOBJECTNAMEHERE is the string below)
+				LibraryObjectName: `Fable`,
+
+				// The folder to write the library files and maps out to:
+				LibraryOutputFolder: `${__dirname}/dist/`,
+
+				// The name of the unminified version of the packaged library, for easy debugging:
+				LibraryUniminifiedFileName: `fable.js`,
+
+				// The name of the minified version of the packaged library, for production release:
+				LibraryMinifiedFileName: `fable.min.js`
+			});
+
+	2) We are using a .browserslistrc file... this is what tells gulp-babel, through the
+	   magic of the @babel/preset-env library, how to transpile the library into a compatible
+	   enough format for our targets.
+
+	   For example as of writing this, there are two targets we want:
+
+			*	Modern browsers in the last five years, expressed as a .browserslistrc with the string "since 2018"
+			*	Very old janky browsers expressed as a .browserslistrc with the string "> 0.01%"
+				... which is interpreted as anything more than 0.01% of browsers in existence or something like that
+
+	3) Because we want multiple outputs, and, the tools do fine if we want one output but some of
+	   the toolchain doesn't like making different targets well, we're just going to have multiple
+	   configurations and .browserslistrc files.  So if our spec above says we need a ".browserslistrc"
+	   file and a "gulpfile-config.json", we're going to make the following two sets of configuration:
+
+			*	.browserslistrc_default, .gulpfile-config_default.json
+			*	.browserslistrc_compatible, .gulpfile-config_compatible.json
+
+	4) We will copy, synchronously, these files to where the rest of our toolchain expects
+	   them, before we begin the build.  This will be done by looking at the GULP_CUSTOM_BUILD_TARGET
+	   environment variable.  This allows us to create new targets to experiment by copying a couple files,
+	   jimmying the settings and setting an environment variable before running the pipeline.
+
+	5) We will run the toolchain and it will happily think it's just doing a single build and kinda work.
+
+ */
+
+// ---> Now load the config and get on with building <--- \\
+console.log(``);
+console.log(`---> Loading the gulp config...`);
+const _CONFIG = require(`${process.cwd()}/.gulpfile-quackage-config.json`);
+console.log(`   > Building to [${_CONFIG.LibraryUniminifiedFileName}] and [${_CONFIG.LibraryMinifiedFileName}]`)
+
+// --->  Boilerplate Browser Uglification and Packaging  <--- \\
+console.log(``);
+console.log(`--> Gulp is taking over!`);
+
+const libBrowserify = require('browserify');
+const libGulp = require('gulp');
+
+const libVinylSourceStream = require('vinyl-source-stream');
+const libVinylBuffer = require('vinyl-buffer');
+
+const libSourcemaps = require('gulp-sourcemaps');
+const libGulpUtil = require('gulp-util');
+const libBabel = require('gulp-babel');
+const libTerser = require('gulp-terser');
+
+// Build the module for the browser
+libGulp.task('minified',
+() => {
+	// set up the custom browserify instance for this task
+	var tmpBrowserify = libBrowserify(
+	{
+		entries: _CONFIG.EntrypointInputSourceFile,
+		standalone: _CONFIG.LibraryObjectName,
+		debug: true
+	});
+
+	return tmpBrowserify.bundle()
+		.pipe(libVinylSourceStream(_CONFIG.LibraryMinifiedFileName))
+		.pipe(libVinylBuffer())
+		.pipe(libSourcemaps.init({loadMaps: true}))
+				// Oddly, having a .babelrc with this same thing behaves differently, and is the behavior we want
+				//.pipe(libBabel({"presets": ["@babel/preset-env"]}))
+				.pipe(libBabel())
+				.pipe(libTerser())
+				.on('error', libGulpUtil.log)
+		.pipe(libSourcemaps.write('./'))
+		.pipe(libGulp.dest(_CONFIG.LibraryOutputFolder));
+});
+
+// Build the module for the browser
+libGulp.task('debug',
+	() => {
+		// set up the custom browserify instance for this task
+		var tmpBrowserify = libBrowserify(
+		{
+			entries: _CONFIG.EntrypointInputSourceFile,
+			standalone: _CONFIG.LibraryObjectName,
+			debug: true
+		});
+
+		return tmpBrowserify.bundle()
+			.pipe(libVinylSourceStream(_CONFIG.LibraryUniminifiedFileName))
+			.pipe(libVinylBuffer())
+					// Oddly, having a .babelrc with this same thing behaves differently, and is the behavior we want
+					//.pipe(libBabel({"presets": ["@babel/preset-env"]}))
+					.pipe(libBabel())
+					.on('error', libGulpUtil.log)
+			.pipe(libGulp.dest(_CONFIG.LibraryOutputFolder));
+	});
+
+libGulp.task
+(
+	'build',
+	libGulp.series('debug', 'minified')
+);
+
+libGulp.task
+(
+	'default',
+	libGulp.series('debug', 'minified')
+);

package/package.json

@@ -0,0 +1,69 @@
+{
+  "name": "quackage",
+  "version": "1.0.0",
+  "description": "Building.  Testing.  Quacking.",
+  "main": "source/Quackage.js",
+  "scripts": {
+    "start": "node source/Quackage.js",
+    "coverage": "./node_modules/.bin/nyc --reporter=lcov --reporter=text-lcov ./node_modules/mocha/bin/_mocha -- -u tdd -R spec",
+    "test": "./node_modules/.bin/mocha -u tdd -R spec",
+    "build": "./node_modules/.bin/gulp build",
+    "build-compatible": "GULP_CUSTOM_BUILD_TARGET=compatible ./node_modules/.bin/gulp build"
+  },
+  "mocha": {
+    "diff": true,
+    "extension": [
+      "js"
+    ],
+    "package": "./package.json",
+    "reporter": "spec",
+    "slow": "75",
+    "timeout": "5000",
+    "ui": "tdd",
+    "watch-files": [
+      "source/**/*.js",
+      "test/**/*.js"
+    ],
+    "watch-ignore": [
+      "lib/vendor"
+    ]
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/stevenvelozo/quackage.git"
+  },
+  "browser": {
+    "./source/utility/Quackage-Execute-Process.js": "./source/utility/Quackage-Execute-Process-Base.js"
+  },
+
+  "keywords": [
+    "entity",
+    "behavior"
+  ],
+  "author": "Steven Velozo <steven@velozo.com> (http://velozo.com/)",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/stevenvelozo/quackage/issues"
+  },
+  "homepage": "https://github.com/stevenvelozo/quackage",
+  "dependencies": {
+    "@babel/core": "^7.22.1",
+    "@babel/preset-env": "^7.22.2",
+    "browserify": "^17.0.0",
+    "chai": "4.3.7",
+    "commander": "^10.0.1",
+    "gulp": "^4.0.2",
+    "gulp-babel": "^8.0.0",
+    "gulp-env": "^0.4.0",
+    "gulp-sourcemaps": "^3.0.0",
+    "gulp-terser": "^2.1.0",
+    "gulp-util": "^3.0.8",
+    "mocha": "10.2.0",
+    "npm-check-updates": "^16.10.12",
+    "nyc": "^15.1.0",
+    "pict": "^1.0.55",
+    "retold-data-service": "^1.0.3",
+    "vinyl-buffer": "^1.0.1",
+    "vinyl-source-stream": "^2.0.0"
+  }
+}

package/source/Default-Quackage-Configuration.json

@@ -0,0 +1,30 @@
+{
+	"QuackageBaseGulpfile": "require('{~Data:AppData.QuackageFolder~}/gulp/Quackage-Gulpfile.js');",
+	"GulpfileConfiguration": 
+	{
+		"EntrypointInputSourceFile": "{~Data:AppData.CWD~}/{~Data:AppData.Package.main~}",
+		"LibraryObjectName": "{~Data:AppData.Package.name~}",
+		"LibraryOutputFolder": "{~Data:AppData.CWD~}/dist/",
+		"LibraryUniminifiedFileName": "{~Data:AppData.Package.name~}.{~Data:Record.BuildFileLabel~}js",
+		"LibraryMinifiedFileName": "{~Data:AppData.Package.name~}.{~Data:Record.BuildFileLabel~}min.js"
+	},
+	"DefaultBabelRC":
+	{
+		"presets": ["@babel/preset-env"]
+	},
+	"GulpExecutions":
+	[
+		{
+			"Hash": "default",
+			"Name": "Default standard build.",
+			"BuildFileLabel": "",
+			"BrowsersListRC": "since 2018"
+		},
+		{
+			"Hash": "compatible",
+			"Name": "Default standard build.",
+			"BuildFileLabel": "compatible.",
+			"BrowsersListRC": "> 0.01%"
+		}
+	]
+}

package/source/Quackage.js

@@ -0,0 +1,129 @@
+const libFS = require('fs');
+const libPict = require('pict');
+const libCommander = require('commander').Command;
+
+const _QuackagePackage = require('../package.json');
+const _QuackageDefaultConfiguration = require('./Default-Quackage-Configuration.json');
+
+let _Pict = new libPict(
+    {
+        Product: 'Quackage',
+        ProductVersion: '1.0.0'
+    }
+);
+_Pict.serviceManager.addAndInstantiateServiceType('QuackageProcess', require('./utility/Quackage-Execute-Process.js'));
+
+// Grab the current working directory for the quackage
+_Pict.AppData.CWD = _Pict.QuackageProcess.cwd();
+_Pict.AppData.QuackageFolder = _Pict.QuackageProcess.quackageFolder();
+
+// Check that a package.json is in the folder we are quacking from
+try
+{
+    _Pict.AppData.Package = require(`${_Pict.AppData.CWD}/package.json`);
+}
+catch (pError)
+{
+    _Pict.log.error(`No package.json found in [${_Pict.AppData.CWD}].  Please run quackage from a folder with a package.json file.`);
+    _Pict.log.info(`Quack a nice day!`)
+    _Pict.QuackageProcess.exitParentProcess(1);
+}
+finally
+{
+    // Check for a quackage.json file
+    try
+    {
+        _Pict.AppData.QuackagePackage = require(`${_Pict.AppData.CWD}/.quackage.json`);
+        _Pict.AppData.QuackagePackage = _Pict.Utility.extend(_QuackageDefaultConfiguration, _Pict.AppData.QuackagePackage);
+    }
+    catch (pError)
+    {
+        _Pict.log.warn(`No quackage.json found in [${_Pict.AppData.CWD}].  Using default configuration.`);
+        _Pict.AppData.QuackagePackage = _QuackageDefaultConfiguration;
+    }
+
+    // Use the Commander library to deal with CLI parameters
+    _Pict.Command = new libCommander();
+
+    _Pict.Command.name('quackage')
+        .description('CLI testing and building meant to be run from a folder with a package.json and customized with a quackage.json')
+        .version(_QuackagePackage.version);
+
+    _Pict.Command.command('build')
+        .description('Build your npm module into a dist folder')
+        .argument('[config]', 'optional hash of the configuration you want to run -- otherwise all are built', "ALL")
+        //.option('-s, --separator <char>', 'separator character', ',')
+        .action((pString, pOptions) =>
+        {
+            let tmpActionsToExecute = pString.toUpperCase();
+            let tmpActionSet = [];
+
+            _Pict.log.info(`Building your module to ${pString} from the command...`,pOptions);
+
+            // ##. Load the gulp config and code template files into our pict
+            _Pict.TemplateProvider.addTemplate('Gulpfile-Configuration', JSON.stringify(_Pict.AppData.QuackagePackage.GulpfileConfiguration,null,4));
+            _Pict.TemplateProvider.addTemplate('Gulpfile-QuackageBase', _Pict.AppData.QuackagePackage.QuackageBaseGulpfile);
+
+            // ##. Figure out which actions to execute
+            for (let i = 0; i < _Pict.AppData.QuackagePackage.GulpExecutions.length; i++)
+            {
+                if (tmpActionsToExecute == 'ALL' || tmpActionsToExecute.includes(_Pict.AppData.QuackagePackage.GulpExecutions[i].Name.toUpperCase()))
+                {
+                    tmpActionSet.push(_Pict.AppData.QuackagePackage.GulpExecutions[i]);
+                }
+            }
+
+            if (tmpActionSet.length < 1)
+            {
+                _Pict.log.error(`No actions to execute for the configuration hash [${pString}]`);
+                return false;
+            }
+
+            // ##. Enumerate the actions, executing each one, in series asynchronously
+            _Pict.Utility.eachLimit(
+                tmpActionSet, 1,
+                (pAction, fActionCallback) =>
+                {
+                    _Pict.log.info(`Executing action [${pAction.Name}]...`);
+
+                    // ## .browserslistrc
+                    if (pAction.hasOwnProperty('BrowsersListRC'))
+                    {
+                        // ## Backup the .browserslistrc file if it existst
+                        if (libFS.existsSync(`${_Pict.AppData.CWD}/.browserslistrc`))
+                        {
+                            libFS.copyFileSync(`${_Pict.AppData.CWD}/.browserslistrc`, `${_Pict.AppData.CWD}/.browserslistrc-BACKUP`);
+                            _Pict.log.info(`Contents of existing .browserslistrc backed up to .browserslistrc-BACKUP and output below:`, {FileContents:libFS.readFileSync(`${_Pict.AppData.CWD}/.browserslistrc`).toString()});
+                        }
+
+                        // ## Write out the browserslistrc
+                        libFS.writeFileSync(`${_Pict.AppData.CWD}/.browserslistrc`, pAction.BrowsersListRC);
+                    }
+
+                    // ## .babelrc
+                    if (_Pict.AppData.QuackagePackage.DefaultBabelRC)
+                    {
+                        if (libFS.existsSync(`${_Pict.AppData.CWD}/.babelrc`))
+                        {
+                            _Pict.log.info(`Leaving the existing .babelrc file in place.  Please make sure it is compatible with the build you are trying to make.`);
+                        }
+                        else
+                        {
+                            libFS.writeFileSync(`${_Pict.AppData.CWD}/.babelrc`, JSON.stringify(_Pict.AppData.QuackagePackage.DefaultBabelRC,null,4));
+                        }
+                    }
+
+                    // ## gulpfile-quackage-config.json
+                    libFS.writeFileSync(`${_Pict.AppData.CWD}/.gulpfile-quackage-config.json`, _Pict.parseTemplateByHash('Gulpfile-Configuration', pAction));
+                    // ## gulpfile-quackage.js
+                    libFS.writeFileSync(`${_Pict.AppData.CWD}/.gulpfile-quackage.js`, _Pict.parseTemplateByHash('Gulpfile-QuackageBase', {AppData:_Pict.AppData, Record:pAction}));
+
+                    // Now execute the gulpfile using our custom service provider!
+                    _Pict.QuackageProcess.execute(`./node_modules/.bin/gulp`, [`--gulpfile`, `${_Pict.AppData.CWD}/.gulpfile-quackage.js`], {cwd:_Pict.AppData.CWD}, fActionCallback);
+                });
+            });
+
+    _Pict.Command.parse();
+}
+
+module.exports = _Pict;

package/source/utility/Quackage-Execute-Process-Base.js

@@ -0,0 +1,38 @@
+const libPict = require('pict');
+
+class BaseQuackageProcessExecutionService extends libPict.ServiceProviderBase
+{
+	constructor(pFable, pManifest, pServiceHash)
+	{
+		super(pFable, pManifest, pServiceHash);
+
+        this.serviceType = 'QuackageProcess';
+    }
+
+    cwd()
+    {
+        return `ABSTRACT_CWD`;
+    }
+
+
+    quackageFolder()
+    {
+        return `ABSTRACT_QUACKAGE_FOLDER`;
+    }
+
+    exitParentProcess(pCode)
+    {
+        return 'ABSTRACT_EXIT_PARENT_PROCESS';
+    }
+
+	execute(pProcess, pArguments, pOptions, fCallback)
+    {
+        // Now log out what our execution would be!
+        this.log.info(`Executing process: ${pProcess}`);
+        this.log.trace(`Full command:  ${pProcess} ${pArguments.join(' ')}`, pOptions);
+
+        return fCallback();
+    }
+}
+
+module.exports = BaseQuackageProcessExecutionService;

package/source/utility/Quackage-Execute-Process.js

@@ -0,0 +1,64 @@
+const libQuackageExecuteProcessBase = require(`./Quackage-Execute-Process-Base.js`);
+const libChildProcess = require('child_process');
+
+class BaseQuackageProcessExecutionService extends libQuackageExecuteProcessBase
+{
+	constructor(pFable, pManifest, pServiceHash)
+	{
+		super(pFable, pManifest, pServiceHash);
+
+        this.serviceType = 'QuackageProcess';
+    }
+
+    cwd()
+    {
+        return process.cwd();
+    }
+
+    quackageFolder()
+    {
+        return `${__dirname}/../..`;
+    }
+
+    exitParentProcess(pCode)
+    {
+        process.exit(pCode);
+    }
+
+    execute(pProcess, pArguments, pOptions, fCallback)
+    {
+        // Now log out what our execution would be!
+        this.log.info(`Executing process: ${pProcess}`);
+        this.log.trace(`Full command:  ${pProcess} ${pArguments.join(' ')}`, pOptions);
+
+        // Now execute the gulpfile!
+        const tmpProcess = libChildProcess.spawn(pProcess, pArguments, pOptions);
+
+        tmpProcess.stdout.on('data',
+            (pConsoleOutput) =>
+            {
+                this.log.trace(pConsoleOutput);
+            });
+        tmpProcess.stderr.on('data',
+            (pConsoleOutput) =>
+            {
+                this.log.error(pConsoleOutput);
+            });
+
+        tmpProcess.stderr.on('error',
+            (pError) =>
+            {
+                this.log.error(`Process execution failed in your quackage manager!  Error: ${pError.message}`);
+                return fCallback(pError);
+            });
+
+        tmpProcess.stderr.on('close',
+            (pError) =>
+            {
+                this.log.info(`Process completed successfully, with a quack!`);
+                return fCallback(pError);
+            });
+    }
+}
+
+module.exports = BaseQuackageProcessExecutionService;

package/test/Quackage_tests.js

@@ -0,0 +1,38 @@
+/**
+* Unit tests for Quackage
+*
+* @license     MIT
+*
+* @author      Steven Velozo <steven@velozo.com>
+*/
+
+var libQuackage = require('../source/Quackage.js');
+
+var Chai = require("chai");
+var Expect = Chai.expect;
+
+suite
+(
+	'Quackage',
+	function()
+	{
+		setup ( () => {} );
+
+		suite
+		(
+			'Execution Sanity',
+			function()
+			{
+				test
+				(
+					'Quackage should load up okay.',
+					function()
+					{
+						let testQuackage = new libQuackage();
+						Expect(testQuackage.settings.Product).to.equal('ApplicationNameHere')
+					}
+				);
+			}
+		);
+	}
+);