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

package/lib/index.d.ts

@@ -0,0 +1,309 @@
+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>;
+  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> {
+  /**
+   * 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.
+   */
+  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 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 type CreatePrompt = PromptModule;
+
+declare module 'create-gasket-app' {
+  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;
+
+    /** Use to add content to the README.md */
+    readme: Readme;
+  }
+}
+
+export interface ActionWrapperParams {
+  gasket: GasketEngine;
+  context: CreateContext;
+  spinner?: any;
+}
+
+declare module '@gasket/core' {
+
+  export interface HookExecTypes {
+    presetPrompt(
+      context: CreateContext,
+      utils: {
+        prompt: CreatePrompt;
+      }
+    ): Promise<void>;
+    presetConfig(context: CreateContext): Promise<CreateContext['presetConfig']>;
+    prompt(
+      context: CreateContext,
+      utils: {
+        prompt: CreatePrompt;
+      }
+    ): 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();

package/lib/scaffold/action-wrapper.js

@@ -0,0 +1,37 @@
+import ora from 'ora';
+
+/**
+ * Decorate a create action with spinner.
+ * If an action throws, a fail spinner will render for the step, regardless of
+ * if the spinner was started or not.
+ *
+ * @param {String} label - Label for the spinner
+ * @param {Function} fn - Action to wrap
+ * @param {Boolean} startSpinner - Should the spinner start
+ * @returns {Function} decorated action
+ */
+export default function withSpinner(label, fn, { startSpinner = true } = {}) {
+  /**
+   * Decorated function
+   *
+   * @param {ActionWrapperParams} params - ActionWrapperParams
+   * @param {GasketEngine} params.gasket - Gasket config
+   * @param {CreateContext} params.context - Create context
+   * @returns {Promise} promise
+   */
+  async function wrapper({ gasket = {}, context }) {
+    const spinner = ora(label);
+    if (startSpinner) spinner.start();
+    try {
+      await fn({ gasket, context, spinner });
+      if (spinner.isSpinning) spinner.succeed();
+    } catch (err) {
+      spinner.fail();
+      context.errors.push(err.stack);
+      throw err;
+    }
+  }
+
+  wrapper.wrapped = fn;
+  return wrapper;
+}

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

@@ -0,0 +1,27 @@
+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 }) {
+  const { plugins = [], warnings } = context;
+
+  const files = new Files();
+  const readme = new Readme();
+  const gasketConfig = ConfigBuilder.create({}, { orderBy: ['plugins'], warnings, plugins });
+  Object.assign(context, { files, readme, gasketConfig });
+
+  await gasket.execApply('create', async function applyCreate(plugin, handler) {
+    await handler(context.runWith(plugin));
+  });
+}
+
+export default action('Execute create hooks', createHooks);

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

@@ -0,0 +1,189 @@
+import { default as diagnostics } from 'diagnostics';
+const debug = diagnostics('gasket:cli:generate-files');
+import fs from 'fs/promises';
+import { promisify } from 'util';
+import Handlebars from 'handlebars';
+import path from 'path';
+import mkdirp from 'mkdirp';
+import chalk from 'chalk';
+const { dim } = chalk;
+import action from '../action-wrapper.js';
+import * as syncGlob from 'glob';
+const glob = promisify(syncGlob.default);
+
+const flatten = (acc, values) => (acc || []).concat(values);
+const reSep = /[/\\]+/;
+const joinSep = pthArr => pthArr.join(path.sep);
+const splitSep = pthStr => pthStr.split(reSep);
+
+/**
+ * Find all duplicate target files and reduce to single descriptor.
+ * Keeps track of overrides.
+ * Last in wins.
+ *
+ * @param {object[]} descriptors - Details about files to generate
+ * @returns {object[]} descriptors
+ */
+function reduceDescriptors(descriptors) {
+  const reduced = descriptors.reduce((acc, desc) => {
+    const { target } = desc;
+    if (acc.has(target)) {
+      const prev = acc.get(target);
+      if (prev.from !== desc.from) {
+        debug(`Using "${target}" from ${desc.from} instead of ${prev.from}`);
+        desc.overrides = prev.from;
+      }
+    }
+    acc.set(target, desc);
+    return acc;
+  }, new Map());
+
+  return Array.from(reduced.values());
+}
+
+/**
+ * Assemble the description objects from glob results
+ *
+ * @param {string} dest - app destination
+ * @param {string} from - Plugin source name
+ * @param {string} pattern - pattern to glob
+ * @param {string[]} srcPaths - resulting paths from glob
+ * @returns {object[]} descriptors
+ */
+function assembleDescriptors(dest, from, pattern, srcPaths) {
+  const output = joinSep(splitSep(dest));
+  const baseParts = splitSep(path.resolve(pattern.replace(/[/\\]+\.?\*.*$/, '')));
+  const base = joinSep(baseParts);
+  return srcPaths.map((srcPath) => {
+    const parts = splitSep(srcPath);
+    const srcFile = joinSep(parts);
+    const target = joinSep(parts.slice(baseParts.length)).replace('.template', '');
+    return {
+      pattern,
+      base,
+      srcFile,
+      targetFile: joinSep([output, target]),
+      target,
+      from
+    };
+  });
+}
+
+/**
+ * Build a list of descriptions of all files we want to generate
+ *
+ * @param {CreateContext} context - Create context
+ * @returns {object[]} descriptors
+ */
+async function getDescriptors(context) {
+  const { dest, files } = context;
+  const descriptors = (
+    await Promise.all(files.globSets.map(async set => {
+      const { globs, source } = set;
+      const matches = await Promise.all(globs.map(async pattern => {
+        pattern = splitSep(pattern).join('/');  // Glob uses / for all OS's
+        const srcPaths = await glob(pattern, { nodir: true });
+        return assembleDescriptors(dest, source.name, pattern, srcPaths);
+      }));
+      return matches.reduce(flatten);
+    }))
+  ).reduce(flatten);
+
+  return reduceDescriptors(descriptors);
+}
+
+/**
+ * Read file content, apply templating, then write out target file.
+ *
+ * @param {CreateContext} context - Create context
+ * @param {object[]} descriptors - Details about files to generate
+ * @returns {boolean} hasWarnings
+ */
+async function performGenerate(context, descriptors) {
+  const { warnings, errors, generatedFiles } = context;
+  let hasWarning = false;
+  let hasError = false;
+
+  const handlebars = Handlebars.create();
+  handlebars.registerHelper('json', JSON.stringify);
+  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));
+
+  await Promise.all(descriptors.map(async desc => {
+    const targetDir = path.dirname(desc.targetFile);
+    let content;
+
+    try {
+      const source = await fs.readFile(desc.srcFile, { encoding: 'utf8' });
+      content = source;
+      try {
+        content = handlebars.compile(source)(context);
+      } catch (compileErr) {
+        hasWarning = true;
+        warnings.push(`Error templating ${desc.targetFile}: ${compileErr.message}`);
+      }
+    } catch (readErr) {
+      if (readErr.code === 'EISDIR') {
+        // Skipping directory errors.
+        // node-glob seems to incorrectly captures some directories on Windows
+        hasWarning = true;
+        warnings.push(`Directory matched as template file: ${desc.targetFile}`);
+      } else {
+        hasError = true;
+        errors.push(`Error reading template ${desc.srcFile}: ${readErr.message}`);
+      }
+    }
+    if (!content) return;
+
+    try {
+      await mkdirp(targetDir);
+      try {
+        await fs.writeFile(desc.targetFile, content, { encoding: 'utf8' });
+        const message = desc.target + (desc.overrides ? dim(` – from ${desc.from}`) : '');
+        generatedFiles.add(message);
+      } catch (writeErr) {
+        hasError = true;
+        errors.push(`Error writing ${desc.targetFile}: ${writeErr.message}`);
+      }
+    } catch (err) {
+      hasError = true;
+      errors.push(`Error creating directory ${targetDir}: ${err.message}`);
+    }
+  }));
+
+  return [hasWarning, hasError];
+}
+
+/**
+ * Generate the app files and templates using context
+ *
+ * @param {CreateContext} context - Create context
+ * @param {Spinner} spinner - Spinner
+ * @returns {Promise} promise
+ */
+async function generateFiles({ context, spinner }) {
+  const { files } = context;
+
+  if (!files.globSets.length) {
+    return;
+  }
+
+  let descriptors = await getDescriptors(context);
+  descriptors = reduceDescriptors(descriptors);
+  const [hasWarnings, hasError] = await performGenerate(context, descriptors);
+
+  if (hasWarnings) spinner.warn();
+  if (hasError) spinner.fail();
+}
+
+export default action('Generate app contents', generateFiles);
+// exported for unit testing
+export const _getDescriptors = getDescriptors;
+export const _assembleDescriptors = assembleDescriptors;