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

package/lib/scaffold/actions/global-prompts.js

@@ -0,0 +1,153 @@
+import inquirer from 'inquirer';
+import action from '../action-wrapper.js';
+
+/**
+ * What is your app description?
+ *
+ * @param {CreateContext} context - Create context
+ * @param {function} prompt - function to prompt user
+ * @returns {Promise} promise
+ */
+async function chooseAppDescription(context, prompt) {
+  if (!('appDescription' in context)) {
+    const { appDescription } = await prompt([
+      {
+        name: 'appDescription',
+        message: 'What is your app description?',
+        type: 'input',
+        default: 'A basic gasket app'
+      }
+    ]);
+
+    Object.assign(context, { appDescription });
+  }
+}
+
+/**
+ * What package manager do you want to use?
+ *
+ * @param {CreateContext} context - Create context
+ * @param {function} prompt - function to prompt user
+ * @returns {Promise} promise
+ */
+async function choosePackageManager(context, prompt) {
+  const packageManager =
+    context.packageManager ||
+    (
+      await prompt([
+        {
+          name: 'packageManager',
+          message: 'Which packager would you like to use?',
+          type: 'list',
+          choices: [{ name: 'npm' }, { name: 'pnpm' }, { name: 'yarn' }]
+        }
+      ])
+    ).packageManager;
+
+  const installCmd = context.installCmd || `${packageManager} install`;
+
+  const localCmd = context.localCmd || `${packageManager} run local`;
+
+  Object.assign(context, {
+    packageManager,
+    installCmd,
+    localCmd
+  });
+}
+
+/**
+ * Choose your unit test suite and integration test suite
+ *
+ * @param {CreateContext} context - Create context
+ * @param {function} prompt - function to prompt user
+ * @returns {Promise} promise
+ */
+async function chooseTestPlugins(context, prompt) {
+  const knownTestPlugins = {
+    unit: { mocha: '@gasket/plugin-mocha', jest: '@gasket/plugin-jest' },
+    integration: { cypress: '@gasket/plugin-cypress' }
+  };
+
+  const testTypes = ['unit', 'integration'];
+  const testPlugins = [];
+
+  if (!('testPlugins' in context)) {
+    for (const type of testTypes) {
+      if (type + 'TestSuite' in context) {
+        const testSuite = knownTestPlugins[type][context[type + 'TestSuite']];
+        if (testSuite) testPlugins.push(testSuite);
+      } else {
+        const plugin = await promptForTestPlugin(
+          prompt,
+          `Choose your ${type} test suite`,
+          Object.entries(knownTestPlugins[type]).map(([name, value]) => ({ name, value }))
+        );
+
+        if (plugin) testPlugins.push(plugin);
+      }
+    }
+
+    if (testPlugins.length > 0) {
+      Object.assign(context, { testPlugins });
+    }
+  }
+}
+
+async function promptForTestPlugin(prompt, message, choices) {
+  const { testPlugin } = await prompt([
+    {
+      name: 'testPlugin',
+      message,
+      type: 'list',
+      choices: [{ name: 'none', value: 'none' }, ...choices]
+    }
+  ]);
+
+  return testPlugin !== 'none' ? testPlugin : null;
+}
+
+/**
+ * Given that gasket is creating in an already existing directory, it should
+ * confirm with the user that it's intentionally overwriting that directory
+ *
+ * @param  {CreateContext} context - Create context
+ * @param {function} prompt - function to prompt user
+ * @returns {Promise} promise
+ */
+async function allowExtantOverwriting(context, prompt) {
+  const { dest, extant } = context;
+  if (extant && !('destOverride' in context)) {
+    const { destOverride } = await prompt([
+      {
+        name: 'destOverride',
+        type: 'confirm',
+        message: `Override contents of ${dest} ?`,
+        default: true
+      }
+    ]);
+
+    Object.assign(context, { destOverride });
+  }
+}
+
+export const questions = [
+  chooseAppDescription,
+  choosePackageManager,
+  chooseTestPlugins,
+  allowExtantOverwriting
+];
+
+/**
+ * Fire off prompts for user input
+ *
+ * @param {CreateContext} context - Create context
+ * @returns {Promise} promise
+ */
+async function globalPrompts({ context }) {
+  const prompt = context.prompts ? inquirer.createPromptModule() : () => ({});
+  for (var fn of questions) {
+    await fn(context, prompt);
+  }
+}
+
+export default action('Global prompts', globalPrompts, { startSpinner: false });

package/lib/scaffold/actions/index.js

@@ -0,0 +1,33 @@
+import mkDir from './mkdir.js';
+import loadPreset from './load-preset.js';
+import globalPrompts from './global-prompts.js';
+import setupPkg from './setup-pkg.js';
+import writePkg from './write-pkg.js';
+import installModules from './install-modules.js';
+import linkModules from './link-modules.js';
+import writeGasketConfig from './write-gasket-config.js';
+import presetPromptHooks from './preset-prompt-hooks.js';
+import presetConfigHooks from './preset-config-hooks.js';
+import promptHooks from './prompt-hooks.js';
+import createHooks from './create-hooks.js';
+import generateFiles from './generate-files.js';
+import postCreateHooks from './post-create-hooks.js';
+import printReport from './print-report.js';
+
+export {
+  mkDir,
+  loadPreset,
+  globalPrompts,
+  setupPkg,
+  writePkg,
+  installModules,
+  linkModules,
+  writeGasketConfig,
+  presetPromptHooks,
+  presetConfigHooks,
+  promptHooks,
+  createHooks,
+  postCreateHooks,
+  generateFiles,
+  printReport
+};

package/lib/scaffold/actions/install-modules.js

@@ -0,0 +1,15 @@
+import action from '../action-wrapper.js';
+
+/**
+ * Installs node_modules using the selected package manager
+ *
+ * @param {CreateContext} context - Create context
+ * @returns {Promise} promise
+ */
+async function installModules({ context }) {
+  const { pkgManager } = context;
+
+  await pkgManager.install();
+}
+
+export default action('Install node modules', installModules);

package/lib/scaffold/actions/link-modules.js

@@ -0,0 +1,19 @@
+import action from '../action-wrapper.js';
+
+/**
+ * Links local packages using the selected package manager
+ *
+ * @param {CreateContext} context - Create context
+ * @param {Spinner} spinner - Spinner
+ * @returns {Promise} promise
+ */
+async function linkModules({ context, spinner }) {
+  const { pkgLinks, pkgManager } = context;
+
+  if (pkgLinks && pkgLinks.length) {
+    spinner.start();
+    await pkgManager.link(pkgLinks);
+  }
+}
+
+export default action('Link node modules', linkModules, { startSpinner: false });

package/lib/scaffold/actions/load-preset.js

@@ -0,0 +1,60 @@
+import path from 'path';
+import os from 'os';
+import action from '../action-wrapper.js';
+import { default as gasketUtils } from '@gasket/utils';
+import { mkdtemp } from 'fs/promises';
+import { createRequire } from 'module';
+const require = createRequire(import.meta.url);
+const hasVersionOrTag = /@([\^~]?\d+\.\d+\.\d+(?:-[\d\w.-]+)?|[\^~]?\d+\.\d+\.\d+|[a-zA-Z]+|file:.+)$/;
+
+/**
+ * loadPresets - Load presets to temp directory
+ * @param {CreateContext} context - Create context
+ */
+async function loadPresets({ context }) {
+  const tmpDir = await mkdtemp(path.join(os.tmpdir(), `gasket-create-${context.appName}`));
+  context.tmpDir = tmpDir;
+
+  const modPath = path.join(tmpDir, 'node_modules');
+  const pkgManager = new gasketUtils.PackageManager({
+    packageManager: context.packageManager,
+    dest: tmpDir
+  });
+  const pkgVerb = pkgManager.manager === 'npm' ? 'install' : 'add';
+
+  const remotePresets = context.rawPresets.map(async preset => {
+    const parts = hasVersionOrTag.test(preset) && preset.split('@').filter(Boolean);
+    const name = parts ? `@${parts[0]}` : preset;
+    const version = parts ? `@${parts[1]}` : '@latest';
+
+    try {
+      // Install the preset
+      await pkgManager.exec(pkgVerb, [`${name}${version}`]);
+      // Get the package file
+      const pkgFile = require(path.join(modPath, name, 'package.json'));
+      // Import the preset via the package file attrs, name and main
+      // We can't specify the cwd for the import, so we need to use the full path
+      // expects type:module & "main": "lib/fullpath.js"
+      const mod = await import(`${modPath}/${name}/${pkgFile.main}`);
+      return mod.default?.default || mod.default || mod;
+    } catch (err) {
+      throw new Error(`Failed to install preset ${name}${version}: ${err.message}`);
+    }
+  });
+
+  const localPresets = context.localPresets.map(async localPresetPath => {
+
+    try {
+      await pkgManager.exec(pkgVerb, [localPresetPath]);
+      const pkgFile = require(path.join(localPresetPath, 'package.json'));
+      const mod = await import(`${modPath}/${pkgFile.name}/${pkgFile.main}`);
+      return mod.default?.default || mod.default || mod;
+    } catch (err) {
+      throw new Error(`Failed to install local preset ${localPresetPath}`);
+    }
+  });
+
+  context.presets = await Promise.all([...remotePresets, ...localPresets]);
+}
+
+export default action('Load presets', loadPresets);

package/lib/scaffold/actions/mkdir.js

@@ -0,0 +1,30 @@
+import { mkdir } from 'fs/promises';
+import action from '../action-wrapper.js';
+
+/**
+ * Validates this instance can execute without common blockers:
+ *   - Target destination on disk is available. Validate by acquiring
+ *     a lock through `mkdir`.
+ *
+ * @param {CreateContext} context - Create context
+ * @param {Spinner} spinner - Spinner
+ * @returns {Promise} promise
+ */
+async function mkDir({ context, spinner }) {
+  const { dest, relDest, extant, destOverride } = context;
+
+  // At this point, either the directory does not exist, or the user has
+  // confirmed that this directory can be overwritten, so we can proceed.
+
+  if (!extant) {
+    spinner.text = `Make directory: ${relDest}`;
+    await mkdir(dest);
+  } else {
+    spinner.text = `Existing directory: ${relDest}`;
+    if (!destOverride) {
+      throw new Error(`Directory ${relDest} was not allowed to be overwritten.`);
+    }
+  }
+}
+
+export default action('Set up directory', mkDir);

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

@@ -0,0 +1,31 @@
+import action from '../action-wrapper.js';
+import { runShellCommand } from '@gasket/utils';
+
+/**
+ * Executes the `postCreate` hook for all registered plugins.
+ *
+ * @param {GasketEngine} gasket - Gasket API
+ * @param {CreateContext} context - Create context
+ * @returns {Promise} promise
+ */
+async function postCreateHooks({ gasket, context }) {
+  const { dest } = context;
+
+  /**
+   * Run an npm script in the context of the created application
+   * @param  {String} script name of script
+   * @returns {Promise} A promise represents if npm succeeds or fails.
+   */
+  async function runScript(script) {
+    return await runShellCommand('npm', ['run', script], { cwd: dest });
+  }
+
+  /**
+   * An object with one value for now, so adding more utilities
+   * in future is easy.
+   */
+  const utils = { runScript };
+  await gasket.exec('postCreate', context, utils);
+}
+
+export default action('Execute postCreate hooks', postCreateHooks);

package/lib/scaffold/actions/preset-config-hooks.js

@@ -0,0 +1,13 @@
+import action from '../action-wrapper.js';
+
+/**
+ * presetConfigHooks - exec `presetConfig` hook
+ * @param {Gasket} gasket - Preset gasket instance
+ * @param {CreateContext} context - Create context
+ */
+async function presetConfigHooks({ gasket, context }) {
+  const config = await gasket.execWaterfall('presetConfig', context);
+  Object.assign(context.presetConfig, config);
+}
+
+export default action('Preset Config', presetConfigHooks, { startSpinner: false });

package/lib/scaffold/actions/preset-prompt-hooks.js

@@ -0,0 +1,17 @@
+import inquirer from 'inquirer';
+import action from '../action-wrapper.js';
+
+/**
+ * presetPromptHooks - exec `presetPrompt` hook
+ * @param {Gasket} gasket - Preset gasket instance
+ * @param {CreateContext} context - Create context
+ */
+async function presetPromptHooks({ gasket, context }) {
+  const prompt = context.prompts ? inquirer.createPromptModule() : () => ({});
+
+  const nextContext = await gasket.execWaterfall('presetPrompt', context, { prompt });
+
+  Object.assign(context, nextContext);
+}
+
+export default action('Preset prompts', presetPromptHooks, { startSpinner: false });

package/lib/scaffold/actions/print-report.js

@@ -0,0 +1,89 @@
+import pkg from 'chalk';
+const { bold } = pkg;
+import action from '../action-wrapper.js';
+import { logo } from '../../utils/index.js';
+
+/**
+ * Logs a new line in the console
+ * @private
+ */
+const newline = () => {
+  console.log('');
+};
+
+/**
+ * Converts a camelCase string to Space Case
+ * @see: https://stackoverflow.com/questions/4149276/javascript-camelcase-to-regular-form?answertab=active#tab-top
+ *
+ * @param {string} str - camelCase string to fixup
+ * @returns {string} result
+ * @private
+ */
+const toSpaceCase = str => str.replace(/([A-Z])/g, ' $1')
+  .replace(/^./, s => s.toUpperCase());
+
+/**
+ * Builds the report object from context
+ *
+ * @param {CreateContext} context - Create context
+ * @returns {Object} report
+ * @private
+ */
+function buildReport(context) {
+  const {
+    appName,
+    dest,
+    fullPresets,
+    plugins,
+    generatedFiles: generatedFilesSet,
+    messages,
+    warnings,
+    errors,
+    nextSteps
+  } = context;
+
+  const generatedFiles = Array.from(generatedFilesSet);
+  generatedFiles.sort();
+
+  return {
+    appName,
+    output: dest,
+    presets: fullPresets,
+    plugins,
+    generatedFiles,
+    messages,
+    warnings,
+    errors,
+    nextSteps
+  };
+}
+
+/**
+ * Outputs create command details to the console
+
+ * @param {CreateContext} context - Create context
+ */
+async function printReport({ context }) {
+  const report = buildReport(context);
+  const { warnings, errors } = context;
+
+  console.log(`✨Success!
+
+Finished with ${warnings.length} warnings and ${errors.length} errors using
+` + logo);
+
+  Object.entries(report).forEach(([k, v]) => {
+    if (!v || !v.length) return;
+    newline();
+    console.log(`${bold(toSpaceCase(k))}`);
+    if (Array.isArray(v)) {
+      v.map(o => console.log(`  ${o}`));
+    } else {
+      console.log(`  ${v}`);
+    }
+  });
+
+  newline();
+}
+
+export default action('Print report', printReport, { startSpinner: false });

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

@@ -0,0 +1,43 @@
+import inquirer from 'inquirer';
+import action from '../action-wrapper.js';
+
+/**
+ * Initializes engine with provide preset and plugins
+ * to execute their prompt lifecycle hooks.
+ *
+ * @param {CreateContext} context - Create context
+ * @param {String[]} plugins - plugins to load
+ * @param {String} [presets] - presets to load
+ * @returns {Promise} promise
+ * @private
+ */
+async function execPluginPrompts(gasket, context) {
+  //
+  // @see: https://github.com/SBoudrias/Inquirer.js/#inquirercreatepromptmodule---prompt-function
+  //
+  const prompt = context.prompts ? inquirer.createPromptModule() : () => ({});
+  const nextContext = await gasket.execWaterfall('prompt', context, { prompt });
+  //
+  // Ensure the original context is transformed in case a prompt returns a new object
+  //
+  Object.assign(context, nextContext);
+}
+
+/**
+ * Executes the `prompt` hook for all registered plugins.
+ * Adds `prompt` util function for prompting features.
+ *
+ * @param {GasketEngine} gasket - Gasket API
+ * @param {CreateContext} context - Create context
+ * @returns {Promise} promise
+ */
+async function promptHooks({ gasket, context }) {
+  //
+  // Because `execPluginPrompts` is recursively, we need to start it
+  // with the processPlugins and presets from our initial context
+  //
+  const { plugins } = context;
+  await execPluginPrompts(gasket, context, plugins);
+}
+
+export default action('Plugin prompts', promptHooks, { startSpinner: false });

package/lib/scaffold/actions/setup-pkg.js

@@ -0,0 +1,34 @@
+import action from '../action-wrapper.js';
+import { ConfigBuilder } from '../config-builder.js';
+import { default as gasketUtils } from '@gasket/utils';
+import { createRequire } from 'module';
+const require = createRequire(import.meta.url);
+const { dependencies } = require('../../../package.json');
+
+/**
+ * Initializes the ConfigBuilder builder and adds to context.
+ *
+ * @param {CreateContext} context - Create context
+ * @returns {Promise} promise
+ */
+async function setupPkg({ context }) {
+  const { appName, appDescription, warnings } = context;
+
+  const pkg = ConfigBuilder.createPackageJson({
+    name: appName,
+    version: '0.0.0',
+    description: appDescription,
+    type: 'module'
+  }, { warnings });
+
+  // Add critical dependencies
+  pkg.add('dependencies', {
+    '@gasket/core': dependencies['@gasket/core'],
+    '@gasket/utils': dependencies['@gasket/utils']
+  });
+
+  const pkgManager = new gasketUtils.PackageManager(context);
+  Object.assign(context, { pkg, pkgManager });
+}
+
+export default action('Set up package.json', setupPkg, { startSpinner: false });

package/lib/scaffold/actions/write-gasket-config.js

@@ -0,0 +1,119 @@
+import { default as JSON5 } from 'json5';
+import path from 'path';
+import { writeFile } from 'fs/promises';
+import action from '../action-wrapper.js';
+
+/**
+ * writePluginImports - Write string imports as value(s)
+ * @param {string[]} plugins - Array of plugin import names
+ * @returns {string} - Array of plugin imports as string
+ */
+function writePluginImports(plugins) {
+  return plugins.reduce((acc, cur, index) => {
+    acc += `\t\t${cur}${index < plugins.length - 1 ? ',\n' : ''}`;
+    return acc;
+  }, '');
+}
+
+/**
+ * writeImports - Write imports to file using key value pairs
+ * @param {{[pluginImport: string]: string}[]} imports - Array of key value pairs for imports
+ * @returns {string} - import declarations as string
+ */
+function writeImports(imports) {
+  if (!imports) return '';
+  return `${Object.entries(imports).map(([importDef, importPath]) => `import ${importDef} from '${importPath}';`).join('\n')}\n`;
+}
+
+/**
+ * createInjectionAssignments - replace object path with a temp string value
+ * @param {GasketConfigDefinition} config - gasket config object
+ * @param {{ [configKey]: string }} assignments - key value pairs of config keys to replace
+ * @returns {string} - string if assignments is falsy
+ */
+function createInjectionAssignments(config, assignments) {
+  if (!assignments) return '';
+  Object.keys(assignments).forEach((key) => {
+    const keys = key.split('.');
+
+    keys.reduce((acc, cur, index) => {
+      if (index === keys.length - 1) {
+        acc[cur] = `${key}_INJECTION_ASSIGNMENT_REPLACE`;
+        return;
+      }
+      return acc[cur];
+    }, config);
+  });
+}
+
+/**
+ * replaceInjectionAssignments - replace temp string value with actual value
+ * @param {string} content
+ * @param {{ [configKey]: string }} assignments - key value pairs of config keys to replace
+ * @returns {string} - content with replaced values
+ */
+function replaceInjectionAssignments(content, assignments) {
+  if (!assignments) return content;
+  Object.keys(assignments).forEach((key) => {
+    content = content.replace(`'${key}_INJECTION_ASSIGNMENT_REPLACE'`, assignments[key]);
+  });
+
+  return content;
+}
+
+/**
+ * writeExpressions - Write expressions to file
+ * @param {string} expressions - programmatic expressions as string
+ * @returns {string} - expressions as string
+ */
+function writeExpressions(expressions) {
+  if (!expressions) return '';
+  return `${expressions.map((expression) => `${expression}`).join('\n')}\n`;
+}
+
+/**
+ * cleanupFields - Remove fields from config object
+ * @param {GasketConfigDefinition} config - gasket config object
+ */
+function cleanupFields(config) {
+  delete config.fields.imports;
+  delete config.fields.pluginImports;
+  delete config.fields.expressions;
+  delete config.fields.injectionAssignments;
+}
+
+/**
+ * Writes the contents of `pkg` to the app's package.json.
+ *
+ * @param {CreateContext} context - Create context
+ * @returns {Promise} promise
+ */
+async function writeGasketConfig({ context }) {
+  const { dest, gasketConfig, generatedFiles, typescript } = context;
+  const fileName = typescript ? 'gasket.ts' : 'gasket.js';
+  const filePath = path.join(dest, fileName);
+  const plugins = gasketConfig.fields.plugins;
+  const assignments = gasketConfig.fields.injectionAssignments || null;
+  const expressions = gasketConfig.fields.expressions || null;
+  gasketConfig.fields.plugins = 'PLUGIN_REPLACE';
+
+  let contents = '';
+  if (typescript) contents += `import type { GasketConfigDefinition } from '@gasket/core';\n`;
+  contents += `import { makeGasket } from '@gasket/core';\n`;
+  contents += writeImports(gasketConfig.fields.pluginImports);
+  contents += writeImports(gasketConfig.fields.imports);
+  contents += writeExpressions(expressions);
+  createInjectionAssignments(gasketConfig.fields, assignments);
+  cleanupFields(gasketConfig);
+
+  const pluginImports = `[\n${writePluginImports(plugins)}\n  ]`;
+  const typeCoercion = typescript ? ' as GasketConfigDefinition' : '';
+  contents += `\nexport default makeGasket(${JSON5.stringify(gasketConfig.fields, null, 2)}${typeCoercion});\n`;
+  contents = contents.replace('\'PLUGIN_REPLACE\'', pluginImports);
+  contents = replaceInjectionAssignments(contents, assignments);
+
+  await writeFile(filePath, contents, 'utf8');
+  generatedFiles.add(fileName);
+}
+
+export default action('Write gasket config', writeGasketConfig);

package/lib/scaffold/actions/write-pkg.js

@@ -0,0 +1,19 @@
+import path from 'path';
+import { writeFile } from 'fs/promises';
+import action from '../action-wrapper.js';
+
+/**
+ * Writes the contents of `pkg` to the app's package.json.
+ *
+ * @param {CreateContext} context - Create context
+ * @returns {Promise} promise
+ */
+async function writePkg({ context }) {
+  const { dest, pkg, generatedFiles } = context;
+  const fileName = 'package.json';
+  const filePath = path.join(dest, fileName);
+  await writeFile(filePath, JSON.stringify(pkg, null, 2), 'utf8');
+  generatedFiles.add(fileName);
+}
+
+export default action('Write package.json', writePkg);