/**
 * @author        Vivek M. Chawla <@VivekMChawla>
 * @copyright     2019, Vivek M. Chawla / Salesforce. All rights reserved.
 * @license       BSD-3-Clause For full license text, see the LICENSE file in the repo root or
 *                `https://opensource.org/licenses/BSD-3-Clause`
 * @file          packages/generator/src/generator.ts
 * @summary       Exports `SfdxFalconGenerator` for use with custom Yeoman generators.
 * @description   Exports an abstract class that extends Yeoman's `Generator` class, adding
 *                customized support for SFDX-Falcon specific tools and capabilities.
 */
import * as Generator from 'yeoman-generator';
import { ExternalContext } from '@sfdx-falcon/builder';
import { SfdxEnvironment } from '@sfdx-falcon/environment';
import { SfdxFalconInterview } from '@sfdx-falcon/interview';
import { SfdxFalconResult } from '@sfdx-falcon/status';
import { GeneratorStatus } from '@sfdx-falcon/status';
import { GeneratorOptions } from '@sfdx-falcon/command';
import { SfdxEnvironmentRequirements } from '@sfdx-falcon/environment';
import { SfdxFalconTableData } from '@sfdx-falcon/status';
import { ConfirmationAnswers } from '@sfdx-falcon/types';
import { JsonMap } from '@sfdx-falcon/types';
/**
 * Interface. Collection of objects that represent the Answers that will be leveraged by an
 * `SfdxFalconGenerator`.
 */
export interface Answers<T extends JsonMap> {
    /** Required. The set of default answers for the Interview of an `SfdxFalconGenerator`. */
    default: T;
    /** Required. The set of answers provided by the user for the Interview of an `SfdxFalconGenerator`. */
    user: T;
    /** Required. The set of final answers for the Interview of an `SfdxFalconGenerator`. In other words, the merging of User and Default answers in case the user did not supply some answers. */
    final: T;
    /** Required. Special set of answers. Provides a means to send meta values (usually template tags) to EJS templates. */
    meta: T;
    /** Required. The set of answers provided when the user is asked to proceed/retry/abort something. */
    confirmation: ConfirmationAnswers;
}
/**
 * Interface. Collection of message strings that are displayed at various times during the execution
 * of an `SfdxFalconGenerator`.
 */
export interface GeneratorMessages {
    /** Required. Message that will be displayed by the opening Banner when the generator is loaded. */
    opening: string;
    /** Required. Message shown to the user before the interview starts during the prompting() run-loop function. */
    preInterview: string;
    /** Required. Message shown to the user to help them decide to exit the prompting() run-loop function. */
    confirmation: string;
    /** Required. Message shown to the user after the interview ends but before the prompting() run-loop function exits. */
    postInterview: string;
    /** Required. Message that will be displayed by the `end()` run-loop function upon successful completion of the Generator. */
    success: string;
    /** Required. Message that will be displayed by the `end()` run-loop function upon failure of the Generator. */
    failure: string;
    /** Required. Message that will be displayed by the `end()` run-loop function upon partial success of the Generator.  */
    warning: string;
}
/**
 * Interface. Collection of requirements for the initialization process of an `SfdxFalconGenerator`.
 */
export interface GeneratorRequirements {
    gitEnvReqs: object;
    sfdxEnvReqs: SfdxEnvironmentRequirements;
    localEnvReqs: object;
}
/**
 * Interface. Collection of status `boolean` variables that reflect the status of various Yeoman
 * run-loop functions.
 */
export interface RunLoopStatus {
    /** Required. Indicates that the `initializing()` run-loop function has completed successfully. */
    initializingComplete: boolean;
    /** Required. Indicates that the `prompting()` run-loop function has completed successfully. */
    promptingComplete: boolean;
    /** Required. Indicates that the `configuring()` run-loop function has completed successfully. */
    configuringComplete: boolean;
    /** Required. Indicates that the `writing()` run-loop function has completed successfully. */
    writingComplete: boolean;
    /** Required. Indicates that the `install()` run-loop function has completed successfully. */
    installComplete: boolean;
    /** Required. Indicates that the `end()` run-loop function completed successfully. */
    endComplete: boolean;
}
/**
 * @class       SfdxFalconGenerator
 * @extends     Generator
 * @summary     Abstract base class class for building Yeoman Generators for SFDX-Falcon commands.
 * @description Classes that extend `SfdxFalconGenerator` must provide a type parameter to
 *              ensure that the "answers" family of member variables (`defaultAnswers`,
 *              `userAnswers`, `metaAnswers`, and `finalAnswers`) has the appropriate interface
 *              type which defines the answers that are relevant to a concrete child class.
 * @public @abstract
 */
export declare abstract class SfdxFalconGenerator<T extends JsonMap> extends Generator {
    /** Debug namespace of the derived class. Makes it easier to debug superclass operations when extending `SfdxFalconGenerator`. */
    protected readonly dbgNs: string;
    /** Name of the CLI command that kicked off this Generator. */
    protected readonly commandName: string;
    /** External Context describing an instance of the derived class. Used by Builder-derived classes. */
    protected readonly extCtx: ExternalContext;
    /** Reference to the package manifest (`package.json`) of the module that owns the class that implements the command entrypoint. */
    protected readonly packageJson: JsonMap;
    /** Version of the plugin that's running this Generator. Taken dynamically from `package.json`. */
    protected readonly pluginVersion: string;
    /** Custom `falcon` options key from `package.json`. Can be used to read package-global settings that a plugin developer chooses to add to `package.json`. */
    protected readonly falcon: JsonMap;
    /** Specifies the various messages used by this Generator. */
    protected readonly generatorMessages: GeneratorMessages;
    /** Tracks the name (type) of Generator being run, eg. `clone-appx-package-project`. */
    protected readonly generatorType: string;
    /** Tracks the path to the of the source file containing the Generator being run, eg `../../generators`. */
    protected readonly generatorPath: string;
    /** Used to keep track of status and to return messages to the caller. */
    protected readonly generatorStatus: GeneratorStatus;
    /** Used to keep track of status and to return messages to the caller. */
    protected readonly generatorResult: SfdxFalconResult;
    /** Determines which initialization tasks are performed during the Default Initialization process. */
    protected readonly generatorReqs: GeneratorRequirements;
    /** Tracks the status of various run-loop functions. */
    protected readonly runLoopStatus: RunLoopStatus;
    /** Collection of objects that represent the Answers to questions that will be asked during the Interview. */
    protected readonly answers: Answers<T>;
    /** Used to share data between the Generator, Inqurirer Prompts, and Listr Tasks. */
    protected readonly sharedData: object;
    /** Holds the `SfdxFalconInterview` object that will be run during the `prompting()` run-loop function. */
    protected userInterview: SfdxFalconInterview<T>;
    /** Represents the SFDX Environment. */
    protected sfdxEnv: SfdxEnvironment;
    /**
     * @constructs  SfdxFalconGenerator
     * @param       {string|string[]} args Required. Array of arguments that are
     *              passed to this generator by Yeoman if the generator is being
     *              invoked from the command line. Passed directly through to
     *              the superclass constructor without modification.
     * @param       {GeneratorOptions}  opts Required. Object containing options
     *              that help specify how a specific generator is run. These
     *              options are set when external code uses a Yeoman Environment
     *              to `run()` a Generator that's derived from this class.
     * @description Constructs an `SfdxFalconGenerator` object.
     * @public
     */
    constructor(args: string | string[], opts: GeneratorOptions, reqs: GeneratorRequirements);
    abstract initializing(): Promise<void>;
    abstract prompting(): Promise<void>;
    abstract configuring(): Promise<void>;
    abstract writing(): Promise<void>;
    abstract install(): Promise<void>;
    abstract end(): Promise<void>;
    /**
     * @method      _showOpener
     * @returns     {Promise<void>}
     * @description Shows an opening message when the `initializing` run-loop
     *              function is executed. Uses the string from
     *              `this.generatorMessage.opening` as the source of the message
     *              contents. Can be overridden by derived class to customize the
     *              opener behavior.
     * @protected @async
     */
    protected _showOpener(): Promise<void>;
    /**
     * @method      __initializing
     * @returns     {Promise<void>}
     * @description STEP ONE in the Yeoman run-loop.  Intended to be executed as
     *              part of Yeoman's `initializing` run-loop priority.  Will call
     *              the matching single-underscore method `_initializing()` from
     *              the derived class after executing logic that's specialized
     *              for `SfdxFalconGenerator` based Generators. This method must
     *              be called by the `initializing()` method that's implemented
     *              by the dervived class.
     * @protected @async
     */
    protected __initializing(): Promise<void>;
    /**
     * @method      __prompting
     * @returns     {Promise<void>}
     * @description STEP TWO in the Yeoman run-loop.  Interviews the User to get
     *              information needed by the `writing` and `installing` phases.
     *              Intended to be executed as part of Yeoman's `prompting`
     *              run-loop priority.  Will call the matching single-underscore
     *              method `_prompting()` from the derived class after executing
     *              logic that's specialized for `SfdxFalconGenerator` based
     *              Generators. This method must be called by the `prompting()`
     *              method that's implemented by the dervived class.
     * @protected @async
     */
    protected __prompting(): Promise<void>;
    /**
     * @method      __configuring
     * @returns     {void}
     * @description STEP THREE in the Yeoman run-loop. Perform any pre-install
     *              configuration steps based on the answers provided by the User.
     *              Intended to be executed as part of Yeoman's `configuring`
     *              run-loop priority.  Will call the matching single-underscore
     *              method `_configuring()` from the derived class after executing
     *              logic that's specialized for `SfdxFalconGenerator` based
     *              Generators. this method must be called by the `configuring()`
     *              method that's implemented by the dervived class.
     * @protected @async
     */
    protected __configuring(): Promise<void>;
    /**
     * @method      __writing
     * @returns     {Promise<void>}
     * @description __STEP FOUR in the Yeoman run-loop.__ Typically, this is where
     *              you perform filesystem writes, git clone operations, etc.
     *              Intended to be executed as part of Yeoman's `writing` run-loop
     *              priority.  Will call the matching single-underscore method
     *              `_writing()` from the derived class after executing logic
     *              that's specialized for `SfdxFalconGenerator` based Generators.
     *              This method must] be called by the `writing()` method that's
     *              implemented by the dervived class.
     * @protected @async
     */
    protected __writing(): Promise<void>;
    /**
     * @method      install
     * @returns     {Promise<void>}
     * @description __STEP FIVE in the Yeoman run-loop.__ Typically, this is where
     *              you perform operations that must happen AFTER files are
     *              written to disk. For example, if the `writing` step downloaded
     *              an app to install, the `install` step would run the
     *              installation. Intended to be executed as part of Yeoman's
     *              `install` run-loop priority.  Will call the matching
     *              single-underscore method `_install()` from the derived class
     *              after executing logic that's specialized for `SfdxFalconGenerator`
     *              based Generators. This method must be called by the `install()`
     *              method that's implemented by the dervived class.
     * @protected @async
     */
    protected __install(): Promise<void>;
    /**
     * @method      __end
     * @returns     {Promise<void>}
     * @description __STEP SIX in the Yeoman run-loop.__ This is the FINAL step
     *              that Yeoman runs and it gives us a chance to do any post-Yeoman
     *              updates and/or cleanup. Intended to be executed as part of the
     *              `end` run-loop priority.  Will call the matching single-underscore
     *              method `_end()` from the derived class after executing logic
     *              that's specialized for `SfdxFalconGenerator` based Generators.
     *              This method must be called by the `end()` method that's
     *              implemented by the dervived class.
     * @protected @async
     */
    protected __end(): Promise<void>;
    /** Builds a complete `SfdxFalconInterview` object, which may include zero or more confirmation groupings. */
    protected abstract _buildInterview(): SfdxFalconInterview<T>;
    /** Creates Interview Answers table data. Can be used to render an `SfdxFalconTable` object. */
    protected abstract _buildInterviewAnswersTableData(userAnswers: T): Promise<SfdxFalconTableData>;
    /** STEP ONE in the Yeoman run-loop. Uses Yeoman's "initializing" run-loop priority. */
    protected abstract _initializing(): Promise<void>;
    /** STEP TWO in the Yeoman run-loop. Interviews the User to get information needed by the `_writing()` and `_install()` functions. */
    protected abstract _prompting(): Promise<void>;
    /** STEP THREE in the Yeoman run-loop. Perform any pre-install configuration steps based on the answers provided by the User. */
    protected abstract _configuring(): Promise<void>;
    /** STEP FOUR in the Yeoman run-loop. Typically, this is where you perform filesystem writes, git clone operations, etc. */
    protected abstract _writing(): Promise<void>;
    /** STEP FIVE in the Yeoman run-loop. Typically, this is where you perform operations that must happen AFTER files are written to disk. For example, if the `_writing()` step downloaded an app to install, the `_install()` step would run the installation. */
    protected abstract _install(): Promise<void>;
    /** STEP SIX in the Yeoman run-loop. This is the FINAL step that Yeoman runs and it gives us a chance to do any post-Yeoman updates and/or cleanup. */
    protected abstract _end(): Promise<void>;
}