create-gasket-app 7.0.4 → 7.0.9

package/lib/commands/create.js

@@ -25,9 +25,7 @@ import {
 
 /**
  * Parses comma separated option input to array
- *
- * @param {String} input - option argument
- * @returns {String[]} results
+ * @type {import('../internal').commasToArray}
  */
 const commasToArray = input => input.split(',').map(name => name.trim());
 
@@ -97,10 +95,7 @@ const createCommand = {
 
 /**
  * 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
+ * @type {import('../index').createCommandAction}
  */
 createCommand.action = async function run(appname, options, command) {
   process.env.GASKET_ENV = 'create';

package/lib/index.d.ts

@@ -1,6 +1,7 @@
 import type { GasketConfigDefinition, MaybeAsync, Plugin, GasketEngine } from '@gasket/core';
 import type { PackageManager } from '@gasket/utils';
 import type { PromptModule } from 'inquirer';
+import type ora from 'ora';
 
 export interface Dependencies {
   dependencies?: Record<string, string>;
@@ -25,6 +26,41 @@ export interface PackageJson extends Dependencies {
   homepage?: string;
 }
 
+interface CommandArgument {
+  name: string;
+  description?: string;
+  required?: boolean;
+  default?: any;
+}
+
+interface CommandOption {
+  name: string;
+  description: string;
+  required?: boolean;
+  short?: string;
+  parse?: (value: string) => any;
+  type?: string;
+  conflicts?: string | string[];
+  hidden?: boolean;
+  default?: any;
+}
+
+export function createCommandAction(
+  appname: string,
+  options: CreateCommandOptions,
+  command: Command 
+): Promise<void>;
+
+export interface CreateCommand {
+  id: string;
+  description: string;
+  args: CommandArgument[];
+  action?: createGasketAction;
+  options: CommandOption[];
+  hidden?: boolean;
+  default?: boolean;
+}
+
 export interface ModuleInfo {
   name: string;
   module: any;
@@ -38,18 +74,28 @@ export interface PresetInfo extends ModuleInfo { }
 export interface PluginInfo extends ModuleInfo { }
 
 export interface ConfigBuilder<Config> {
-  /**
-   * fields object
-   */
+  /** fields object */
   fields: { [key: string]: any };
+  original?: { [key: string]: any };
+  source?: Plugin;
+  orderBy?: string[];
+  orderedFields?: string[];
+  objectFields?: string[];
+  semverFields?: string[];
+  blame?: Map<string, string[]>;
+  force?: Set<any>;
+  warnings?: string[];
 
   /**
    * 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.
+   * @param source - Plugin to blame if conflicts arise from this operation.
    */
   extend(
-    fields: Partial<Config> | ((current: Config) => Partial<Config>)
+    fields: Partial<Config> | ((current: Config) => Partial<Config>),
+    source: Plugin
   ): void;
+  extend(fields: Partial<Config> | ((current: Config) => Partial<Config>)): void;
 
   /**
    * Performs an intelligent, domain-aware merge of the `value` for
@@ -57,17 +103,20 @@ export interface ConfigBuilder<Config> {
    *
    * @param key - Field in package.json to add or extend.
    * @param value - Target value to set for key provided.
+   * @param source - Plugin to blame if conflicts arise from this operation.
    * @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>(
+  add<Key extends keyof Config & string>(
     key: Key,
     value: Config[Key],
+    source: Plugin,
     options?: { force?: boolean }
   ): void;
+  add(key: string, value: object, options?: object): void;
 
   /**
    * addPlugin - Add plugin import to the gasket file and use the value in the plugins array
@@ -146,43 +195,177 @@ export interface PackageJsonBuilder extends ConfigBuilder<PackageJson> {
   has(key: keyof PackageJson, value: string): boolean;
 }
 
-export interface Files {
-  add(...args: string[]): void;
+/**
+ * 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 {
+export class 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): Readme;
+  heading(content: string, level?: number): this;
 
   /** Add a markdown sub-heading */
-  subHeading(content: string): Readme;
+  subHeading(content: string): this;
 
   /** Add markdown content */
   content(markdown: string);
 
   /** Add a markdown list */
-  list(items: string[]): Readme;
+  list(items: string[]): this;
 
   /** Add a markdown link - printed in footer */
-  link(content: string, href: string): Readme;
+  link(content: string, href: string): this;
 
   /** Add a markdown code block */
-  codeBlock(content: string, syntax?: string): Readme;
+  codeBlock(content: string, syntax?: string): this;
 
   /** Add markdown file */
-  markdownFile(path: string): Promise<Readme>;
+  markdownFile(path: string): Promise<this>;
 }
 
-export type CreatePrompt = PromptModule;
+type NoopPromptObject = {
+  [key: string]: any;
+};
+type NoopPromptFunction = () => NoopPromptObject;
+export type CreatePrompt = PromptModule | NoopPromptFunction;
+
+export interface CreateCommandOptions {
+  presets?: string[];
+  npmLink?: string[];
+  presetPath?: string[];
+  packageManager?: string;
+  prompts?: boolean;
+  config?: string;
+  configFile?: string;
+}
 
 declare module 'create-gasket-app' {
-  export interface CreateContext {
+  export class CreateContext {
     /** Short name of the app */
     appName: string;
 
@@ -223,9 +406,15 @@ declare module 'create-gasket-app' {
     /** any generated files to show in report */
     generatedFiles: Set<string>;
 
+    /** (INTERNAL) false to skip the prompts */
+    prompts: boolean;
+
     /** Default empty array, populated by load-preset with actual imports */
     presets: Array<Plugin>;
 
+    /** temporary directory */
+    tmpDir: string;
+
     /** Default to object w/empty plugins array to be populated by `presetConfig` hook */
     presetConfig: GasketConfigDefinition;
 
@@ -272,13 +461,16 @@ declare module 'create-gasket-app' {
 
     /** Use to add content to the README.md */
     readme: Readme;
+    
+    constructor(initContext?: Partial<T>);
+    runWith(plugin: Plugin): Proxy<CreateContext>;
   }
 }
 
 export interface ActionWrapperParams {
   gasket: GasketEngine;
   context: CreateContext;
-  spinner?: any;
+  spinner?: ora.Ora;
 }
 
 declare module '@gasket/core' {

package/lib/index.js

@@ -19,6 +19,9 @@ const gasketBin = program
 
 
 async function main() {
+  // Suppress deprecation warning for punycode in node 22
+  // @ts-ignore
+  process.noDeprecation = true;
   const { command, hidden, isDefault } = processCommand(createCommand);
   await warnIfOutdated(pkg.name, pkg.version);
   gasketBin.addCommand(command, { hidden, isDefault });

package/lib/internal.d.ts

@@ -0,0 +1,133 @@
+import { Gasket } from '@gasket/core';
+import type {
+  CreateContext,
+  CreatePrompt,
+  ConfigBuilder,
+  CreateCommand,
+  CommandArgument,
+  CommandOption
+} from './index';
+import type { GasketEngine, Plugin } from '@gasket/core';
+import type ora from 'ora';
+import type { Command, Option } from 'commander';
+
+
+export type PartialCreateContext = Partial<CreateContext>;
+
+export function commasToArray(value: string): string[];
+
+/** scaffold */
+
+export function readConfig(
+  context: PartialCreateContext,
+  configFlags: { config?: string; configFile?: string }
+): void;
+
+export function dumpErrorContext(context: PartialCreateContext, error: Error): Promise<void>;
+
+export function makeCreateContext(argv?: string[], options?: CreateCommandOptions): PartialCreateContext;
+
+export function makeCreateRuntime(context: PartialCreateContext, source: Plugin): Proxy<CreateContext>;
+
+export function spinnerAction({ gasket, context, spinner } : {
+  gasket?: GasketEngine;
+  context?: CreateContext;
+  spinner?: ora.Ora
+}): Promise<void>;
+export function withSpinnerWrapper({ gasket, context } : { gasket: GasketEngine, context: CreateContext }): Promise<void>; 
+export function withSpinner(
+  label: string,
+  fn: spinnerAction,
+  options?: { startSpinner?: boolean }
+): withSpinnerWrapper
+
+/** sacaffold/actions */
+
+export function createHooks({ gasket, context } : { gasket: GasketEngine; context: CreateContext }): Promise<void>;
+
+export function chooseAppDescription(context: CreateContext, prompt: CreatePrompt): Promise<void>;
+export function choosePackageManager(context: CreateContext, prompt: CreatePrompt): Promise<void>;
+export function chooseTestPlugins(context: CreateContext, prompt: CreatePrompt): Promise<void>;
+export function promptForTestPlugin(
+  prompt: CreatePrompt, 
+  message: string, 
+  choices: { name: string; value: string; }[]
+): Promise<string | null>;
+export function allowExtantOverwriting(context: CreateContext, prompt: CreatePrompt): Promise<void>;
+export function globalPrompts({ context } : { context: CreateContext }): Promise<void>;
+
+export function loadPresets({ context } : { context: CreateContext }): Promise<void>;
+
+export function presetPromptHooks({ gasket, context }: { gasket: GasketEngine; context: CreateContext }): Promise<void>;
+
+export function presetConfigHooks({ gasket, context }: { gasket: GasketEngine; context: CreateContext }): Promise<void>;
+
+export function promptHooks({ gasket, context }: { gasket: GasketEngine; context: CreateContext }): Promise<void>;
+export function execPluginPrompts(gasket: GasketEngine, context: CreateContext): Promise<void>;
+
+export function mkDir({ context, spinner }: { context: CreateContext, spinner: ora.Ora }): Promise<void>;
+
+export function setupPkg({ context }: { context: CreateContext }): Promise<void>;
+
+export function writePkg({ context }: { context: CreateContext }): Promise<void>;
+
+export type Descriptior = {
+  pattern: string;
+  base: string;
+  srcFile: string;
+  targetFile: string;
+  target: string;
+  from: string;
+  overrides?: string;
+}
+export function generateFiles({ context, spinner }: { context: CreateContext, spinner: ora.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: sring[]): Descriptior[];
+export function reduceDescriptors(descriptors: Descriptior[]): Descriptior[];
+
+export function writeGasketConfig({ context }: { context: CreateContext }): 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({ context }: { context: CreateContext }): Promise<void>;
+
+export function linkModules({context, spinner}: { context: CreateContext, spinner: ora.Ora }): Promise<void>;
+
+export function postCreateHooks({ gasket, context }: { gasket: GasketEngine, context: CreateContext }): Promise<void>;
+
+export function printReport({ context }: { context: CreateContext }): Promise<void>;
+export function buildReport(context: CreateContext): {
+  appName?: string;
+  output?: string;
+  generatedFiles?: string[];
+  messages?: string[];
+  warnings?: string[];
+  errors?: string[];
+  nextSteps?: string[];
+}
+
+/** utils */
+
+export function processCommand(command: CreateCommand): { command: Command, hidden: boolean, isDefault: boolean };
+export function isValidCommand(command: CreateCommand): boolean;
+
+export function processArgs(args: CommandArgument[]): [string, string?, any?][];
+export function isValidArg(arg: CommandArgument): boolean;
+
+interface OptionDefinition { 
+  options: [string, string];
+  conflicts: CommandOption['conflicts'];
+  hidden: CommandOption['hidden'];
+  required: CommandOption['required'];
+  defaultValue: CommandOption['default'];
+  parse: CommandOption['parse']
+};
+export function isValidOption(option: CommandOption): boolean;
+export function processOptions(options: CommandOption[]): OptionDefinition[]
+
+export function createOption(definition: OptionDefinition): Option

package/lib/scaffold/action-wrapper.js

@@ -4,20 +4,12 @@ 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
+ * @type {import('../internal').withSpinner}
  */
 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
+   * @type {import('../internal').withSpinnerWrapper}
    */
   async function wrapper({ gasket = {}, context }) {
     const spinner = ora(label);

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

@@ -6,17 +6,13 @@ 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
+ * @type {import('../../internal').createHooks}
  */
 async function createHooks({ gasket, context }) {
-  const { plugins = [], warnings } = context;
-
+  const { warnings } = context;
   const files = new Files();
   const readme = new Readme();
-  const gasketConfig = ConfigBuilder.create({}, { orderBy: ['plugins'], warnings, plugins });
+  const gasketConfig = ConfigBuilder.create({}, { orderBy: ['plugins'], warnings });
   Object.assign(context, { files, readme, gasketConfig });
 
   await gasket.execApply('create', async function applyCreate(plugin, handler) {

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

@@ -20,9 +20,7 @@ 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
+ * @type {import('../../internal').reduceDescriptors}
  */
 function reduceDescriptors(descriptors) {
   const reduced = descriptors.reduce((acc, desc) => {
@@ -43,12 +41,7 @@ function reduceDescriptors(descriptors) {
 
 /**
  * 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
+ * @type {import('../../internal').assembleDescriptors}
  */
 function assembleDescriptors(dest, from, pattern, srcPaths) {
   const output = joinSep(splitSep(dest));
@@ -71,9 +64,7 @@ function assembleDescriptors(dest, from, pattern, srcPaths) {
 
 /**
  * Build a list of descriptions of all files we want to generate
- *
- * @param {CreateContext} context - Create context
- * @returns {object[]} descriptors
+ * @type {import('../../internal').getDescriptors}
  */
 async function getDescriptors(context) {
   const { dest, files } = context;
@@ -94,10 +85,7 @@ async function getDescriptors(context) {
 
 /**
  * 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
+ * @type {import('../../internal').performGenerate}
  */
 async function performGenerate(context, descriptors) {
   const { warnings, errors, generatedFiles } = context;
@@ -163,10 +151,7 @@ async function performGenerate(context, descriptors) {
 
 /**
  * Generate the app files and templates using context
- *
- * @param {CreateContext} context - Create context
- * @param {Spinner} spinner - Spinner
- * @returns {Promise} promise
+ * @type {import('../../internal').generateFiles}
  */
 async function generateFiles({ context, spinner }) {
   const { files } = context;

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

@@ -3,10 +3,7 @@ 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
+ * @type {import('../../internal').chooseAppDescription}
  */
 async function chooseAppDescription(context, prompt) {
   if (!('appDescription' in context)) {
@@ -25,10 +22,7 @@ async function chooseAppDescription(context, prompt) {
 
 /**
  * What package manager do you want to use?
- *
- * @param {CreateContext} context - Create context
- * @param {function} prompt - function to prompt user
- * @returns {Promise} promise
+ * @type {import('../../internal').choosePackageManager}
  */
 async function choosePackageManager(context, prompt) {
   const packageManager =
@@ -61,10 +55,7 @@ async function choosePackageManager(context, prompt) {
 
 /**
  * Choose your unit test suite and integration test suite
- *
- * @param {CreateContext} context - Create context
- * @param {function} prompt - function to prompt user
- * @returns {Promise} promise
+ * @type {import('../../internal').chooseTestPlugins}
  */
 async function chooseTestPlugins(context, prompt) {
   const knownTestPlugins = {
@@ -102,6 +93,10 @@ async function chooseTestPlugins(context, prompt) {
   }
 }
 
+/**
+ *
+ * @type {import('../../internal').promptForTestPlugin}
+ */
 async function promptForTestPlugin(prompt, message, choices) {
   const { testPlugin } = await prompt([
     {
@@ -118,10 +113,7 @@ async function promptForTestPlugin(prompt, message, choices) {
 /**
  * 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
+ * @type {import('../../internal').allowExtantOverwriting}
  */
 async function allowExtantOverwriting(context, prompt) {
   const { dest, extant } = context;
@@ -148,12 +140,11 @@ export const questions = [
 
 /**
  * Fire off prompts for user input
- *
- * @param {CreateContext} context - Create context
- * @returns {Promise} promise
+ * @type {import('../../internal').globalPrompts}
  */
 async function globalPrompts({ context }) {
   const prompt = context.prompts ? inquirer.createPromptModule() : () => ({});
+
   for (var fn of questions) {
     await fn(context, prompt);
   }

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

@@ -2,9 +2,7 @@ import action from '../action-wrapper.js';
 
 /**
  * Installs node_modules using the selected package manager
- *
- * @param {CreateContext} context - Create context
- * @returns {Promise} promise
+ * @type {import('../../internal').installModules}
  */
 async function installModules({ context }) {
   const { pkgManager } = context;