create-gasket-app 7.0.0-next.8 → 7.0.0

package/README.md

@@ -1,6 +1,6 @@
 # create-gasket-app
 
-Starter Pack for creating Gasket apps. 
+Starter Pack for creating Gasket apps.
 
 ### Get Started Immediately
 
@@ -43,9 +43,6 @@ 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
@@ -100,38 +97,36 @@ 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')
+//  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 };
-    }
+    return { ...context, ...answers };
   }
 };
+
+export default { name, hooks };
 ```
 
 The hook is passed the following parameters:
@@ -156,29 +151,31 @@ package.json or register files and templates to be generated.
 The `create` lifecycle is fired using [exec].
 
 ```js
-const path = require('path');
+//  gasket-plugin-pizza.js
 
-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
+import path from 'path';
 
-      files.add(
-        path.join(__dirname, 'generator', 'ingredients', pizzaSauce)
-      );
+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
 
-      pkg.add('devDependencies', {
-        'pizza-oven': '^1.0.0'
-      });
+    files.add(
+      path.join(__dirname, 'generator', 'ingredients', pizzaSauce)
+    );
 
-      pkg.add('scripts', {
-        bake: `pizza-oven --size ${ pizzaSize }`
-      });
-    }
+    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:
@@ -189,7 +186,7 @@ The hook is passed the following parameters:
 | `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.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     |
@@ -206,9 +203,10 @@ generated. This is useful to use in conjunction with any scripts added in the
 The `postCreate` lifecycle is fired by [exec]:
 
 ```js
-module.exports = {
-  id: 'totally-a-good-idea',
-  hooks: {
+// totally-a-good-idea.js
+
+const name = 'totally-a-good-idea';
+const hooks = {
     async create(gasket, context) {
       const { pkg } = context;
 
@@ -221,6 +219,8 @@ module.exports = {
     }
   }
 };
+
+export default { name, hooks };
 ```
 
 The hook is passed the following parameters:

package/lib/commands/create.js

@@ -103,21 +103,23 @@ const createCommand = {
  * @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(null, context);
+    await globalPrompts({ context });
 
     if (rawPresets.length || localPresets.length) {
-      await loadPreset(null, context);
+
+      await loadPreset({ context });
 
       const presetGasket = makeGasket({
         plugins: context.presets
       });
 
-      await presetPromptHooks(presetGasket, context);
-      await presetConfigHooks(presetGasket, context);
+      await presetPromptHooks({ gasket: presetGasket, context });
+      await presetConfigHooks({ gasket: presetGasket, context });
     }
 
     const pluginGasket = makeGasket({
@@ -125,18 +127,18 @@ createCommand.action = async function run(appname, options, command) {
       plugins: context.presets.concat(context.presetConfig.plugins, defaultPlugins)
     });
 
-    await promptHooks(pluginGasket, context);
-    await mkDir(null, context);
-    await setupPkg(null, context);
-    await createHooks(pluginGasket, context);
-    await writePkg(null, context);
-    await generateFiles(null, context);
-    await writeGasketConfig(null, context);
-    await installModules(null, context);
-    await linkModules(null, context);
-    await postCreateHooks(pluginGasket, context);
+    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(null, context);
+    printReport({ context });
   } catch (err) {
     console.error(chalk.red('Exiting with errors.'));
     dumpErrorContext(context, err);

package/lib/config/default-plugins.js

@@ -1,7 +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
+  pluginGit,
+  pluginMetadata,
+  pluginCommand,
+  pluginDocs,
+  pluginDocusaurus
 ];

package/lib/index.d.ts

@@ -1,5 +1,6 @@
-import type { GasketConfigDefinition, MaybeAsync } from '@gasket/engine';
+import type { GasketConfigDefinition, MaybeAsync, Plugin, GasketEngine } from '@gasket/core';
 import type { PackageManager } from '@gasket/utils';
+import type { PromptModule } from 'inquirer';
 
 export interface Dependencies {
   dependencies?: Record<string, string>;
@@ -9,7 +10,7 @@ export interface Dependencies {
 
 export interface PackageJson extends Dependencies {
   name: string;
-  version: string;
+  version?: string;
   description?: string;
   license?: string;
   repository?:
@@ -20,6 +21,7 @@ export interface PackageJson extends Dependencies {
   };
   scripts?: Record<string, string>;
   optionalDependencies?: Record<string, string>;
+  homepage?: string;
 }
 
 export interface ModuleInfo {
@@ -30,13 +32,16 @@ export interface ModuleInfo {
   version?: string;
 }
 
-export interface PresetInfo extends ModuleInfo {
-}
+export interface PresetInfo extends ModuleInfo { }
 
-export interface PluginInfo extends ModuleInfo {
-}
+export interface PluginInfo extends ModuleInfo { }
 
 export interface ConfigBuilder<Config> {
+  /**
+   * fields object
+   */
+  fields: { [key: string]: any };
+
   /**
    * 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.
@@ -95,7 +100,7 @@ export interface ConfigBuilder<Config> {
    * import { readFileSync } from 'fs';
    * import fs from 'fs';
    */
-  addImport(importName: string, importPath: string): ConfigBuilder;
+  addImport(importName: string, importPath: string): ConfigBuilder<Config>;
 
   /**
    * addExpression - add programmatic expression to the gasket file
@@ -110,7 +115,7 @@ export interface ConfigBuilder<Config> {
    * import fs from 'fs';
    * const file = fs.readFileSync('./file.txt');
    */
-  addExpression(expression: string): ConfigBuilder;
+  addExpression(expression: string): ConfigBuilder<Config>;
 
   /**
    * injectValue - Inject a value into the gasket config object
@@ -127,120 +132,168 @@ export interface ConfigBuilder<Config> {
    *  }
    * });
    */
-  injectValue(configKey: string, injectedValue: any): void;
+  injectValue(configKey: string, injectedValue: string): 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
+   * 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 Dependencies, value: string): boolean;
+  has(key: keyof PackageJson, value: string): boolean;
 }
 
 export interface Files {
-  add(...args: string[]): void
+  add(...args: string[]): void;
+}
+
+export interface Readme {
+  /** Markdown content to be injected into the app readme */
+  markdown: string[];
+
+  /** Links to be added to the footer */
+  links: string[];
+
+  /** Add a markdown heading */
+  heading(content: string, level?: number): Readme;
+
+  /** Add a markdown sub-heading */
+  subHeading(content: string): Readme;
+
+  /** Add markdown content */
+  content(markdown: string);
+
+  /** Add a markdown list */
+  list(items: string[]): Readme;
+
+  /** Add a markdown link - printed in footer */
+  link(content: string, href: string): Readme;
+
+  /** Add a markdown code block */
+  codeBlock(content: string, syntax?: string): Readme;
+
+  /** Add markdown file */
+  markdownFile(path: string): Promise<Readme>;
 }
 
-export interface CreateContext {
-  /** Short name of the app */
-  appName: string;
+export type CreatePrompt = PromptModule;
+
+declare module 'create-gasket-app' {
+  export interface CreateContext {
+    /** Short name of the app */
+    appName: string;
 
-  /** Current work directory */
-  cwd: string;
+    /** Current work directory */
+    cwd: string;
 
-  /** Path to the target app (Default: cwd/appName) */
-  dest: string;
+    /** Path to the target app (Default: cwd/appName) */
+    dest: string;
 
-  /** Relative path to the target app */
-  relDest: string;
+    /** Relative path to the target app */
+    relDest: string;
 
-  /** Whether or not target directory already exists */
-  extant: boolean;
+    /** Whether or not target directory already exists */
+    extant: boolean;
 
-  /** paths to the local presets packages */
-  localPresets: Array<string>;
+    /** 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 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>;
+    /** Local packages that should be linked */
+    pkgLinks: Array<string>;
 
-  /** non-error/warning messages to report */
-  messages: Array<string>;
+    /** non-error/warning messages to report */
+    messages: Array<string>;
 
-  /** warnings messages to report */
-  warnings: Array<string>;
+    /** warnings messages to report */
+    warnings: Array<string>;
 
-  /** error messages to report but do not exit process */
-  errors: 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 next steps to report for user */
+    nextSteps: Array<string>;
 
-  /** any generated files to show in report */
-  generatedFiles: Set<string>;
+    /** any generated files to show in report */
+    generatedFiles: Set<string>;
 
-  /** Default empty array, populated by load-preset with actual imports */
-  presets: Array<any>;
+    /** 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;
+    /** Default to object w/empty plugins array to be populated by `presetConfig` hook */
+    presetConfig: GasketConfigDefinition;
 
-  // Added by `global-prompts`
+    // Added by `global-prompts`
 
-  /** Description of app */
-  appDescription: string;
+    /** Description of app */
+    appDescription: string;
 
-  /** Should a git repo be initialized and first commit */
-  gitInit: boolean;
+    /** Should a git repo be initialized and first commit */
+    gitInit: boolean;
 
-  /** Name of the plugin for unit tests */
-  testPlugin: string;
+    /** Names of the plugins that add unit and integration tests */
+    testPlugins: Array<string>;
 
-  /** Which package manager to use (Default: 'npm') */
-  packageManager: string;
+    /** Which package manager to use (Default: 'npm') */
+    packageManager: string;
 
-  /** Derived install command (Default: 'npm install') */
-  installCmd: string;
+    /** Derived install command (Default: 'npm install') */
+    installCmd: string;
 
-  /** Derived local run command (Default: 'npx gasket local') */
-  localCmd: string;
+    /** Derived local run command (Default: 'npx gasket local') */
+    localCmd: string;
 
-  /** Whether or not the user wants to override an extant directory */
-  destOverride: boolean;
+    /** Whether or not the user wants to override an extant directory */
+    destOverride: boolean;
 
-  // Added by `setup-pkg`
+    // Added by `setup-pkg`
 
-  /** package.json builder */
-  pkg: PackageJsonBuilder;
+    /** package.json builder */
+    pkg: PackageJsonBuilder;
 
-  /** manager to execute npm or yarn commands */
-  pkgManager: PackageManager;
+    /** manager to execute npm or yarn commands */
+    pkgManager: PackageManager;
 
-  // Added by `setup-gasket-config`
+    // Added by `setup-gasket-config`
 
-  /** gasket.config builder */
-  gasketConfig: ConfigBuilder<GasketConfigDefinition>;
+    /** gasket.config builder */
+    gasketConfig: ConfigBuilder<GasketConfigDefinition>;
 
-  // Added by `create-hooks`
+    // Added by `create-hooks`
 
-  /** Use to add files and templates to generate */
-  files: Files;
+    /** Use to add files and templates to generate */
+    files: Files;
+
+    /** Use to add content to the README.md */
+    readme: Readme;
+  }
 }
 
-declare module '@gasket/engine' {
+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<void>;
+    presetPrompt(
+      context: CreateContext,
+      utils: {
+        prompt: CreatePrompt;
+      }
+    ): Promise<void>;
+    presetConfig(context: CreateContext): Promise<CreateContext['presetConfig']>;
     prompt(
       context: CreateContext,
       utils: {
-        prompt: (prompts: Array<Record<string, any>>) => Promise<Record<string, any>>,
+        prompt: CreatePrompt;
       }
     ): MaybeAsync<CreateContext>;
 
@@ -249,7 +302,8 @@ declare module '@gasket/engine' {
     postCreate(
       context: CreateContext,
       utils: {
-        runScript: (script: string) => Promise<void>
-      }): MaybeAsync<void>;
+        runScript: (script: string) => Promise<void>;
+      }
+    ): MaybeAsync<void>;
   }
 }

package/lib/index.js

@@ -2,7 +2,8 @@
 import { Command } from 'commander';
 import { createRequire } from 'module';
 import { createCommand } from './commands/create.js';
-import { processCommand, logo, warnIfOutdated } from './utils/index.js';
+import { processCommand, logo } from './utils/index.js';
+import { warnIfOutdated } from '@gasket/utils';
 
 const require = createRequire(import.meta.url);
 const pkg = require('../package.json');

package/lib/scaffold/action-wrapper.js

@@ -14,14 +14,16 @@ export default function withSpinner(label, fn, { startSpinner = true } = {}) {
   /**
    * Decorated function
    *
-   * @param {CreateContext} context - Create context
+   * @param {ActionWrapperParams} params - ActionWrapperParams
+   * @param {GasketEngine} params.gasket - Gasket config
+   * @param {CreateContext} params.context - Create context
    * @returns {Promise} promise
    */
-  async function wrapper(gasket = {}, context) {
+  async function wrapper({ gasket = {}, context }) {
     const spinner = ora(label);
     if (startSpinner) spinner.start();
     try {
-      await fn(gasket, context, spinner);
+      await fn({ gasket, context, spinner });
       if (spinner.isSpinning) spinner.succeed();
     } catch (err) {
       spinner.fail();

package/lib/scaffold/actions/create-hooks.js

@@ -1,20 +1,23 @@
 import action from '../action-wrapper.js';
 import { ConfigBuilder } from '../config-builder.js';
 import { Files } from '../files.js';
+import Readme from '../readme.js';
 
 /**
  * Executes the `create` hook for all registered plugins.
  * Adds `files` to context for plugins to add their files and templates.
  *
+ * @param {GasketEngine} gasket - Gasket API
  * @param {CreateContext} context - Create context
  * @returns {Promise} promise
  */
-async function createHooks(gasket, context) {
+async function createHooks({ gasket, context }) {
   const { plugins = [], warnings } = context;
 
   const files = new Files();
+  const readme = new Readme();
   const gasketConfig = ConfigBuilder.create({}, { orderBy: ['plugins'], warnings, plugins });
-  Object.assign(context, { files, gasketConfig });
+  Object.assign(context, { files, readme, gasketConfig });
 
   await gasket.execApply('create', async function applyCreate(plugin, handler) {
     await handler(context.runWith(plugin));

package/lib/scaffold/actions/generate-files.js

@@ -109,6 +109,10 @@ async function performGenerate(context, descriptors) {
   handlebars.registerHelper('jspretty', (data) => {
     return JSON.stringify(data).replace(/"/g, '\'');
   });
+  handlebars.registerHelper('eq', (a, b) => a === b);
+  handlebars.registerHelper('markdownCompile', (data) => {
+    return handlebars.compile(data)(context);
+  });
 
   debug('descriptors', JSON.stringify(descriptors, null, 2));
 
@@ -164,7 +168,7 @@ async function performGenerate(context, descriptors) {
  * @param {Spinner} spinner - Spinner
  * @returns {Promise} promise
  */
-async function generateFiles(_, context, spinner) {
+async function generateFiles({ context, spinner }) {
   const { files } = context;
 
   if (!files.globSets.length) {