create-gasket-app 7.0.2-cli.0 → 7.2.0-canary.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,148 @@
+/* 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,7 @@
+import pluginGit from '@gasket/plugin-git';
+import pluginLogger from '@gasket/plugin-logger';
+
+export const defaultPlugins = [
+  pluginLogger,
+  pluginGit
+];

package/lib/index.d.ts

@@ -0,0 +1,264 @@
+import type { GasketConfigDefinition, MaybeAsync, Plugin, GasketEngine } from '@gasket/core';
+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>;
+  homepage?: 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;
+
+  /**
+   * addPlugin - Add plugin import to the gasket file and use the value in the plugins array
+   * @param {string} pluginImport - name of the import used as a value - `import pluginImport...`
+   * @param {string} pluginName - name of the plugin import/package - `from 'pluginName'`
+   * @example
+   * addPlugin('pluginA', '@gasket/plugin-a')
+   *
+   * // gasket.js
+   * import pluginA from '@gasket/plugin-a';
+   *
+   * export default makeGasket({
+   *  plugins: [
+   *    pluginA
+   *  ]
+   * });
+   */
+  addPlugin(pluginImport: string, pluginName: string): void;
+
+  /**
+   * addImport - Add a non-plugin import to the gasket file
+   * @param {string} importName - name of the import used as a value - `import fs...`
+   * @param {string} importPath - path of the import - `from 'fs'`
+   * @returns {ConfigBuilder} - instance for chaining
+   * @example
+   * Can be default or named import
+   * addImport('{ readFileSync }', 'fs')
+   * addImport('fs', 'fs')
+   *
+   * // gasket.js
+   * import { readFileSync } from 'fs';
+   * import fs from 'fs';
+   */
+  addImport(importName: string, importPath: string): ConfigBuilder<Config>;
+
+  /**
+   * addExpression - add programmatic expression to the gasket file
+   * @param {string} expression - expression to add after imports
+   * @returns {ConfigBuilder} - instance for chaining
+   * @example
+   *
+   * .addImport('fs', 'fs')
+   * .addExpression('const file = fs.readFileSync(\'./file.txt\')')
+   *
+   * // gasket.js
+   * import fs from 'fs';
+   * const file = fs.readFileSync('./file.txt');
+   */
+  addExpression(expression: string): ConfigBuilder<Config>;
+
+  /**
+   * injectValue - Inject a value into the gasket config object
+   * @param {string} configKey - collapsed object path to inject value into - `express.config.routes`
+   * @param {string} injectedValue - string used as a value
+   * @example
+   * .addImport('{ routes }', './routes')
+   * .injectValue('express.routes', 'routes');
+   *
+   * // gasket.js
+   * export default makeGasket({
+   *  express: {
+   *    routes: routes
+   *  }
+   * });
+   */
+  injectValue(configKey: string, injectedValue: string): void;
+}
+
+export interface PackageJsonBuilder extends ConfigBuilder<PackageJson> {
+  /**
+   * Checks if a property exists on the package.json fields.
+   * @param  key - Field to search
+   * @param  value - Value to search for
+   * @returns True if the property exists and matches the value
+   */
+  has(key: keyof PackageJson, 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>;
+
+  /** 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>;
+
+  /** Default empty array, populated by load-preset with actual imports */
+  presets: Array<Plugin>;
+
+  /** Default to object w/empty plugins array to be populated by `presetConfig` hook */
+  presetConfig: GasketConfigDefinition;
+
+  // Added by `global-prompts`
+
+  /** Description of app */
+  appDescription: string;
+
+  /** Should a git repo be initialized and first commit */
+  gitInit: boolean;
+
+  /** Names of the plugins that add unit and integration tests */
+  testPlugins: Array<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 `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;
+}
+
+export interface ActionWrapperParams {
+  gasket: GasketEngine;
+  context: CreateContext;
+  spinner?: any;
+}
+
+declare module '@gasket/core' {
+  export interface HookExecTypes {
+    presetPrompt(context: CreateContext): Promise<void>;
+    presetConfig(context: CreateContext): Promise<CreateContext['presetConfig']>;
+    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,31 @@
 #!/usr/bin/env node
+import { Command } from 'commander';
+import { createRequire } from 'module';
+import { createCommand } from './commands/create.js';
+import { processCommand, logo } from './utils/index.js';
+import { warnIfOutdated } from '@gasket/utils';
 
-const { fork } = require('child_process');
-const path = require('path');
+const require = createRequire(import.meta.url);
+const pkg = require('../package.json');
+const program = new Command();
 
-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();