feat: initial makeGasket with actions (#720)

* feat: initial makeGasket with actions

* docs: cleanup copy/pasta

* feat: more work on makeGasket with actions

* feat: adjust plugin action types

* test: changes to engine plugins config

* test: changes to engine plugins config

* test: changes to next config handling

* test: changes to engine plugins config

* test: changes to engine plugins config

* feat: adjust engine args again

* test: adjust engine args

* test: adjusting types

* fix: force tsc check

* fix: lockfile

* docs: updated engine readme

* docs: gasket core

* docs: todos

* docs: note about plugins

* docs: todos

* chore: add typecheck

packages/create-gasket-app/lib/scaffold/create-engine.js

@@ -1,5 +1,5 @@
 const path = require('path');
-const PluginEngine = require('@gasket/engine');
+const GasketEngine = require('@gasket/engine');
 const defaultPlugins = require('../config/default-plugins');
 
 module.exports  = async function createEngine({ dest, presets = [], plugins = [] }) {
@@ -13,7 +13,7 @@ module.exports  = async function createEngine({ dest, presets = [], plugins = []
     root: dest
   };
 
-  const engine = new PluginEngine(engineConfig, { resolveFrom });
+  const engine = new GasketEngine(engineConfig, { resolveFrom });
   engine.command = { id: 'create' };
   await engine.exec('init');
 

packages/create-gasket-app/test/unit/scaffold/actions/prompt-hooks.test.js

@@ -116,7 +116,7 @@ describe('promptHooks', () => {
       expect(mockInstallStub).not.toHaveBeenCalled();
     });
 
-    it('re-instantiates PluginEngine with only newly added plugins', async () => {
+    it('re-instantiates GasketEngine with only newly added plugins', async () => {
       await mockAddPlugins('@gasket/plugin-jest@^1.2.3');
       expect(mockEngineStub).toHaveBeenCalledWith(expect.objectContaining({ plugins: ['@gasket/jest'] }));
     });

packages/create-gasket-app/test/unit/scaffold/create-engine.test.js

@@ -4,7 +4,7 @@ const path = require('path');
 const defaultPlugins = require('../../../lib/config/default-plugins');
 
 jest.mock('@gasket/engine', () => {
-  return class PluginEngine {
+  return class GasketEngine {
     constructor() {
       mockConstructorStub(...arguments);
     }
@@ -29,7 +29,7 @@ describe('createEngine', () => {
     jest.clearAllMocks();
   });
 
-  it('instantiates PluginEngine with preset from context in array', async () => {
+  it('instantiates GasketEngine with preset from context in array', async () => {
     await createEngine(mockOpts);
     expect(mockConstructorStub).toHaveBeenCalledWith(
       expect.objectContaining({
@@ -39,7 +39,7 @@ describe('createEngine', () => {
     );
   });
 
-  it('instantiates PluginEngine if no preset in context', async () => {
+  it('instantiates GasketEngine if no preset in context', async () => {
     mockOpts = {
       dest: '/some/path/my-app'
     };
@@ -53,7 +53,7 @@ describe('createEngine', () => {
     );
   });
 
-  it('instantiates PluginEngine with built-in git-plugin', async () => {
+  it('instantiates GasketEngine with built-in git-plugin', async () => {
     await createEngine(mockOpts);
     expect(mockConstructorStub).toHaveBeenCalledWith(
       expect.objectContaining({
@@ -65,7 +65,7 @@ describe('createEngine', () => {
     );
   });
 
-  it('instantiates PluginEngine with plugins from context', async () => {
+  it('instantiates GasketEngine with plugins from context', async () => {
     await createEngine(mockOpts);
     expect(mockConstructorStub).toHaveBeenCalledWith(
       expect.objectContaining({
@@ -77,7 +77,7 @@ describe('createEngine', () => {
     );
   });
 
-  it('instantiates PluginEngine if no plugins in context', async () => {
+  it('instantiates GasketEngine if no plugins in context', async () => {
     mockOpts = {
       dest: '/some/path/my-app'
     };
@@ -93,7 +93,7 @@ describe('createEngine', () => {
     );
   });
 
-  it('instantiates PluginEngine with resolveFrom options', async () => {
+  it('instantiates GasketEngine with resolveFrom options', async () => {
     mockOpts = {
       dest: '/some/path/my-app'
     };

packages/gasket-cli/lib/index.d.ts

@@ -1,4 +1,4 @@
-import type { GasketConfigFile, MaybeAsync } from '@gasket/engine';
+import type { GasketConfigDefinition, MaybeAsync } from '@gasket/engine';
 import type { PackageManager } from '@gasket/utils';
 import type { Command } from 'commander';
 
@@ -278,7 +278,7 @@ export interface CreateContext {
   // Added by `setup-gasket-config`
 
   /** gasket.config builder */
-  gasketConfig: ConfigBuilder<GasketConfigFile>;
+  gasketConfig: ConfigBuilder<GasketConfigDefinition>;
 
   // Added by `create-hooks`
 

packages/gasket-core/.gitattributes

@@ -0,0 +1 @@
+package-lock.json binary

packages/gasket-core/CHANGELOG.md

@@ -0,0 +1,2 @@
+# `@gasket/core`
+

packages/gasket-core/LICENSE.md

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2019 GoDaddy Operating Company, LLC.
+
+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.

packages/gasket-core/README.md

@@ -0,0 +1,99 @@
+# @gasket/core
+
+## Installation
+
+#### Existing apps
+
+```shell
+npm install @gasket/core
+```
+
+Add a `gasket.mjs` file to the root of your project.
+This can be a `.js` extension if your package.json has the `type` field set to `module`.
+It is also possible to use with a `.ts` extension if you have TypeScript configured.
+
+```js
+// gasket.mjs
+import { makeGasket } from '@gasket/core';
+import LoggerPlugin from '@gasket/plugin-logger';
+import MyPlugin from './my-plugin';
+
+export default makeGasket({
+  plugins: [
+    LoggerPlugin,
+    MyPlugin
+  ]
+});
+```
+
+You can now import the Gasket instance from your `gasket.mjs` file into your
+application code.
+With a Gasket, you can fire **actions** that will trigger **lifecycles** hooked
+by plugins which encapsulate functionality allowing reuse across many applications.
+
+### Registered plugins
+
+A plugin is a module that exports a `name` and `hooks` object
+(See [Plugins Guide]).
+In your `gasket.mjs` file, you can import plugins and add them to the `plugins`
+array of the Gasket configuration.
+
+## Lifecycles
+
+When a new Gasket is created, there are two lifecycles executed: [configure] and
+[actions].
+
+### configure
+
+The `configure` lifecycle is the first lifecycle executed when a Gasket is
+instantiated.
+This allows any [registered plugins] to adjust the configuration before further
+lifecycles are executed.
+
+```js
+// gasket-plugin-example.mjs
+
+export const name = 'gasket-plugin-example';
+
+export const hooks = {
+  configure(gasket, gasketConfig) {
+    // Modify the configuration
+    return {
+      ...gasketConfig,
+      example: true
+    };
+  }
+};
+```
+
+### actions
+
+The `actions` lifecycle is the second lifecycle executed when a Gasket is created.
+This lets plugins register actions that can be fired by the application code.
+
+```js
+// gasket-plugin-example.mjs
+
+export const name = 'gasket-plugin-example';
+
+export const hooks = {
+  actions(gasket) {
+    return {
+      async getDoodads() {
+        if(gasket.config.example) {
+          const dodaads = await gasket.exec('dodaads');
+          return dodaads.flat()
+        }
+      }
+    }
+  }
+};
+```
+
+In this example, we register an action `getDoodads` that will only execute if the
+`example` configuration is set to `true`.
+It will then execute the `doodads` lifecycle, allowing any registered plugin to
+provide doodads.
+
+[registered plugins]: #registered-plugins
+[Plugins Guide]:/packages/gasket-cli/docs/plugins.md

packages/gasket-core/lib/index.d.ts

@@ -0,0 +1,20 @@
+import { Gasket, GasketConfigDefinition } from '@gasket/engine';
+
+declare module '@gasket/engine' {
+
+  export interface GasketActions {}
+
+  export interface GasketConfig {}
+
+  export interface Gasket {
+    new (config: GasketConfigDefinition): Gasket
+    actions: GasketActions
+  }
+
+  export interface HookExecTypes {
+    configure(config: GasketConfig): GasketConfig
+    actions(): GasketActions
+  }
+}
+
+export function makeGasket(config: GasketConfigDefinition): Gasket

packages/gasket-core/lib/index.js

@@ -0,0 +1,86 @@
+/* eslint-disable no-console, no-process-env */
+/// <reference types="./index" />
+
+import GasketEngine from '@gasket/engine';
+import { applyConfigOverrides } from '@gasket/utils';
+
+/**
+ * Get the environment to use for the gasket instance.
+ * Defaults to `development`.
+ * @returns {string} env
+ */
+function getEnvironment(
+  // flags, commandId, warn
+) {
+  // TODO: enable if cli commands and flags are to be used with v7
+  // if (flags.env) {
+  //   debug('Environment was passed through command line flags', flags.env);
+  //   return flags.env;
+  // }
+
+  const { GASKET_ENV } = process.env;
+  if (GASKET_ENV) {
+    return GASKET_ENV;
+  }
+
+  // TODO: enable if cli commands and flags are to be used with v7
+  // // special snowflake case to match up `local` env with command unless set
+  // if (commandId === 'local') {
+  //   debug('Environment defaulting to `local` due to `local` command');
+  //   return 'local';
+  // }
+
+  const { NODE_ENV } = process.env;
+  if (NODE_ENV) {
+    console.warn(`No env specified, falling back to NODE_ENV: "${NODE_ENV}".`);
+    return NODE_ENV;
+  }
+
+  console.warn('No env specified, falling back to "development".');
+  return 'development';
+}
+/* eslint-enable no-console, no-process-env */
+
+// TODO: Add JSDoc types
+function registerActions(instance) {
+  const actions = {};
+  const actionPluginMap = {};
+
+  instance.execApplySync('actions', async (plugin, handler) => {
+    const results = handler(); // The gasket parameter is automatically applied
+    if (results) {
+      Object.keys(results).forEach(actionName => {
+        if (actionPluginMap[actionName]) {
+          // eslint-disable-next-line no-console
+          console.error(
+            `Action '${actionName}' from '${plugin.name}' was registered by '${actionPluginMap[actionName]}'`
+          );
+          return;
+        }
+        actionPluginMap[actionName] = plugin.name;
+        actions[actionName] = results[actionName];
+      });
+    }
+  });
+
+  return actions;
+}
+
+// TODO: Add JSDoc types
+class Gasket extends GasketEngine {
+  constructor(gasketConfig) {
+    const env = getEnvironment();
+    const config = applyConfigOverrides(gasketConfig, { env });
+    config.env = env;
+    config.root ??= process.cwd();
+
+    super(config.plugins);
+    this.command = null;
+    this.config = this.execWaterfallSync('configure', config);
+    this.actions = registerActions(this);
+  }
+}
+
+export function makeGasket(gasketConfigDefinition) {
+  return new Gasket(gasketConfigDefinition);
+}