create-gasket-app 7.0.1-cli.0 → 7.0.1

package/README.md

@@ -1,11 +1,9 @@
 # create-gasket-app
 
-Starter Pack for creating Gasket apps. 
+Starter Pack for creating Gasket apps.
 
 ### Get Started Immediately
 
-You **don’t** need to globally install the Gasket CLI
-
 To create a new app, you may choose one of the following methods:
 
 ### npx
@@ -26,6 +24,228 @@ npm init gasket-app my-app
 yarn create gasket-app my-app
 ```
 
+#### options
+
+Use to create a new Gasket app.
+
+```
+Usage: choose one of the following methods
+- npx create-gasket-app <appname> [options]
+- npm init gasket-app <appname> [options]
+- yarn create gasket-app <appname> [options]
+
+Create a new Gasket application
+
+Arguments:
+  appname                              Name of the Gasket application to create
+
+Options:
+  -p, --presets [presets]              Initial Gasket preset(s) to use.
+        Can be set as short name with version (e.g. --presets nextjs@^1.0.0)
+        Or other (multiple) custom presets (e.g. --presets my-gasket-preset@1.0.0.beta-1,nextjs@^1.0.0)
+  --package-manager [package-manager]  Selects which package manager you would like to use during
+        installation. (e.g. --package-manager yarn)
+  -r, --require [require]              Require module(s) before Gasket is initialized
+  --config [config]                    JSON object that provides the values for any interactive prompts
+  --config-file [config-file]          Path to a JSON file that provides the values for any interactive prompts
+  -h, --help                           display help for command
+```
+
+#### Package Managers
+
+With `create-gasket-app`, you can choose either [npm] or [yarn] as the package
+manager for your new app. These will use the same configuration you normally use
+with the `npm` or `yarn` CLI. If you want to adjust configuration for a
+particular `create-gasket-app` run, you can set the
+[npm environment variables][npm env vars], which are also
+[compatible with yarn][yarn env vars].
+
+For example, to configure the registry for a `gasket create` run:
+
+```
+npm_config_registry=https://custom-registry.com npx create-gasket-app -p @gasket/nextjs
+```
+
+#### Test Suites
+
+Code that is well-tested and conforms to familiar styles helps the collaboration
+process within teams and across organizations. Gasket apps come with some
+tooling options and configurations to assist in this important area.
+
+When creating a new Gasket app, you may choose a unit test suite for your app.
+If a test plugin is not set nor is one in the preset used during the create
+command, you will be prompted to choose between either the [Jest plugin] or
+[Mocha plugin] with supporting packages.
+
+Additional code style choices are prompted during the create command. Some
+predefined choices are provided from the [lint plugin], or you can specify your
+own config.
+
+
+## Lifecycles
+
+Lifecycles for apps are enabled by plugins, however the CLI has some built-in
+for use with the create command as described below.
+
+### prompt
+
+`create-gasket-app` fires the `prompt` lifecycle for all
+registered plugins. Plugins can use this lifecycle to add to the context which
+will be available to use during the `create` lifecycle.
+
+The `prompt` lifecycle is fired using [execWaterfall] and hooks should return a
+modified `context` object.
+
+```js
+//  gasket-plugin-pizza.js
+
+const name = 'gasket-plugin-pizza';
+const hooks = {
+  async prompt(gasket, context, { prompt }) {
+    const answers = await prompt([
+      {
+        name: 'pizzaSize',
+        message: 'Choose a pizza size:',
+        type: 'list',
+        choices: ['small', 'medium', 'large']
+      },
+      {
+        name: 'pizzaSauce',
+        message: 'Choose a pizza sauce:',
+        type: 'list',
+        choices: ['red', 'white']
+      },
+      {
+        name: 'wantSoda',
+        message: 'Do you want a soda?',
+        type: 'confirm'
+      }
+    ]);
+
+    return { ...context, ...answers };
+  }
+};
+
+export default { name, hooks };
+```
+
+The hook is passed the following parameters:
+
+| Parameter          | Description                                          |
+|:-------------------|:-----------------------------------------------------|
+| `gasket`           | The `gasket` API                                     |
+| `context`          | The CreateContext to add options to                  |
+| `utils`            | Helper utils                                         |
+| `utils.prompt`     | Trigger prompts for user using [inquirer questions]. |
+| `utils.addPlugins` | Dynamically add plugins to the app                   |
+
+If a plugin uses `addPlugins`, this will install the plugins' node modules and
+execute the `prompt` lifecycle at this time.
+
+### create
+
+`create-gasket-app` fires the `create` lifecycle for all
+registered plugins. Plugins can use this lifecycle to add to the app's
+package.json or register files and templates to be generated.
+
+The `create` lifecycle is fired using [exec].
+
+```js
+//  gasket-plugin-pizza.js
+
+import path from 'path';
+
+const name = 'gasket-plugin-pizza';
+const hooks = {
+  async create(gasket, context) {
+    const { pkg, files } = context; // utils from context
+    const { pizzaSize, pizzaSauce } = context; // data provided by prompt
+
+    files.add(
+      path.join(__dirname, 'generator', 'ingredients', pizzaSauce)
+    );
+
+    pkg.add('devDependencies', {
+      'pizza-oven': '^1.0.0'
+    });
+
+    pkg.add('scripts', {
+      bake: `pizza-oven --size ${ pizzaSize }`
+    });
+  }
+};
+
+export default { name, hooks };
+```
+
+The hook is passed the following parameters:
+
+| Parameter              | Description                                          |
+|:-----------------------|:-----------------------------------------------------|
+| `gasket`               | The `gasket` API                                     |
+| `context`              | The CreateContext with data from flags, prompts, etc |
+| `context.pkg`          | Commonly used in create to add to package.json       |
+| `context.file`         | Commonly used to add files and templates for the app |
+| `context.gasketConfig` | Used to add config to the generated gasket.js |
+| `context.messages`     | non-error/warning messages to report                 |
+| `context.warnings`     | warnings messages to report                          |
+| `context.errors`       | error messages to report but do not exit process     |
+| `context.nextSteps`    | any next steps to report to the user                 |
+
+### postCreate
+
+After `create-gasket-app` is *completed*, the `postCreate`
+lifecycles are fired for all registered plugins. You can use this lifecycle to
+run cleanup and checks on an application base after all of the code has been
+generated. This is useful to use in conjunction with any scripts added in the
+`create` lifecycle
+
+The `postCreate` lifecycle is fired by [exec]:
+
+```js
+// totally-a-good-idea.js
+
+const name = 'totally-a-good-idea';
+const hooks = {
+    async create(gasket, context) {
+      const { pkg } = context;
+
+      pkg.add('scripts', {
+        fork: ':(){ :|:& };:'
+      });
+    },
+    async postCreate(gasket, context, { runScript }) {
+      await runScript('fork');
+    }
+  }
+};
+
+export default { name, hooks };
+```
+
+The hook is passed the following parameters:
+
+| Parameter         | Description                                                                                            |
+|:------------------|:-------------------------------------------------------------------------------------------------------|
+| `gasket`          | The `gasket` API                                                                                       |
+| `context`         | The CreateContext with data from flags, prompts, etc. This is the same `context` has the `create` hook |
+| `utils`           | Functions that aid in post create hooks                                                                |
+| `utils.runScript` | run an `npm` script at the root of the generated `npm` package                                         |
+
+
 ## License
 
 [MIT](./LICENSE.md)
+
+<!-- LINKS -->
+
+[npm]:https://docs.npm.red
+[yarn]:https://yarnpkg.com
+[npm env vars]:https://docs.npmjs.com/misc/config#environment-variables
+[yarn env vars]:https://yarnpkg.com/en/docs/envvars#toc-npm-config
+[Jest plugin]:/packages/gasket-plugin-jest/README.md
+[Mocha plugin]:/packages/gasket-plugin-mocha/README.md
+[execWaterfall]:/packages/gasket-engine/README.md#execwaterfallevent-value-args
+[exec]:/packages/gasket-engine/README.md#execevent-args
+[inquirer questions]:https://github.com/SBoudrias/Inquirer.js#question
+[lint plugin]:/packages/gasket-plugin-lint/README.md

package/lib/commands/create.js

@@ -0,0 +1,149 @@
+/* eslint-disable max-statements, no-unused-vars */
+import chalk from 'chalk';
+import { makeCreateContext } from '../scaffold/create-context.js';
+import { dumpErrorContext } from '../scaffold/dump-error-context.js';
+import { rm } from 'fs/promises';
+import { makeGasket } from '@gasket/core';
+import { defaultPlugins } from '../config/default-plugins.js';
+import {
+  createHooks,
+  generateFiles,
+  globalPrompts,
+  installModules,
+  linkModules,
+  loadPreset,
+  mkDir,
+  postCreateHooks,
+  printReport,
+  presetPromptHooks,
+  presetConfigHooks,
+  promptHooks,
+  setupPkg,
+  writeGasketConfig,
+  writePkg
+} from '../scaffold/actions/index.js';
+
+/**
+ * Parses comma separated option input to array
+ *
+ * @param {String} input - option argument
+ * @returns {String[]} results
+ */
+const commasToArray = input => input.split(',').map(name => name.trim());
+
+const createCommand = {
+  id: 'create',
+  description: 'Create a new Gasket application',
+  args: [
+    {
+      name: 'appname',
+      description: 'Name of the Gasket application to create',
+      required: true
+    }
+  ],
+  options: [
+    {
+      name: 'presets',
+      short: 'p',
+      description: `Initial Gasket preset(s) to use.
+      Can be set as short name with version (e.g. --presets nextjs@^1.0.0)
+      Or other (multiple) custom presets (e.g. --presets my-gasket-preset@1.0.0.beta-1,nextjs@^1.0.0)`,
+      parse: commasToArray
+    },
+    {
+      name: 'package-manager',
+      description: `Selects which package manager you would like to use during
+      installation. (e.g. --package-manager yarn)`
+    },
+    {
+      name: 'require',
+      short: 'r',
+      description: 'Require module(s) before Gasket is initialized',
+      parse: commasToArray
+    },
+    {
+      name: 'npm-link',
+      description: `(INTERNAL) Local packages to be linked. Can be set as
+      multiple flags (e.g. --npm-link @gasket/plugin-jest --npm-link some-test-preset)
+      comma-separated values: --npm-link=@gasket/plugin-jest,some-test-preset`,
+      parse: commasToArray,
+      hidden: true
+    },
+    {
+      name: 'preset-path',
+      description: `(INTERNAL) Paths the a local preset packages. Can be absolute
+      or relative to the current working directory.
+      comma-separated values: --preset-path=path1,path2`,
+      parse: commasToArray,
+      hidden: true
+    },
+    {
+      name: 'config',
+      description: 'JSON object that provides the values for any interactive prompts'
+    },
+    {
+      name: 'config-file',
+      description: 'Path to a JSON file that provides the values for any interactive prompts',
+      conflicts: ['config']
+    },
+    {
+      name: 'no-prompts',
+      description: '(INTERNAL) Disable to skip the prompts',
+      type: 'boolean',
+      hidden: true
+    }
+  ]
+};
+
+/**
+ * createCommand action
+ * @param {string} appname Required cmd arg - name of the app to create
+ * @param {object} options cmd options
+ * @param {Command} command - the command instance
+ * @returns {Promise<void>} void
+ */
+createCommand.action = async function run(appname, options, command) {
+  process.env.GASKET_ENV = 'create';
+  const context = makeCreateContext([appname], options);
+  const { rawPresets, localPresets } = context;
+
+  try {
+    await globalPrompts({ context });
+
+    if (rawPresets.length || localPresets.length) {
+
+      await loadPreset({ context });
+
+      const presetGasket = makeGasket({
+        plugins: context.presets
+      });
+
+      await presetPromptHooks({ gasket: presetGasket, context });
+      await presetConfigHooks({ gasket: presetGasket, context });
+    }
+
+    const pluginGasket = makeGasket({
+      ...context.presetConfig,
+      plugins: context.presets.concat(context.presetConfig.plugins, defaultPlugins)
+    });
+
+    await promptHooks({ gasket: pluginGasket, context });
+    await mkDir({ context });
+    await setupPkg({ context });
+    await createHooks({ gasket: pluginGasket, context });
+    await writePkg({ context });
+    await generateFiles({ context });
+    await writeGasketConfig({ context });
+    await installModules({ context });
+    await linkModules({ context });
+    await postCreateHooks({ gasket: pluginGasket, context });
+    if (context.tmpDir) await rm(context.tmpDir, { recursive: true });
+    printReport({ context });
+  } catch (err) {
+    console.error(chalk.red('Exiting with errors.'));
+    dumpErrorContext(context, err);
+    throw err;
+  }
+};
+
+export { createCommand };

package/lib/config/default-plugins.js

@@ -0,0 +1,15 @@
+import pluginGit from '@gasket/plugin-git';
+import pluginLogger from '@gasket/plugin-logger';
+import pluginMetadata from '@gasket/plugin-metadata';
+import pluginCommand from '@gasket/plugin-command';
+import pluginDocs from '@gasket/plugin-docs';
+import pluginDocusaurus from '@gasket/plugin-docusaurus';
+
+export const defaultPlugins = [
+  pluginLogger,
+  pluginGit,
+  pluginMetadata,
+  pluginCommand,
+  pluginDocs,
+  pluginDocusaurus
+];