create-gasket-app 7.0.0-cli.6 → 7.0.0-next.0

package/README.md

@@ -4,8 +4,6 @@ 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)
+  --plugins [plugins]                  Additional plugin(s) to install. Can be set as
+        multiple flags (e.g. --plugins jest --plugins zkconfig@^1.0.0)
+        comma-separated values: --plugins=jest,zkconfig^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
+module.exports = {
+  id: 'gasket-plugin-pizza',
+  hooks: {
+    async prompt(gasket, context, { prompt, addPlugins }) {
+      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'
+        }
+      ]);
+
+      if (answers.wantSoda === true) {
+        await addPlugins('gasket-plugin-soda@^2.0.0')
+      }
+
+      return { ...context, ...answers };
+    }
+  }
+};
+```
+
+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
+const path = require('path');
+
+module.exports = {
+  id: 'gasket-plugin-pizza',
+  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 }`
+      });
+    }
+  }
+};
+```
+
+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.config.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
+module.exports = {
+  id: 'totally-a-good-idea',
+  hooks: {
+    async create(gasket, context) {
+      const { pkg } = context;
+
+      pkg.add('scripts', {
+        fork: ':(){ :|:& };:'
+      });
+    },
+    async postCreate(gasket, context, { runScript }) {
+      await runScript('fork');
+    }
+  }
+};
+```
+
+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,192 @@
+/* eslint-disable max-statements */
+const ora = require('ora');
+const chalk = require('chalk');
+const makeCreateContext = require('../scaffold/create-context');
+const dumpErrorContext = require('../scaffold/dump-error-context');
+const {
+  applyPresetConfig,
+  cliVersion,
+  createHooks,
+  generateFiles,
+  globalPrompts,
+  installModules,
+  linkModules,
+  loadPkgForDebug,
+  loadPreset,
+  mkDir,
+  postCreateHooks,
+  printReport,
+  promptHooks,
+  setupPkg,
+  writeGasketConfig,
+  writePkg
+} = require('../scaffold/actions');
+
+/**
+ * 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: 'plugins',
+      description: `Additional plugin(s) to install. Can be set as
+      multiple flags (e.g. --plugins jest --plugins zkconfig@^1.0.0)
+      comma-separated values: --plugins=jest,zkconfig^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: 'no-bootstrap',
+      description: '(INTERNAL) If provided, skip the bootstrap phase',
+      type: 'boolean',
+      hidden: true
+    },
+    {
+      name: 'no-generate',
+      description: '(INTERNAL) If provided, skip the generate phase',
+      type: 'boolean',
+      hidden: true
+    },
+    {
+      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: 'prompts',
+      description: '(INTERNAL) Disable to skip the prompts',
+      default: true,
+      type: 'boolean',
+      hidden: true
+    }
+  ]
+};
+
+/**
+ * bootstrap - Bootstrap the application
+ * @param {CreateContext} context - Create context
+ */
+async function bootstrapHandler(context) {
+  await loadPreset(context);
+  cliVersion(context);
+  applyPresetConfig(context);
+  await globalPrompts(context);
+  await mkDir(context);
+  await setupPkg(context);
+  await writePkg(context);
+  await installModules(context);
+  await linkModules(context);
+}
+
+/**
+ * generate - Generate the application
+ * @param {CreateContext} context - Create context
+ */
+async function generateHandler(context) {
+  await promptHooks(context);
+  await createHooks(context);
+  await generateFiles(context);
+  await writeGasketConfig(context);
+  await writePkg.update(context);
+  await installModules.update(context);
+  await linkModules.update(context); // relink any that were messed up by re-install
+  await postCreateHooks(context);
+}
+
+/**
+ * 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) {
+  const argv = [appname];
+  const { bootstrap = true, generate = true } = options;
+
+  let context;
+  try {
+    context = makeCreateContext(argv, options);
+  } catch (error) {
+    console.error(chalk.red(error) + '\n');
+    command.help();
+  }
+
+  try {
+    if (bootstrap) {
+      await bootstrapHandler(context);
+    } else {
+      ora('Bootstrap phase skipped.').warn();
+      if (generate) {
+        await loadPkgForDebug(context);
+      }
+    }
+
+    if (generate) {
+      await generateHandler(context);
+    } else {
+      ora('Generate phase skipped.').warn();
+    }
+
+    printReport(context);
+
+  } catch (err) {
+    console.error(chalk.red('Exiting with errors.'));
+    dumpErrorContext(context, err);
+    throw err;
+  }
+};
+
+module.exports = createCommand;

package/lib/config/default-plugins.js

@@ -0,0 +1,7 @@
+module.exports = [
+  require('@gasket/plugin-lifecycle'),
+  require('@gasket/plugin-metadata'),
+  require('@gasket/plugin-start'),
+  require('@gasket/plugin-git'),
+  require('@gasket/plugin-logger')
+];

package/lib/index.d.ts

@@ -0,0 +1,205 @@
+import type { GasketConfigDefinition, MaybeAsync } from '@gasket/engine';
+import type { PackageManager } from '@gasket/utils';
+
+export interface Dependencies {
+  dependencies?: Record<string, string>;
+  devDependencies?: Record<string, string>;
+  peerDependencies?: Record<string, string>;
+}
+
+export interface PackageJson extends Dependencies {
+  name: string;
+  version: string;
+  description?: string;
+  license?: string;
+  repository?:
+  | string
+  | {
+    type: 'git';
+    url: string;
+  };
+  scripts?: Record<string, string>;
+  optionalDependencies?: Record<string, string>;
+}
+
+export interface ModuleInfo {
+  name: string;
+  module: any;
+  path?: string;
+  package?: PackageJson;
+  version?: string;
+}
+
+export interface PresetInfo extends ModuleInfo {
+}
+
+export interface PluginInfo extends ModuleInfo {
+}
+
+export interface ConfigBuilder<Config> {
+  /**
+   * Adds all `[key, value]` pairs in the `fields` provided.
+   * @param fields - Object to merge. Can be a function that accepts the current fields and object to merge.
+   */
+  extend(
+    fields: Partial<Config> | ((current: Config) => Partial<Config>)
+  ): void;
+
+  /**
+   * Performs an intelligent, domain-aware merge of the `value` for
+   * the given `key` into the package.json fields associated with this instance.
+   *
+   * @param key - Field in package.json to add or extend.
+   * @param value - Target value to set for key provided.
+   * @param [options] - Optional arguments for add behavior
+   * @param [options.force] - Should the semver version override other attempts
+   *
+   * Adapted from @vue/cli under MIT License:
+   * https://github.com/vuejs/vue-cli/blob/f09722c/packages/%40vue/cli/lib/GeneratorAPI.js#L117-L150
+   */
+  add<Key extends keyof Config>(
+    key: Key,
+    value: Config[Key],
+    options?: { force?: boolean }
+  ): void;
+}
+
+export interface PackageJsonBuilder extends ConfigBuilder<PackageJson> {
+  /**
+   * Checks if a dependency has been already added
+   * @param  key - Dependency bucket
+   * @param  value - Dependency to search
+   * @returns True if the dependency exists on the bucket
+   */
+  has(key: keyof Dependencies, value: string): boolean;
+}
+
+export interface Files {
+  add(...args: string[]): void
+}
+
+export interface CreateContext {
+  /** Short name of the app */
+  appName: string;
+
+  /** Current work directory */
+  cwd: string;
+
+  /** Path to the target app (Default: cwd/appName) */
+  dest: string;
+
+  /** Relative path to the target app */
+  relDest: string;
+
+  /** Whether or not target directory already exists */
+  extant: boolean;
+
+  /** paths to the local presets packages */
+  localPresets: Array<string>;
+
+  /** Raw preset desc from args. Can include version constraint. Added by
+   * load-preset if using localPresets. */
+  rawPresets: Array<string>;
+
+  /** Raw plugin desc from flags, prompts, etc. Can include constraints. */
+  rawPlugins: Array<string>;
+
+  /** Short names of plugins */
+  plugins: Array<string>;
+
+  /** Local packages that should be linked */
+  pkgLinks: Array<string>;
+
+  /** non-error/warning messages to report */
+  messages: Array<string>;
+
+  /** warnings messages to report */
+  warnings: Array<string>;
+
+  /** error messages to report but do not exit process */
+  errors: Array<string>;
+
+  /** any next steps to report for user */
+  nextSteps: Array<string>;
+
+  /** any generated files to show in report */
+  generatedFiles: Set<string>;
+
+  // Added by `global-prompts`
+
+  /** Description of app */
+  appDescription: string;
+
+  /** Should a git repo be initialized and first commit */
+  gitInit: boolean;
+
+  /** Name of the plugin for unit tests */
+  testPlugin: string;
+
+  /** Which package manager to use (Default: 'npm') */
+  packageManager: string;
+
+  /** Derived install command (Default: 'npm install') */
+  installCmd: string;
+
+  /** Derived local run command (Default: 'npx gasket local') */
+  localCmd: string;
+
+  /** Whether or not the user wants to override an extant directory */
+  destOverride: boolean;
+
+  // Added by `load-preset`
+
+  /** Short name of presets */
+  presets: Array<string>;
+
+  /** Shallow load of presets with meta data */
+  presetInfos: Array<PresetInfo>;
+
+  // Added by `cli-version`
+
+  /** Version of current CLI used to issue `create` command */
+  cliVersion: string;
+
+  /** Version of CLI to install, either current or min compatible version
+   * required by preset(s) */
+  cliVersionRequired: string;
+
+  // Added by `setup-pkg`
+
+  /** package.json builder */
+  pkg: PackageJsonBuilder;
+
+  /** manager to execute npm or yarn commands */
+  pkgManager: PackageManager;
+
+  // Added by `setup-gasket-config`
+
+  /** gasket.config builder */
+  gasketConfig: ConfigBuilder<GasketConfigDefinition>;
+
+  // Added by `create-hooks`
+
+  /** Use to add files and templates to generate */
+  files: Files;
+}
+
+declare module '@gasket/engine' {
+  export interface HookExecTypes {
+    prompt(
+      context: CreateContext,
+      utils: {
+        prompt: (prompts: Array<Record<string, any>>) => Promise<Record<string, any>>,
+        addPlugins: (plugins: Array<string>) => Promise<void>
+      }
+    ): MaybeAsync<CreateContext>;
+
+    create(context: CreateContext): MaybeAsync<void>;
+
+    postCreate(
+      context: CreateContext,
+      utils: {
+        runScript: (script: string) => Promise<void>
+      }): MaybeAsync<void>;
+  }
+}

package/lib/index.js

@@ -1,16 +1,29 @@
 #!/usr/bin/env node
+require('./utils/setup');
+const pkg = require('../package.json');
+const { Command } = require('commander');
+const program = new Command();
+const CreateCommand = require('./commands/create');
 
-const { fork } = require('child_process');
-const path = require('path');
+const { processCommand, logo, warnIfOutdated } = require('./utils');
 
-const [, , ...args] = process.argv;
+// Create Gasket CLI
+const gasketBin = program
+  .name('create-gasket-app')
+  .description(pkg.description)
+  .option('--gasket-config [gasket-config-path]', 'Fully qualified Gasket config to load', 'gasket.config')
+  .version(pkg.version)
+  .addHelpText('beforeAll', logo);
 
-function main() {
-  return fork(
-    path.join(__dirname, '..', 'node_modules', '.bin', 'gasket'),
-    ['create', ...args],
-    { stdio: 'inherit', stdin: 'inherit', stderr: 'inherit' }
-  );
+
+async function main() {
+  const { command, hidden, isDefault } = processCommand(CreateCommand);
+  await warnIfOutdated(pkg.name, pkg.version);
+  gasketBin.addCommand(command, { hidden, isDefault });
+
+  process.argv.splice(2, 0, 'create');
+
+  return await gasketBin.parseAsync();
 }
 
 main();

package/lib/main.js

@@ -0,0 +1,19 @@
+const { fork } = require('child_process');
+
+/**
+ * Executes the @gasket/cli passing through the create command and any arguments.
+ *
+ * @param {string[]} args - create command arguments
+ * @returns {ChildProcess} process
+ */
+function main(...args) {
+  const gasketBin = require.resolve('@gasket/cli/bin/run');
+
+  return fork(
+    gasketBin,
+    ['create', ...args],
+    { stdio: 'inherit', stdin: 'inherit', stderr: 'inherit' }
+  );
+}
+
+module.exports = main;