@plop-next/core 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,1087 @@
+interface SeparatorLike {
+    type: "separator";
+    separator: string;
+}
+/**
+ * Prompt choices separator compatible with @inquirer/core.
+ * Use this in plopfiles to avoid importing Separator from inquirer directly.
+ */
+declare class Separator implements SeparatorLike {
+    readonly type: "separator";
+    readonly separator: string;
+    constructor(separator?: string);
+    static isSeparator(choice: unknown): choice is SeparatorLike;
+}
+
+type Prettify<T> = {
+    [K in keyof T]: T[K];
+} & {};
+/**
+ * Union type representing the possible statuses of a prompt.
+ */
+type Status = "loading" | "idle" | "done" | (string & {});
+/**
+ * A keybinding entry associating one or more key sequences to a named action.
+ */
+type Keybinding = {
+    key: string | string[];
+    action: string;
+    description?: string;
+};
+declare const BUILT_IN_PROMPT_TYPES: readonly ["input", "select", "generator-select", "list", "checkbox", "confirm", "search", "password", "expand", "editor", "number", "rawlist"];
+type PromptThemeType = (typeof BUILT_IN_PROMPT_TYPES)[number];
+type NormalizedChoice<Value> = {
+    value: Value;
+    name: string;
+    checkedName: string;
+    description?: string;
+    short: string;
+    disabled: boolean | string;
+    checked: boolean;
+};
+type DefaultTheme = {
+    icon?: string | {
+        /** Idle state icon (used by prefix-like contexts). */
+        idle?: string;
+        /** Done state icon (used by prefix-like contexts). */
+        done?: string;
+        /** Cursor icon, used by select/list/checkbox to mark the focused item. */
+        cursor?: string;
+        /** Checked icon, used by checkbox for selected items. */
+        checked?: string;
+        /** Unchecked icon, used by checkbox for unselected items. */
+        unchecked?: string;
+        /** Checked icon shown for a disabled-but-checked item in checkbox prompts. */
+        disabledChecked?: string;
+        /** Unchecked icon shown for a disabled-but-unchecked item in checkbox prompts. */
+        disabledUnchecked?: string;
+    };
+    /**
+     * Prefix shown before the prompt message.
+     */
+    prefix?: string | Prettify<Omit<Record<Status, string>, "loading">>;
+    /**
+     * Spinner shown while prompt status is "loading".
+     */
+    spinner?: {
+        interval?: number;
+        frames?: string[];
+    };
+    /**
+     * Functions used to style prompt segments.
+     */
+    style?: {
+        answer?: (text: string) => string;
+        message?: (text: string, status: Status) => string;
+        error?: (text: string) => string;
+        defaultAnswer?: (text: string) => string;
+        help?: (text: string) => string;
+        highlight?: (text: string) => string;
+        description?: (text: string) => string;
+        disabled?: (text: string) => string;
+        /** Styles a disabled choice label (checkbox). */
+        disabledChoice?: (text: string) => string;
+        /** Styles the active search term in a search prompt. */
+        searchTerm?: (text: string) => string;
+        /**
+         * Renders the summary of selected choices for a checkbox prompt.
+         * Receives the selected choices and the full list (including Separators).
+         */
+        renderSelectedChoices?: <T>(selectedChoices: ReadonlyArray<NormalizedChoice<T>>, allChoices: ReadonlyArray<NormalizedChoice<T> | Separator>) => string;
+        /**
+         * Formats the keyboard shortcuts tip shown below a prompt.
+         * - `input` passes `string[]`
+         * - `select` / `list` / `checkbox` pass `[key: string, action: string][]` (paires)
+         * Can return `undefined` to hide the tip entirely.
+         */
+        keysHelpTip?: (keys: [key: string, action: string][]) => string | undefined;
+        key?: (text: string) => string;
+        /**
+         * Static text displayed as a masked placeholder in password prompts
+         * when no mask character is set.
+         */
+        maskedText?: string;
+        /** Message shown while waiting for the user to open the editor (editor prompts). */
+        waitingMessage?: (enterKey: string) => string;
+    };
+    validationFailureMode?: "keep" | "clear";
+    indexMode?: "hidden" | "number";
+    /** Internationalisation strings used by individual prompt types. */
+    i18n?: {
+        /** Message shown when the user tries to interact with a disabled option. */
+        disabledError?: string;
+    };
+    /**
+     * Custom keybindings appended to the default set of a prompt.
+     * Each entry maps one or more key sequences to a named action.
+     */
+    keybindings?: ReadonlyArray<Keybinding>;
+    /**
+     * plop-next specific CLI style helpers.
+     */
+    plopNext?: {
+        menuTitle?: (text: string) => string;
+        welcome?: (text: string) => string;
+        generatorMenu?: {
+            title?: (text: string) => string;
+            description?: (text: string) => string;
+        };
+        actionLog?: {
+            success?: (text: string) => string;
+            error?: (text: string) => string;
+            warning?: (text: string) => string;
+            skipped?: (text: string) => string;
+            info?: (text: string) => string;
+        };
+        errors?: {
+            prefix?: {
+                error?: string;
+                warning?: string;
+            };
+            error?: (text: string) => string;
+            warning?: (text: string) => string;
+        };
+    };
+};
+type Theme<Extension extends object = object> = Prettify<Extension & DefaultTheme>;
+/**
+ * Shorthand aliases accepted in theme configs.
+ * They are normalized to style/i18n at runtime.
+ */
+type ThemeAliases = {
+    waitingMessage?: (enterKey: string) => string;
+    maskedText?: string;
+    disabledError?: string;
+};
+/**
+ * One theme scope (global or prompt-specific).
+ */
+type PromptThemeScope = Prettify<Partial<Theme> & ThemeAliases>;
+/**
+ * Public theme input accepted by setTheme/core config.
+ * Allows global fields and per-prompt overrides at the same level.
+ */
+type ThemeConfig = Prettify<PromptThemeScope & Partial<Record<PromptThemeType, PromptThemeScope>>>;
+declare const defaultTheme: DefaultTheme;
+/**
+ * Type-specific theme overrides for each @inquirer/prompts prompt type.
+ * These are merged after the global defaultTheme.
+ */
+declare const PROMPT_TYPE_THEMES: Partial<Record<PromptThemeType, PromptThemeScope>>;
+
+/** Flat or nested map of translation strings. */
+type LocaleTexts = Record<string, unknown>;
+/** Generic object map used for dynamic/interoperability paths. */
+type UnknownRecord = Record<string, unknown>;
+/** BCP-47 locale tag, e.g. "en", "fr", "es". */
+type LocaleTag = string;
+/**
+ * Flat map of read-only help/usage strings for the CLI `--help` display.
+ * Keys match the entries declared in `CORE_DEFAULT_TEXTS.help`.
+ */
+type HelpTexts = Readonly<Record<string, string>>;
+/**
+ * Rule that declares how a specific field inside a custom prompt type should be
+ * translated by the i18n system.
+ *
+ * @example
+ * // Translate a top-level field directly:
+ * { translateField: "helpHint" }
+ * // → key: `{gen}.{promptName}.helpHint`
+ *
+ * @example
+ * // Translate `title` in each `columns` item, identified by `value`:
+ * { path: "columns", translateField: "title", idField: "value" }
+ * // → key: `{gen}.{promptName}.columns.{item.value}`
+ *
+ * @example
+ * // Same with explicit array wildcard '#' (equivalent form):
+ * { path: "columns.#", translateField: "title", idField: "value" }
+ *
+ * @example
+ * // Deeply nested arrays (groups → items):
+ * { path: "groups.#.items.#", translateField: "label", idField: "id" }
+ * // → key: `{gen}.{promptName}.groups.{i}.items.{item.id}`
+ */
+interface TranslatableFieldRule {
+    /**
+     * Dot-path to the container holding the field to translate.
+     * Use `#` to mark array-iteration points.
+     *
+     * - Omit entirely for direct top-level fields on the prompt object.
+     * - If provided without `#` **and** `idField` is set, an implicit `#` is
+     *   appended: the last segment resolves to an array keyed by `idField`.
+     * - Multiple `#` are supported for arbitrarily nested arrays; `idField`
+     *   always applies to the **last** `#`.
+     */
+    path?: string;
+    /**
+     * The field whose string value should be translated.
+     *
+     * This field is used to read/write the display value inside the prompt config,
+     * but it is NOT appended to the generated i18n key.
+     */
+    translateField: string;
+    /**
+     * Field used to build the i18n key for the **last** array in the path.
+     * When set, `String(item[idField])` replaces the numeric index in the key,
+     * making translations stable across item reordering.
+     */
+    idField?: string;
+}
+
+/** Raw @inquirer style object. */
+type InquirerStyleObject = Partial<Theme["style"]> & Record<string, unknown>;
+/** Single theme object for both @inquirer and plop-next defaults/overrides. */
+type PlopNextTheme = ThemeConfig;
+
+/** Public generator item displayed in the CLI list. */
+interface GeneratorListItem {
+    name: string;
+    description?: string;
+}
+/** Public generator menu item displayed by the runner (generator or separator). */
+type GeneratorMenuItem = GeneratorListItem | SeparatorLike;
+/**
+ * Generic validate callback — T is the answer value type for the prompt.
+ * Supports sync and async validation, returns true on success or an error string.
+ */
+type ValidateFn<T = unknown> = (value: T, answers?: Record<string, any>) => boolean | string | Promise<boolean | string>;
+/** Select/list choice item. */
+type SelectChoiceItem = string | SeparatorLike | {
+    value: unknown;
+    name?: string;
+    description?: string;
+    short?: string;
+    disabled?: boolean | string;
+};
+/** Rawlist choice item. */
+type RawListChoiceItem = string | SeparatorLike | {
+    value: unknown;
+    name?: string;
+    short?: string;
+    key?: string;
+    description?: string;
+};
+/** Expand choice item. */
+type ExpandChoiceItem = SeparatorLike | {
+    key: string;
+    name?: string;
+    value?: unknown;
+};
+type SelectChoicesOrFn = SelectChoiceItem[] | ((answers: Record<string, any>) => SelectChoiceItem[] | Promise<SelectChoiceItem[]>);
+type RawListChoicesOrFn = RawListChoiceItem[] | ((answers: Record<string, any>) => RawListChoiceItem[] | Promise<RawListChoiceItem[]>);
+type ExpandChoicesOrFn = ExpandChoiceItem[] | ((answers: Record<string, any>) => ExpandChoiceItem[] | Promise<ExpandChoiceItem[]>);
+/** Search choice item. */
+type SearchChoiceItem = string | SeparatorLike | {
+    value: unknown;
+    name?: string;
+    description?: string;
+    short?: string;
+    disabled?: boolean | string;
+};
+type SearchSourceFn = (term: string | undefined, opt: SearchSourceContext, answers?: Record<string, unknown>) => ReadonlyArray<SearchChoiceItem> | Promise<ReadonlyArray<SearchChoiceItem>>;
+interface SearchSourceContext {
+    signal: AbortSignal;
+}
+interface PromptTransformContext {
+    isFinal: boolean;
+}
+/** Checkbox choice item. */
+type CheckboxChoiceItem = string | SeparatorLike | {
+    value: unknown;
+    name?: string;
+    checkedName?: string;
+    description?: string;
+    short?: string;
+    checked?: boolean;
+    disabled?: boolean | string;
+};
+/** Selected checkbox item as received by inquirer validate callback. */
+type CheckboxSelectedChoice = {
+    value: unknown;
+    name: string;
+    checkedName: string;
+    description?: string;
+    short: string;
+    checked: boolean;
+    disabled: boolean | string;
+};
+/** Checkbox global shortcuts. */
+type CheckboxShortcuts = {
+    all?: string | null;
+    invert?: string | null;
+};
+type CheckboxChoicesOrFn = CheckboxChoiceItem[] | ((answers: Record<string, any>) => CheckboxChoiceItem[] | Promise<CheckboxChoiceItem[]>);
+/**
+ * Base prompt configuration shared across all prompt types.
+ * These are plop-next specific fields, separate from @inquirer/prompts fields.
+ */
+interface PlopPromptBase {
+    /** Prompt type: 'input', 'number', 'confirm', 'list', 'select', 'checkbox', etc. */
+    type: string;
+    /** Answer key in the answers hash. Should contain no spaces. */
+    name: string;
+    /**
+     * Reserved for future plop-next theming API.
+     * Intentionally blocked for now.
+     */
+    /** Input message or callback to generate dynamic message. */
+    message?: string | ((answers: Record<string, any>) => string);
+    /** Default value if no answer provided. */
+    default?: unknown | ((answers: Record<string, unknown>) => unknown | Promise<unknown>);
+    /** Filter the user input before storing in answers. */
+    filter?: (value: unknown, answers?: Record<string, unknown>) => unknown;
+    /** Show or hide prompt based on condition or callback. */
+    when?: boolean | ((answers: Record<string, any>) => boolean);
+    /** Force prompt even if answer already exists. */
+    askAnswered?: boolean;
+}
+/** Text input prompt. */
+interface PlopPromptInput extends PlopPromptBase {
+    type: "input";
+    /** Transform/format the raw value for display (visual only, does not affect stored value). */
+    transformer?: (value: string, context: PromptTransformContext) => string;
+    /** RegExp pattern the input must match. */
+    pattern?: RegExp;
+    /** Error message shown when pattern is not matched. */
+    patternError?: string;
+    /** Prefill behavior: 'tab' fills on Tab, 'editable' pre-fills the input field. */
+    prefill?: "tab" | "editable";
+    /** Reject empty input. */
+    required?: boolean;
+    /** Validate the text value before accepting. */
+    validate?: ValidateFn<string>;
+}
+/** Numeric input prompt. */
+interface PlopPromptNumber extends PlopPromptBase {
+    type: "number";
+    default?: number;
+    min?: number;
+    max?: number;
+    step?: number | "any";
+    required?: boolean;
+    /** Validate the numeric value before accepting. */
+    validate?: ValidateFn<number | undefined>;
+}
+/** Boolean confirmation prompt (yes / no). */
+interface PlopPromptConfirm extends PlopPromptBase {
+    type: "confirm";
+    default?: boolean;
+    /** Transform the displayed value (visual only). */
+    transformer?: (value: boolean) => string;
+}
+/** Single-choice prompt (select one item from a list). */
+interface PlopPromptSelect extends PlopPromptBase {
+    type: "list" | "select";
+    choices: SelectChoicesOrFn;
+    pageSize?: number;
+    loop?: boolean;
+}
+/** Rawlist prompt (single choice with indexed shortcuts). */
+interface PlopPromptRawList extends PlopPromptBase {
+    type: "rawlist";
+    choices: RawListChoicesOrFn;
+    loop?: boolean;
+}
+/** Expand prompt (single choice with explicit key shortcuts). */
+interface PlopPromptExpand extends PlopPromptBase {
+    type: "expand";
+    choices: ExpandChoicesOrFn;
+    expanded?: boolean;
+}
+/** Search-based single-choice prompt (dynamic source function). */
+interface PlopPromptSearch extends PlopPromptBase {
+    type: "search";
+    /** Async function that returns filtered choices based on current input. */
+    source: SearchSourceFn;
+    pageSize?: number;
+    /** Validate the selected value before accepting. */
+    validate?: (value: unknown, answers?: Record<string, unknown>) => boolean | string | Promise<boolean | string>;
+}
+/** Multi-choice checkbox prompt. */
+interface PlopPromptCheckbox extends PlopPromptBase {
+    type: "checkbox";
+    choices: CheckboxChoicesOrFn;
+    pageSize?: number;
+    loop?: boolean;
+    /** Reject empty selection. */
+    required?: boolean;
+    shortcuts?: CheckboxShortcuts;
+    /** Validate the selected values array before accepting. */
+    validate?: (choices: readonly CheckboxSelectedChoice[], answers?: Record<string, unknown>) => boolean | string | Promise<boolean | string>;
+}
+/** Multi-line editor prompt (opens the user's $EDITOR). */
+interface PlopPromptEditor extends PlopPromptBase {
+    type: "editor";
+    default?: string;
+    /** File extension for the temp file shown in the editor (e.g. ".md"). */
+    postfix?: string;
+    /** Open editor immediately without waiting for Enter. */
+    waitForUserInput?: boolean;
+    /** Low-level temp file options forwarded to @inquirer/external-editor. */
+    file?: Record<string, unknown>;
+    /** Validate the final text content before accepting. */
+    validate?: ValidateFn<string>;
+}
+/** Masked password input. */
+interface PlopPromptPassword extends PlopPromptBase {
+    type: "password";
+    /** true uses "*", string uses a custom mask character/string, false keeps input transparent. */
+    mask?: boolean | string;
+    /** Validate the entered password before accepting. */
+    validate?: ValidateFn<string>;
+}
+/** Union of all built-in prompt types plus a generic fallback for custom/unknown types. */
+type PlopPrompt = PlopPromptInput | PlopPromptNumber | PlopPromptConfirm | PlopPromptSelect | PlopPromptRawList | PlopPromptExpand | PlopPromptSearch | PlopPromptCheckbox | PlopPromptEditor | PlopPromptPassword | PlopPromptBase;
+type ActionType = "add" | "modify" | "append" | string;
+type TransformFn = (input: string, data: Record<string, unknown>) => string | Promise<string>;
+type SkipFn = (answers: Record<string, any>, action: ActionConfig) => boolean | string | Promise<boolean | string>;
+interface ActionConfig {
+    type: ActionType;
+    path?: string;
+    template?: string;
+    templateFile?: string;
+    pattern?: RegExp | string;
+    transform?: TransformFn;
+    skip?: SkipFn;
+    skipIfExists?: boolean;
+    force?: boolean;
+    unique?: boolean;
+    separator?: string;
+    destination?: string;
+    base?: string;
+    templateFiles?: string | string[];
+    stripExtensions?: string[];
+    globOptions?: Record<string, unknown>;
+    verbose?: boolean;
+    abortOnFail?: boolean;
+    data?: Record<string, unknown>;
+    [key: string]: unknown;
+}
+type CustomActionFunction = (answers: Record<string, any>, config: ActionConfig, plopNext: unknown) => string | Promise<string>;
+type Action = ActionConfig | CustomActionFunction | string;
+type DynamicActionsFn = (answers: Record<string, any>) => Action[] | Promise<Action[]>;
+type ActionsConfig = Action[] | DynamicActionsFn;
+type HandlebarsHelper = (...args: unknown[]) => unknown;
+/**
+ * Legacy custom prompt renderer signature.
+ *
+ * Kept intentionally permissive because third-party prompt packages can expose
+ * stricter config generics and optional extra params (e.g. context).
+ */
+type PromptRenderer = (...args: any[]) => unknown | Promise<unknown>;
+interface ActionExecutionOptions {
+    dest?: string;
+    force?: boolean;
+}
+interface ActionStepResult {
+    type: string;
+    status: "success" | "error";
+    message: string;
+    path?: string;
+}
+interface ActionExecutionResult {
+    steps: ActionStepResult[];
+    failed: boolean;
+}
+type DefaultIncludeConfig = Record<string, unknown>;
+interface GeneratorConfig {
+    description?: string;
+    prompts: PlopPrompt[];
+    actions: ActionsConfig;
+}
+interface PlopNextEnv {
+    cwd: string;
+    configPath: string | null;
+    modulePath: string | null;
+    config?: unknown;
+}
+
+/**
+ * Config passed to a PromptHandler's ask() method.
+ * Contains all prompt fields except the plop-next-only keys
+ * (type, name, filter, when, askAnswered) which the runner strips before dispatch.
+ */
+interface PromptHandlerConfig {
+    /** Answer key — included so handlers can forward it if needed. */
+    name: string;
+    /** Internal use: resolved by core.setTheme({ ... }). */
+    theme?: PromptThemeConfig;
+    message?: unknown;
+    default?: unknown;
+    validate?: unknown;
+    [key: string]: unknown;
+}
+/** Raw config shape expected by @inquirer prompt functions. */
+type InquirerPromptFn = (config: UnknownRecord) => Promise<unknown>;
+/** Theme payload forwarded to @inquirer prompt functions. */
+type PromptThemeConfig = UnknownRecord;
+/**
+ * Contract for a specialised prompt handler.
+ *
+ * Each handler encapsulates the rendering logic for one or more prompt types
+ * (e.g. the select handler covers "list", "select").
+ * Handlers are registered into PlopNextCore via `registerPrompt(handler)` and
+ * are therefore available to any runtime that uses the core (CLI, test helpers,
+ * custom runners, etc.).
+ *
+ * @example
+ * // Register a custom date-picker handler
+ * core.registerPrompt({
+ *   types: ["datepicker"],
+ *   async ask(_type, config) {
+ *     return myDatePickerLib({ message: String(config.message ?? "") });
+ *   },
+ * });
+ */
+interface PromptHandler {
+    /**
+     * Prompt type identifiers this handler supports.
+     * The first entry is used as the canonical name in error messages.
+     */
+    readonly types: ReadonlyArray<string>;
+    /**
+     * Execute the prompt and return the user's answer.
+     * @param type   The exact type string that was requested.
+     * @param config All prompt fields minus the plop-next-only keys.
+     */
+    ask(type: string, config: PromptHandlerConfig): Promise<unknown>;
+}
+
+/**
+ * Extraction spec for one theme field.
+ *
+ * - `true`      → include the field as-is (scalar or full object)
+ * - `string[]`  → field is an object; include only these sub-fields
+ */
+type PromptThemeFieldSpec = true | string[];
+/**
+ * Flat selector declaration — no wrapper objects.
+ *
+ * Each key (except the reserved `baseSelector`) maps to an extraction spec:
+ * - `fieldName: true`        → copy the top-level field value as-is
+ * - `fieldName: string[]`    → field is an object; copy only the listed sub-keys
+ *
+ * @example
+ * // Built-in select selector:
+ * {
+ *   prefix: true,
+ *   spinner: true,
+ *   indexMode: true,
+ *   style: ["answer", "message", "description", "keysHelpTip"],
+ *   icon: ["cursor"],
+ * }
+ */
+type PromptThemeSelector = {
+    /** Inherit all entries from another registered selector, then apply overrides. */
+    baseSelector?: string;
+    [field: string]: PromptThemeFieldSpec | string | undefined;
+};
+/**
+ * Options for declaring which theme fields a custom prompt should receive.
+ *
+ * The `selector` key is the only reserved entry; all other keys follow the
+ * same flat extraction syntax as `PromptThemeSelector`.
+ *
+ * @example
+ * plop.registerPrompt("table-multiple", handler, {
+ *   selector: "select",        // inherit select's fields
+ *   icon: ["cursor", "checked"], // extend icon with extra sub-fields
+ * });
+ */
+type PromptThemeSelectorOptions = {
+    /** Inherit from an existing built-in selector (e.g. "select"). */
+    selector?: string;
+    [field: string]: PromptThemeFieldSpec | string | undefined;
+};
+declare function createPromptThemeSelector(options: PromptThemeSelectorOptions): PromptThemeSelector;
+
+/**
+ * Configuration for error behavior and reporting.
+ */
+interface ErrorConfig {
+    /** Whether this is a warning (non-fatal) or an error (fatal). */
+    isWarning: boolean;
+    /** Whether handling this issue should terminate the process. */
+    shouldExit: boolean;
+    /** Exit code to return when this error is handled. */
+    exitCode: number;
+    /** Whether to display the stack trace in output (depends on verbosity). */
+    showStackTrace: boolean;
+    /** Whether to allow logging this error to a file. */
+    allowLogFile: boolean;
+}
+interface ErrorTranslation {
+    key: string;
+    args?: unknown[];
+    fallback: string;
+}
+type ForcedLangFallbackReason = "i18n-missing" | "locale-not-found";
+/**
+ * Base error class for plop-next errors.
+ * All caught errors must extend this class for proper handling and logging.
+ */
+declare class PlopError extends Error {
+    readonly code: string;
+    readonly isOperational: boolean;
+    readonly config: ErrorConfig;
+    readonly translation?: ErrorTranslation;
+    constructor(code: string, message: string, config: ErrorConfig, translation?: ErrorTranslation);
+}
+/**
+ * Generator not found error.
+ */
+declare class GeneratorNotFoundError extends PlopError {
+    constructor(generatorName: string);
+}
+/**
+ * No generators registered error.
+ */
+declare class NoGeneratorsError extends PlopError {
+    constructor();
+}
+/**
+ * Invalid prompt configuration error.
+ */
+declare class InvalidPromptError extends PlopError {
+    constructor(promptName: string, reason: string);
+}
+/**
+ * Bypass value parsing error.
+ */
+declare class BypassParseError extends PlopError {
+    constructor(promptName: string, promptType: string, value: string, reason?: string);
+}
+/**
+ * Plopfile loading error.
+ */
+declare class PlopfileLoadError extends PlopError {
+    readonly requireError?: Error;
+    readonly importError?: Error;
+    constructor(filePath: string, requireError?: Error, importError?: Error);
+}
+/**
+ * Invalid plopfile export error.
+ */
+declare class PlopfileExportError extends PlopError {
+    constructor(message?: string);
+}
+/**
+ * User cancelled the prompt (e.g., Ctrl+C).
+ * This is not really an error, but treated as one for control flow.
+ */
+declare class UserCancelledError extends PlopError {
+    constructor();
+}
+/**
+ * No plopfile found in current working directory.
+ */
+declare class PlopfileNotFoundWarning extends PlopError {
+    constructor(message?: string);
+}
+/**
+ * Forced locale fallback warning.
+ * Emitted when `--lang` is provided but cannot be applied.
+ */
+declare class ForcedLangFallbackWarning extends PlopError {
+    readonly locale: string;
+    readonly reason: ForcedLangFallbackReason;
+    constructor(locale: string, reason: ForcedLangFallbackReason);
+}
+/**
+ * Non-fatal warning emitted when an i18n source file is ignored.
+ */
+declare class I18nSourceWarning extends PlopError {
+    constructor(message: string);
+}
+
+interface UseI18nOptions {
+    /** Force a specific locale tag, e.g. "fr". */
+    force?: LocaleTag;
+    /**
+     * Use auto-detection (OS locale) when `force` is not provided.
+     * Defaults to true when calling useI18n().
+     */
+    auto?: boolean;
+}
+interface RegisterLocaleOptions {
+    /** If true, this locale becomes active immediately. */
+    activate?: boolean;
+}
+interface I18nAdapter {
+    t(key: string, args?: unknown[], fallback?: string): string;
+    preparePrompts(generatorName: string, prompts: PlopPrompt[]): PlopPrompt[];
+    getWelcomeMessage?(): string | null;
+    use?(options: UseI18nOptions): void;
+    isEnabled?(): boolean;
+    hasLocale?(locale: LocaleTag): boolean;
+    registerLocale?(locale: LocaleTag, messages: LocaleTexts | string, options?: RegisterLocaleOptions): void;
+    registerLocales?(locales: Record<string, LocaleTexts> | LocaleTexts | string, options?: RegisterLocaleOptions): void;
+    registerTexts?(localeOrTexts: LocaleTag | Record<string, LocaleTexts> | LocaleTexts | string, maybeTexts?: LocaleTexts | string): void;
+    registerText?(locale: LocaleTag, path: string, text: unknown): void;
+    setLocale?(locale: LocaleTag): void;
+    getLocale?(): LocaleTag;
+    registerTranslatableFields?(promptType: string, rules: TranslatableFieldRule[]): void;
+}
+interface RegisterPromptOptions {
+    /** Theme selector/extraction config for this custom prompt type. */
+    theme?: PromptThemeSelector;
+    /** Translatable field rules for this custom prompt type. */
+    translatableFields?: TranslatableFieldRule[];
+}
+declare class PlopNextCore {
+    private readonly generators;
+    private readonly generatorEntries;
+    private readonly actionTypes;
+    /** Legacy custom prompt renderers (registered via addPrompt / setPrompt). */
+    private readonly promptTypes;
+    /** Typed prompt handlers registered via registerPrompt(handler). */
+    private readonly promptHandlerRegistry;
+    private readonly promptThemeSelectorRegistry;
+    private i18nAdapter?;
+    private readonly translatableFieldRules;
+    private showWelcomeMessageFlag;
+    private showTitleFlag;
+    private generatorPageSize;
+    private plopfilePath?;
+    private destBasePath;
+    private defaultInclude;
+    private theme;
+    private pkgCachePath?;
+    private pkgCache?;
+    private warningReporter?;
+    constructor();
+    /**
+     * Register a named generator.
+     *
+     * @example
+     * plopNext.registerGenerator("component", { prompts: [...], actions: [...] });
+     */
+    registerGenerator(name: string, config: GeneratorConfig): this;
+    addSeparator(text?: string): this;
+    setGenerator(name: string, config: GeneratorConfig): this;
+    registerHelper(name: string, helper: HandlebarsHelper): this;
+    setHelper(name: string, helper: HandlebarsHelper): this;
+    registerPartial(name: string, partial: string): this;
+    setPartial(name: string, partial: string): this;
+    registerActionType(name: string, actionType: CustomActionFunction): this;
+    setActionType(name: string, actionType: CustomActionFunction): this;
+    registerPrompt(name: string, prompt: PromptRenderer): this;
+    registerPrompt(name: string, prompt: PromptRenderer, options: RegisterPromptOptions): this;
+    registerPrompt(handler: PromptHandler): this;
+    setPrompt(name: string, prompt: PromptRenderer): this;
+    getPrompt(name: string): PromptRenderer | undefined;
+    getPromptList(): string[];
+    /** List the type strings that have a registered PromptHandler. */
+    getPromptHandlerTypes(): string[];
+    /**
+     * Dispatch a prompt to the appropriate handler.
+     *
+     * Resolution order:
+     * 1. Legacy PromptRenderer registered via `addPrompt()` / `setPrompt()` — highest priority.
+     * 2. PromptHandler registered via `registerPrompt(handler)` for the exact type.
+     * 3. PromptHandler registered for "input" as fallback.
+     *
+     * @param type   Prompt type string (e.g. "input", "list", "datepicker").
+     * @param config All prompt fields minus plop-next-only keys (type/name/filter/when/askAnswered).
+     */
+    askPrompt(type: string, config: PromptHandlerConfig): Promise<unknown>;
+    setTheme(theme: PlopNextTheme | string): this;
+    getTheme(): PlopNextTheme;
+    private resolveThemeInput;
+    private parseThemeJsonFile;
+    private parseThemeModuleFile;
+    getActionType(name: string): CustomActionFunction | undefined;
+    getActionTypeList(): string[];
+    getHelper(name: string): HandlebarsHelper | undefined;
+    getHelperList(): string[];
+    getPartial(name: string): string | undefined;
+    getPartialList(): string[];
+    showWelcomeMessage(show?: boolean): this;
+    getWelcomeMessage(): string | null;
+    isWelcomeMessageShown(): boolean;
+    showTitle(show?: boolean): this;
+    isTitleShown(): boolean;
+    /**
+     * Set page size used by the generator selection prompt.
+     * Defaults to 7.
+     */
+    setGeneratorPageSize(pageSize: number): this;
+    /**
+     * Get page size used by the generator selection prompt.
+     */
+    getGeneratorPageSize(): number;
+    setI18nAdapter(adapter: I18nAdapter): this;
+    setWarningReporter(reporter: ((warning: PlopError) => void) | undefined): this;
+    reportWarning(warning: PlopError): this;
+    clearI18nAdapter(): this;
+    setPlopfilePath(path: string): this;
+    getPlopfilePath(): string | undefined;
+    setDestBasePath(path: string): this;
+    getDestBasePath(): string;
+    setDefaultInclude(include: DefaultIncludeConfig): this;
+    getDefaultInclude(): DefaultIncludeConfig;
+    renderString(template: string, data: Record<string, unknown>): string;
+    getGenerator(name: string): GeneratorConfig | undefined;
+    getGeneratorList(): GeneratorMenuItem[];
+    /**
+     * Enable i18n support.
+     *
+     * - `force`: always use this locale.
+     * - `auto` (default): detect locale from process environment,
+     *   then fall back to English.
+     */
+    useI18n(options?: UseI18nOptions): this;
+    isI18nEnabled(): boolean;
+    /**
+     * Resolve the display text for a prompt field.
+     *
+     * When i18n is **disabled**: returns `defaultMessage` as-is.
+     * When i18n is **enabled**: looks up `<generatorName>.<promptName>.<field>`
+     * in the active locale, falls back to English, then to `defaultMessage`.
+     *
+     * @param generatorName  Generator key, e.g. "component"
+     * @param promptName     Prompt name, e.g. "name"
+     * @param field          Field name, e.g. "message"
+     * @param defaultMessage Raw string or function defined inside setGenerator
+     */
+    resolveText(generatorName: string, promptName: string, field: string, defaultMessage?: string | ((...args: unknown[]) => string), args?: unknown[]): string | ((...args: unknown[]) => string) | undefined;
+    /**
+     * Resolve a built-in core UI text (e.g. "cli.welcome").
+     */
+    t(key: string, args?: unknown[], fallback?: string): string;
+    /**
+     * Add or override messages for an existing locale.
+     * Available whether or not i18n plugin is loaded.
+     */
+    addTexts(locale: LocaleTag, texts: LocaleTexts): this;
+    registerText(locale: LocaleTag, path: string, text: unknown): this;
+    registerLocale(locale: LocaleTag, messages: LocaleTexts | string, options?: RegisterLocaleOptions): this;
+    registerLocales(locales: Record<string, LocaleTexts> | LocaleTexts | string, options?: RegisterLocaleOptions): this;
+    registerTexts(locale: LocaleTag, texts: LocaleTexts | string): this;
+    registerTexts(localesOrTexts: Record<string, LocaleTexts> | LocaleTexts | string): this;
+    setLocale(locale: LocaleTag): this;
+    getLocale(): LocaleTag;
+    hasLocale(locale: LocaleTag): boolean;
+    executeActions(actions: Action[], answers: Record<string, unknown>, options?: ActionExecutionOptions): Promise<ActionExecutionResult>;
+    resolveActions(actions: ActionsConfig, answers: Record<string, unknown>): Promise<Action[]>;
+    getActionTypeDisplay(type: string, showTypeNames?: boolean): string;
+    formatActionTargetForDisplay(value: string): string;
+    private registerBuiltInHelpers;
+    private readPackageProperty;
+    private loadPackageJsonNearPlopfile;
+    private getPathValue;
+    /**
+     * Returns prepared prompts for a generator: prompt `message` fields are
+     * transformed by plugins (like i18n) before they are rendered by Inquirer.
+     */
+    preparePrompts(generatorName: string, prompts: PlopPrompt[]): PlopPrompt[];
+    private resolvePromptTheme;
+    /**
+     * Resolve the full theme for a specific prompt type.
+     * Merges in order: defaultTheme → type defaults → user global theme → user type theme.
+     */
+    private resolvePromptTypeTheme;
+    private resolveTheme;
+    private cloneTheme;
+    private resolveNormalizedGlobalTheme;
+    private resolveUserPromptTypeTheme;
+    private normalizeThemeScope;
+    private mergeThemeLayers;
+    private looksLikeThemeSource;
+    private looksLikeI18nSource;
+    private isLocaleLikeKey;
+    private isRecord;
+    private isPromptThemeTypeKey;
+    private unwrapModuleDefault;
+    private cloneUnknown;
+    /**
+     * Merge icon values when applying one layer over another.
+     */
+    private mergeIconLayers;
+}
+
+interface ActionRunnerOptions {
+    /** Base directory for generated files. Relative action paths are resolved against this. */
+    dest?: string;
+    /** When true, overwrite existing files instead of throwing. */
+    force?: boolean;
+}
+interface ActionRunResult {
+    type: string;
+    message: string;
+    /** Interpolated path template, useful for UI output. */
+    path?: string;
+    /** Absolute path used for filesystem operations. */
+    absolutePath?: string;
+}
+/**
+ * Built-in action handlers (business logic): add, modify, append.
+ */
+declare class ActionRunner {
+    private readonly core;
+    private readonly opts;
+    constructor(core: PlopNextCore, opts?: ActionRunnerOptions);
+    run(type: string, config: ActionConfig, answers: Record<string, unknown>): Promise<ActionRunResult>;
+    private runAdd;
+    private runAddMany;
+    private runModify;
+    private runAppend;
+    private resolveTemplate;
+    private toAbsolute;
+    private resolveTemplateFilePath;
+    private interpolate;
+    private applyTransform;
+}
+
+interface PromptAskOptions {
+    allowTheme?: boolean;
+}
+/**
+ * Registry that maps prompt type strings to their PromptHandler.
+ *
+ * Embedded in PlopNextCore — handlers are registered there via
+ * `core.registerPrompt(handler)`.
+ *
+ * Resolution order when PlopNextCore.askPrompt() is called:
+ * 1. User-registered PromptRenderer (legacy `addPrompt` / `setPrompt` API) — highest priority.
+ * 2. Registered PromptHandler matching the exact type string.
+ * 3. Registered PromptHandler for "input" as fallback.
+ */
+declare class PromptHandlerRegistry {
+    private readonly map;
+    /**
+     * Register a handler for all its declared types.
+     * If a type is already registered, the new handler replaces the previous one,
+     * allowing built-in handlers to be overridden by plugins or users.
+     */
+    register(handler: PromptHandler): this;
+    /** Return the handler for the given type, or undefined if none is registered. */
+    get(type: string): PromptHandler | undefined;
+    /** True if a handler is registered for the given type. */
+    has(type: string): boolean;
+    /** List of all registered type strings. */
+    getRegisteredTypes(): string[];
+    /**
+     * Dispatch a prompt to the right handler.
+     *
+     * @param type   The prompt type string.
+     * @param config Prompt fields without plop-next-only keys.
+     * @returns      The user's answer.
+     * @throws       If no handler is registered for the type and no "input" fallback exists.
+     */
+    ask(type: string, config: PromptHandlerConfig, options?: PromptAskOptions): Promise<unknown>;
+}
+
+/** Register all built-in @inquirer prompt handlers into a registry instance. */
+declare function registerBuiltInPromptHandlers(registry: PromptHandlerRegistry): void;
+
+/**
+ * Core-owned default UI texts used by plop-next.
+ * This file is intentionally locale-agnostic from a folder/filename perspective.
+ */
+declare const CORE_DEFAULT_TEXTS: LocaleTexts;
+/**
+ * Backward-compatible alias.
+ * Prefer `CORE_DEFAULT_TEXTS`.
+ */
+declare const CORE_DEFAULT_TEXTS_EN: LocaleTexts;
+/**
+ * Typed accessor for the built-in English help texts.
+ * Use this in the CLI to render `--help` output.
+ */
+declare const CORE_DEFAULT_HELP_TEXTS: HelpTexts;
+
+/** Register a legacy custom prompt renderer by name. */
+declare function registerCustomPrompt(promptTypes: Map<string, PromptRenderer>, name: string, prompt?: PromptRenderer): void;
+/** Return a previously registered custom prompt renderer. */
+declare function getCustomPrompt(promptTypes: Map<string, PromptRenderer>, name: string): PromptRenderer | undefined;
+/** List custom prompt renderer type names. */
+declare function listCustomPromptTypes(promptTypes: Map<string, PromptRenderer>): string[];
+/** Execute a legacy custom prompt renderer with plop-next internal keys stripped. */
+declare function askCustomPrompt(prompt: PromptRenderer, config: PromptHandlerConfig): Promise<unknown>;
+
+type ErrorTranslator = (key: string, args?: unknown[], fallback?: string) => string;
+type ErrorVerbosity = "simple" | "verbose" | "debug";
+interface ErrorHandlerOptions {
+    /**
+     * Level of error output detail.
+     * - "simple" (default): Single-line explanation.
+     * - "verbose": Error code + message + context.
+     * - "debug": Includes full stack trace and diagnostic info.
+     */
+    verbosity?: ErrorVerbosity;
+    /**
+     * Optional file path to log all errors to.
+     * File will be created/appended to if provided.
+     */
+    logFile?: string;
+    /**
+     * Whether to use ANSI color in console output.
+     * Defaults to true.
+     */
+    useColors?: boolean;
+    /**
+     * Error/warning console theming overrides.
+     */
+    theme?: {
+        prefix?: {
+            error?: string;
+            warning?: string;
+        };
+        error?: (text: string) => string;
+        warning?: (text: string) => string;
+    };
+}
+interface ErrorHandleResult {
+    exitCode: number;
+    shouldExit: boolean;
+}
+/**
+ * Handles errors with configurable verbosity and optional file logging.
+ */
+declare class ErrorHandler {
+    private verbosity;
+    private logFile?;
+    private useColors;
+    private errorPrefix;
+    private warningPrefix;
+    private errorStyle;
+    private warningStyle;
+    private translator?;
+    constructor(options?: ErrorHandlerOptions);
+    /**
+     * Handle and output an error.
+     * Returns exit behavior and code.
+     */
+    handle(error: unknown): ErrorHandleResult;
+    private isPlopError;
+    private formatError;
+    private formatSimple;
+    private formatVerbose;
+    private formatDebug;
+    private formatUnhandledError;
+    private resolveMessage;
+    private logToConsole;
+    private logToFile;
+    setVerbosity(verbosity: ErrorVerbosity): void;
+    setLogFile(logFile: string | undefined): void;
+    setTheme(theme: PlopNextTheme | undefined): void;
+    setTranslator(translator: ErrorTranslator | undefined): void;
+    private applyTheme;
+}
+
+declare function createSelectHandler(fn?: InquirerPromptFn): PromptHandler;
+
+declare function createConfirmHandler(fn?: InquirerPromptFn): PromptHandler;
+
+declare function createCheckboxHandler(fn?: InquirerPromptFn): PromptHandler;
+
+declare function createSearchHandler(fn?: InquirerPromptFn): PromptHandler;
+
+declare function createEditorHandler(fn?: InquirerPromptFn): PromptHandler;
+
+declare function createPasswordHandler(fn?: InquirerPromptFn): PromptHandler;
+
+export { type Action, type ActionConfig, type ActionExecutionOptions, type ActionExecutionResult, type ActionRunResult, ActionRunner, type ActionRunnerOptions, type ActionStepResult, type ActionType, type ActionsConfig, BypassParseError, CORE_DEFAULT_HELP_TEXTS, CORE_DEFAULT_TEXTS, CORE_DEFAULT_TEXTS_EN, type CustomActionFunction, type DefaultIncludeConfig, type DefaultTheme, type ErrorConfig, type ErrorHandleResult, ErrorHandler, type ErrorHandlerOptions, type ErrorTranslator, type ErrorVerbosity, type ForcedLangFallbackReason, ForcedLangFallbackWarning, type GeneratorConfig, type GeneratorListItem, type GeneratorMenuItem, GeneratorNotFoundError, type HandlebarsHelper, type HelpTexts, type I18nAdapter, I18nSourceWarning, type InquirerPromptFn, type InquirerStyleObject, InvalidPromptError, type Keybinding, type LocaleTag, type LocaleTexts, NoGeneratorsError, PROMPT_TYPE_THEMES, PlopError, PlopNextCore, type PlopNextEnv, type PlopNextTheme, type PlopPrompt, type PlopPromptBase, PlopfileExportError, PlopfileLoadError, PlopfileNotFoundWarning, type PromptHandler, type PromptHandlerConfig, PromptHandlerRegistry, type PromptRenderer, type PromptThemeFieldSpec, type PromptThemeSelector, type PromptThemeSelectorOptions, type RegisterLocaleOptions, type RegisterPromptOptions, Separator, type SeparatorLike, type Status, type Theme, type TranslatableFieldRule, type UnknownRecord, type UseI18nOptions, UserCancelledError, askCustomPrompt, createCheckboxHandler, createConfirmHandler, createEditorHandler, createPasswordHandler, createPromptThemeSelector, createSearchHandler, createSelectHandler, defaultTheme, getCustomPrompt, listCustomPromptTypes, registerBuiltInPromptHandlers, registerCustomPrompt };