create-gasket-app 8.0.0-next.1 → 8.0.0-next.3

package/EXAMPLES.md

@@ -12,12 +12,6 @@ npx create-gasket-app@latest my-app --template @gasket/template-nextjs-pages
 
 # With package manager selection
 npx create-gasket-app@latest my-app --template @gasket/template-nextjs-pages --package-manager pnpm
-
-# With configuration
-npx create-gasket-app@latest my-app --template @gasket/template-nextjs-pages --config '{"typescript": true}'
-
-# With config file
-npx create-gasket-app@latest my-app --template @gasket/template-nextjs-pages --config-file ./create-config.json
 ```
 
 ## Templates

package/README.md

@@ -46,9 +46,6 @@ Options:
         or relative to the current working directory.
   --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
 ```
 
@@ -117,156 +114,6 @@ tooling options and configurations to assist in this important area.
 When creating a new Gasket app, you can configure your own test suite and
 linting setup according to your team's preferences.
 
-## 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.files`        | 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)
@@ -277,6 +124,3 @@ The hook is passed the following parameters:
 [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
-[execWaterfall]:/packages/gasket-core/docs/gasket-engine.md#execwaterfallevent-value-args
-[exec]:/packages/gasket-core/docs/gasket-engine.md#execevent-args
-[inquirer questions]:https://github.com/SBoudrias/Inquirer.js#question

package/lib/commands/create.js

@@ -9,12 +9,6 @@ import mkDir from '../scaffold/actions/mkdir.js';
 import printReport from '../scaffold/actions/print-report.js';
 import gitInit from '../scaffold/actions/git-init.js';
 
-/**
- * Parses comma separated option input to array
- * @type {import('../internal.js').commasToArray}
- */
-const commasToArray = input => input.split(',').map(name => name.trim());
-
 const createCommand = {
   id: 'create',
   description: 'Create a new Gasket application',
@@ -41,43 +35,13 @@ const createCommand = {
       name: 'package-manager',
       description: `Selects which package manager you would like to use during
       installation. (e.g. --package-manager pnpm)`
-    },
-    {
-      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)
-      comma-separated values: --npm-link=@gasket/plugin-jest,some-test-package`,
-      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
     }
   ]
 };
 
 /**
- * validateOption - We require at least one of the options to be provided
- * @param {import('../internal.js').PartialCreateContext} context - Create context
- * @returns {import('../internal.js').PartialCreateContext} Validated context
+ * We require at least one of the options to be provided
+ * @type {import('../internal.d.ts').validateOptions}
  */
 function validateOptions(context) {
   const hasOption = (context) => Boolean(context.template || context.templatePath);
@@ -90,11 +54,7 @@ function validateOptions(context) {
   return context;
 }
 
-/**
- * handleTemplate - Handles the template creation
- * @param {import('../internal.js').PartialCreateContext} context - Create context
- * @returns {Promise<void>} Promise that resolves when template is created
- */
+/** @type {import('../internal.d.ts').handleTemplate} */
 async function handleTemplate(context) {
   await mkDir({ context });
   await loadTemplate({ context });
@@ -106,10 +66,7 @@ async function handleTemplate(context) {
   return;
 }
 
-/**
- * createCommand action
- * @type {import('../index.js').createCommandAction}
- */
+/** @type {import('../index.d.ts').createCommandAction} */
 // eslint-disable-next-line no-unused-vars
 createCommand.action = async function run(appname, options, command) {
   // eslint-disable-next-line no-process-env

package/lib/index.d.ts

@@ -1,6 +1,4 @@
-import type { GasketConfigDefinition, MaybeAsync, Plugin, GasketEngine } from '@gasket/core';
-import type { PromptModule } from 'inquirer';
-import type ora from 'ora';
+import type { GasketConfigDefinition, Plugin } from '@gasket/core';
 import type { Command } from 'commander';
 
 export interface Dependencies {
@@ -48,11 +46,7 @@ interface CommandOption {
 export interface CreateCommandOptions {
   template?: string;
   templatePath?: string;
-  npmLink?: string[];
   packageManager?: string;
-  prompts?: boolean;
-  config?: string;
-  configFile?: string;
 }
 
 export function createCommandAction(
@@ -246,165 +240,6 @@ export interface PackageJsonBuilder extends ConfigBuilder<PackageJson> {
   has(key: keyof PackageJson, value: string): boolean;
 }
 
-/**
- * Interface for the Files class.
- */
-interface Files {
-  /**
-   * Array of glob sets, each containing an array of globs and a source object.
-   */
-  globSets: Array<{ globs: string[], source: Plugin }>;
-
-  /**
-   * Return array of globs.
-   * @deprecated
-   * @returns {string[]} `globby` compatible patterns.
-   */
-  readonly globs: string[];
-
-  /**
-   * Adds the specified `globby` compatible patterns, `globs`,
-   * into the set of all sources for this set of files.
-   * @param {object} params - Object containing `globs` and `source`.
-   * @param {string[]} params.globs - `globby` compatible patterns.
-   * @param {object} params.source - Plugin to blame if conflicts arise from this operation.
-   */
-  add(params: { globs: string[], source: object }): void;
-  add(...globs: string[]): void;
-
-  /** Add a warning message if this.warnings exists else log it as a warming */
-  warn(message: string): void;
-
-  /**
-   * Checks if a dependency has been already added
-   * @param  {string} key Dependency bucket
-   * @param  {string} value Dependency to search
-   * @returns {boolean} True if the dependency exists on the bucket
-   */
-  has(key: string, value: string): boolean;
-
-  /**
-   * Returns the existing and target array merged without duplicates
-   * @param  {Array} existing Partial lattice to merge.
-   * @param  {Array} target   Partial lattice to merge.
-   * @returns {Array} existing ∪ (i.e. union) target
-   *
-   * Adapted from @vue/cli under MIT License:
-   * https://github.com/vuejs/vue-cli/blob/f09722c/packages/%40vue/cli/lib/GeneratorAPI.js#L15
-   */
-  mergeArrayDeduped(existing: any[], target: any[]): any[];
-
-  /**
-   * Attempts to merge all entries within the `value` provided by
-   * the plugin specified by `name` into the `existing` semver-aware
-   * Object `key` (e.g. dependencies, etc.) for this instance.
-   *
-   * Merge algorithm:
-   *
-   * - ∀   [dep, ver] := Object.entries(value)
-   *   and [prev]     := any existing version for dep
-   *
-   *   - If ver is not valid semver ––> ■
-   *   - If ¬∃ prev                 ––> set and blame [dep, ver]
-   *   - If ver > prev              ––> set and blame [dep, ver]
-   *   - If ¬(ver ∩ prev)           ––> Conflict. Print.
-   * @param {object} options
-   * @param  {string} options.key      {devD,peerD,optionalD,d}ependencies
-   * @param  {object} options.value    Updates for { name: version } pairs
-   * @param  {object} options.existing Existing { name: version } pairs
-   * @param  {string} options.name     Plugin name providing merge `value``
-   * @param {boolean} [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/util/mergeDeps.js
-   */
-  semanticMerge({ key, value, existing, name, force }: {
-    key: string;
-    value: any;
-    existing: any;
-    name: string;
-    force?: boolean;
-  }): void;
-
-  /**
-   * Normalizes a potential semver range into a semver string
-   * and returns the newest version
-   * @param  {string} r1 Semver string (potentially invalid).
-   * @param  {string} r2 Semver string (potentially invalid).
-   * @returns {string | undefined} Newest semver version.
-   *
-   * Adapted from @vue/cli under MIT License:
-   * https://github.com/vuejs/vue-cli/blob/f09722c/packages/%40vue/cli/lib/util/mergeDeps.js#L58-L64
-   */
-  tryGetNewerRange(r1: string, r2: string): string | undefined;
-
-  /**
-   * Performs a naive attempt to take a transform a semver range
-   * into a concrete version that may be used for "newness"
-   * comparison.
-   * @param  {string} range Valid "basic" semver:   ^X.Y.Z, ~A.B.C, >=2.3.x, 1.x.x
-   * @returns {string} Concrete as possible version: X.Y.Z,  A.B.C,   2.3.0, 1.0.0
-   */
-  rangeToVersion(range: string): string;
-
-  /**
-   * Orders top-level keys by `orderBy` options with any fields specified in
-   * the `orderFields` options having their keys sorted.
-   * @returns {object} Ready to be serialized JavaScript object.
-   */
-  toJSON(): object;
-
-  /**
-   * Orders the given object, `obj`, applying any (optional)
-   * key order specified via `orderBy`. If no `orderBy` is provided
-   * keys are ordered lexographically.
-   * @param  {object}   obj       Object to transform to ordered keys
-   * @param  {string[]} [orderBy] Explicit key order to use.
-   * @returns {object} Shallow clone of `obj` with ordered keys
-   *
-   * Adapted from @vue/cli under MIT License:
-   * https://github.com/vuejs/vue-cli/blob/f09722c/packages/%40vue/cli/lib/util/sortObject.js
-   */
-  toOrderedKeys(obj: object, orderBy?: string[]): object;
-}
-
-export interface Readme {
-  /** Markdown content to be injected into the app readme */
-  markdown: string[];
-
-  /** Links to be added to the footer */
-  links: string[];
-
-  addNewLine(): this;
-
-  /** Add a markdown heading */
-  heading(content: string, level?: number): this;
-
-  /** Add a markdown sub-heading */
-  subHeading(content: string): this;
-
-  /** Add markdown content */
-  content(markdown: string);
-
-  /** Add a markdown list */
-  list(items: string[]): this;
-
-  /** Add a markdown link - printed in footer */
-  link(content: string, href: string): this;
-
-  /** Add a markdown code block */
-  codeBlock(content: string, syntax?: string): this;
-
-  /** Add markdown file */
-  markdownFile(path: string): Promise<this>;
-}
-
-type NoopPromptObject = {
-  [key: string]: any;
-};
-type NoopPromptFunction = () => NoopPromptObject;
-export type CreatePrompt = PromptModule | NoopPromptFunction;
-
 export interface CreateContext {
   /** Short name of the app */
   appName: string;
@@ -421,9 +256,6 @@ export interface CreateContext {
   /** Whether or not target directory already exists */
   extant: boolean;
 
-  /** Local packages that should be linked */
-  pkgLinks: Array<string>;
-
   /** non-error/warning messages to report */
   messages: Array<string>;
 
@@ -439,9 +271,6 @@ export interface CreateContext {
   /** any generated files to show in report */
   generatedFiles: Set<string>;
 
-  /** (INTERNAL) false to skip the prompts */
-  prompts: boolean;
-
   /** temporary directory */
   tmpDir: string;
 
@@ -457,8 +286,6 @@ export interface CreateContext {
   /** resolved template name for display */
   templateName?: string;
 
-  // Added by `global-prompts`
-
   /** Description of app */
   appDescription: string;
 
@@ -492,14 +319,6 @@ export interface CreateContext {
 
   /** gasket.config builder */
   gasketConfig: ConfigBuilder<GasketConfigDefinition>;
-
-  // Added by `create-hooks`
-
-  /** Use to add files and templates to generate */
-  files: Files;
-
-  /** Use to add content to the README.md */
-  readme: Readme;
   // eslint-disable-next-line @typescript-eslint/no-misused-new
   constructor(initContext?: Partial<CreateContext>);
   runWith(plugin: Plugin): CreateContext;
@@ -510,33 +329,6 @@ export interface CreateContext {
   addApiRoutes?: boolean;
 }
 
-export interface ActionWrapperParams {
-  gasket: GasketEngine;
-  context: CreateContext;
-  spinner?: ora.Ora;
-}
-
-declare module '@gasket/core' {
-
-  export interface HookExecTypes {
-    prompt(
-      context: CreateContext,
-      utils: {
-        prompt: CreatePrompt;
-      }
-    ): MaybeAsync<CreateContext>;
-
-    create(context: CreateContext): MaybeAsync<void>;
-
-    postCreate(
-      context: CreateContext,
-      utils: {
-        runScript: (script: string) => Promise<void>;
-      }
-    ): MaybeAsync<void>;
-  }
-}
-
 declare global {
   namespace NodeJS {
     interface Process {

package/lib/internal.d.ts

@@ -1,7 +1,5 @@
 import type {
   CreateContext,
-  CreatePrompt,
-  ConfigBuilder,
   CreateCommand,
   CommandArgument,
   CommandOption,
@@ -14,14 +12,11 @@ import type { Command, Option } from 'commander';
 
 export type PartialCreateContext = Partial<CreateContext>;
 
-export function commasToArray(value: string): string[];
+export function validateOptions(context: PartialCreateContext): PartialCreateContext;
 
-/** scaffold */
+export function handleTemplate(context: PartialCreateContext): Promise<void>;
 
-export function readConfig(
-  context: PartialCreateContext,
-  configFlags: { config?: string; configFile?: string }
-): void;
+/** scaffold */
 
 export function dumpErrorContext(context: PartialCreateContext, error: Error): Promise<void>;
 
@@ -57,9 +52,7 @@ export function wrapWithSpinner(
   label: string,
   task: SpinnerTask,
   options?: SpinnerOptions
-): (context: { context: SpinnerContext['context'] } & {
-  errors?: Error[]
-}) => Promise<void>;
+): (args: { gasket?: Gasket; context: SpinnerContext['context'] }) => Promise<void>;
 
 /**
  * Wraps a task with a spinner, using both gasket and context.
@@ -85,44 +78,12 @@ export function spinnerAction(params: {
   spinner?: Ora
 }): Promise<void>;
 
-export function execute(params: { gasket: Gasket, context: PartialCreateContext } & {
-  errors?: Error[]
-}): Promise<void>;
-
-/** sacaffold/actions */
+export function execute(args: { gasket?: Gasket; context: PartialCreateContext }): Promise<void>;
 
-export function createHooks(params: { gasket?: Gasket; context: PartialCreateContext }): Promise<void>;
-
-export function chooseAppDescription(context: PartialCreateContext, prompt: CreatePrompt): Promise<void>;
-export function choosePackageManager(context: PartialCreateContext, prompt: CreatePrompt): Promise<void>;
-export function chooseTestPlugins(context: PartialCreateContext, prompt: CreatePrompt): Promise<void>;
-export function promptForTestPlugin(
-  prompt: CreatePrompt,
-  message: string,
-  isDefault: boolean
-): Promise<string | null>;
-export function allowExtantOverwriting(context: PartialCreateContext, prompt: CreatePrompt): Promise<void>;
-export function globalPrompts(params: { context: PartialCreateContext }): Promise<void>;
-
-export function promptHooks(params: { gasket?: Gasket; context: PartialCreateContext }): Promise<void>;
-export function execPluginPrompts(gasket: Gasket, context: PartialCreateContext): Promise<void>;
+/** scaffold/actions */
 
 export function mkDir({ context, spinner }: { context: CreateContext, spinner: Ora }): Promise<void>;
 
-export function setupPkg(params: { context: PartialCreateContext }): Promise<void>;
-
-export function writePkg(params: { context: PartialCreateContext }): Promise<void>;
-
-export type Descriptior = {
-  pattern: string;
-  base: string;
-  srcFile: string;
-  targetFile: string;
-  target: string;
-  from: string;
-  overrides?: string;
-}
-
 /** Templates */
 export function loadTemplate(params: { context: PartialCreateContext }): Promise<void>;
 export function copyTemplate(params: { context: PartialCreateContext }): Promise<void>;
@@ -130,27 +91,6 @@ export function customizeTemplate(params: { context: PartialCreateContext }): Pr
 export function installTemplateDeps(params: { context: PartialCreateContext }): Promise<void>;
 export function gitInit(params: { context: PartialCreateContext }): Promise<void>;
 
-/** File Generation */
-export function generateFiles({ context, spinner }: { context: CreateContext, spinner: Ora }): Promise<void>;
-export function performGenerate(context: CreateContext, descriptors: Descriptior[]): boolean[];
-export function getDescriptors(context: CreateContext): Promise<Descriptior[]>;
-export function assembleDescriptors(dest: string, from: string, pattern: string, srcPaths: string[]): Descriptior[];
-export function reduceDescriptors(descriptors: Descriptior[]): Descriptior[];
-
-export function writeGasketConfig(params: { context: PartialCreateContext }): Promise<void>;
-export function writeImports(imports: object | null): string;
-export function writeExpressions(expressions: string[] | null): string;
-export function createInjectionAssignments(config: object, assignments: (object | null)): string;
-export function cleanupFields(config: ConfigBuilder<>): void;
-export function writePluginImports(plugins: string[]): string;
-export function replaceInjectionAssignments(content: string, assignments: (object | null)): string;
-
-export function installModules(params: { context: PartialCreateContext }): Promise<void>;
-
-export function linkModules(params: { context: CreateContext, spinner: Ora }): Promise<void>;
-
-export function postCreateHooks(params: { gasket?: Gasket, context: PartialCreateContext }): Promise<void>;
-
 export function printReport(params: {
   context: PartialCreateContext
 }): Promise<void>;

package/lib/scaffold/actions/git-init.js

@@ -3,7 +3,7 @@ import { runShellCommand } from '@gasket/utils';
 
 /**
  * Initialize git repository, create main branch, and make initial commit
- * @type {import('../../internal.d.js').gitInit}
+ * @type {import('../../internal.d.ts').gitInit}
  */
 async function gitInit({ context }) {
   try {

package/lib/scaffold/actions/mkdir.js

@@ -5,7 +5,7 @@ import { withSpinner } from '../with-spinner.js';
  * Validates this instance can execute without common blockers:
  * - Target destination on disk is available. Validate by acquiring
  * a lock through `mkdir`.
- * @type {import('../../internal.js').mkDir}
+ * @type {import('../../internal.d.ts').mkDir}
  */
 async function mkDir({ context, spinner }) {
   const { dest, relDest, extant, destOverride } = context;