grimoire-wizard 0.3.0

package/dist/index.d.ts

@@ -0,0 +1,354 @@
+type Condition = {
+    field: string;
+    equals: unknown;
+} | {
+    field: string;
+    notEquals: unknown;
+} | {
+    field: string;
+    includes: unknown;
+} | {
+    field: string;
+    notIncludes: unknown;
+} | {
+    field: string;
+    greaterThan: number;
+} | {
+    field: string;
+    lessThan: number;
+} | {
+    field: string;
+    isEmpty: true;
+} | {
+    field: string;
+    isNotEmpty: true;
+} | {
+    all: Condition[];
+} | {
+    any: Condition[];
+} | {
+    not: Condition;
+};
+type ValidationRule = {
+    rule: 'required';
+    message?: string;
+} | {
+    rule: 'minLength';
+    value: number;
+    message?: string;
+} | {
+    rule: 'maxLength';
+    value: number;
+    message?: string;
+} | {
+    rule: 'pattern';
+    value: string;
+    message?: string;
+} | {
+    rule: 'min';
+    value: number;
+    message?: string;
+} | {
+    rule: 'max';
+    value: number;
+    message?: string;
+};
+interface SelectOption {
+    value: string;
+    label: string;
+    hint?: string;
+    disabled?: boolean | string;
+}
+interface SeparatorOption {
+    separator: string;
+}
+type SelectChoice = SelectOption | SeparatorOption;
+interface BaseStepConfig {
+    id: string;
+    type: string;
+    message: string;
+    description?: string;
+    next?: string;
+    when?: Condition;
+    keepValuesOnPrevious?: boolean;
+    required?: boolean;
+    group?: string;
+}
+interface TextStepConfig extends BaseStepConfig {
+    type: 'text';
+    placeholder?: string;
+    default?: string;
+    validate?: ValidationRule[];
+}
+interface SelectStepConfig extends BaseStepConfig {
+    type: 'select';
+    options: SelectChoice[];
+    optionsFrom?: string;
+    default?: string;
+    routes?: Record<string, string>;
+    pageSize?: number;
+    loop?: boolean;
+}
+interface MultiSelectStepConfig extends BaseStepConfig {
+    type: 'multiselect';
+    options: SelectChoice[];
+    optionsFrom?: string;
+    default?: string[];
+    min?: number;
+    max?: number;
+    pageSize?: number;
+    loop?: boolean;
+}
+interface ConfirmStepConfig extends BaseStepConfig {
+    type: 'confirm';
+    default?: boolean;
+}
+interface PasswordStepConfig extends BaseStepConfig {
+    type: 'password';
+    validate?: ValidationRule[];
+}
+interface NumberStepConfig extends BaseStepConfig {
+    type: 'number';
+    default?: number;
+    min?: number;
+    max?: number;
+    step?: number;
+}
+interface SearchStepConfig extends BaseStepConfig {
+    type: 'search';
+    options: SelectChoice[];
+    optionsFrom?: string;
+    default?: string;
+    placeholder?: string;
+    pageSize?: number;
+    loop?: boolean;
+}
+interface EditorStepConfig extends BaseStepConfig {
+    type: 'editor';
+    default?: string;
+    validate?: ValidationRule[];
+}
+interface PathStepConfig extends BaseStepConfig {
+    type: 'path';
+    default?: string;
+    placeholder?: string;
+    validate?: ValidationRule[];
+}
+interface ToggleStepConfig extends BaseStepConfig {
+    type: 'toggle';
+    default?: boolean;
+    active?: string;
+    inactive?: string;
+}
+interface MessageStepConfig extends BaseStepConfig {
+    type: 'message';
+}
+type StepConfig = TextStepConfig | SelectStepConfig | MultiSelectStepConfig | ConfirmStepConfig | PasswordStepConfig | NumberStepConfig | SearchStepConfig | EditorStepConfig | PathStepConfig | ToggleStepConfig | MessageStepConfig;
+interface ThemeConfig {
+    tokens?: {
+        primary?: string;
+        success?: string;
+        error?: string;
+        warning?: string;
+        info?: string;
+        muted?: string;
+        accent?: string;
+    };
+    icons?: {
+        step?: string;
+        stepDone?: string;
+        stepPending?: string;
+        pointer?: string;
+    };
+}
+interface PreFlightCheck {
+    name: string;
+    run: string;
+    message: string;
+}
+interface ActionConfig {
+    name?: string;
+    run: string;
+    when?: Condition;
+}
+interface WizardConfig {
+    meta: {
+        name: string;
+        version?: string;
+        description?: string;
+    };
+    theme?: ThemeConfig;
+    steps: StepConfig[];
+    output?: {
+        format: 'json' | 'env' | 'yaml';
+        path?: string;
+    };
+    extends?: string;
+    checks?: PreFlightCheck[];
+    actions?: ActionConfig[];
+}
+interface WizardState {
+    currentStepId: string;
+    answers: Record<string, unknown>;
+    history: string[];
+    status: 'running' | 'done' | 'cancelled';
+    errors: Record<string, string>;
+}
+type WizardTransition = {
+    type: 'NEXT';
+    value: unknown;
+} | {
+    type: 'BACK';
+} | {
+    type: 'JUMP';
+    stepId: string;
+} | {
+    type: 'CANCEL';
+};
+interface ResolvedTheme {
+    primary: (text: string) => string;
+    success: (text: string) => string;
+    error: (text: string) => string;
+    warning: (text: string) => string;
+    info: (text: string) => string;
+    muted: (text: string) => string;
+    accent: (text: string) => string;
+    bold: (text: string) => string;
+    icons: Required<NonNullable<ThemeConfig['icons']>>;
+}
+interface WizardRenderer {
+    renderText(step: TextStepConfig, state: WizardState, theme: ResolvedTheme): Promise<string>;
+    renderSelect(step: SelectStepConfig, state: WizardState, theme: ResolvedTheme): Promise<string>;
+    renderMultiSelect(step: MultiSelectStepConfig, state: WizardState, theme: ResolvedTheme): Promise<string[]>;
+    renderConfirm(step: ConfirmStepConfig, state: WizardState, theme: ResolvedTheme): Promise<boolean>;
+    renderPassword(step: PasswordStepConfig, state: WizardState, theme: ResolvedTheme): Promise<string>;
+    renderNumber(step: NumberStepConfig, state: WizardState, theme: ResolvedTheme): Promise<number>;
+    renderSearch(step: SearchStepConfig, state: WizardState, theme: ResolvedTheme): Promise<string>;
+    renderEditor(step: EditorStepConfig, state: WizardState, theme: ResolvedTheme): Promise<string>;
+    renderPath(step: PathStepConfig, state: WizardState, theme: ResolvedTheme): Promise<string>;
+    renderToggle(step: ToggleStepConfig, state: WizardState, theme: ResolvedTheme): Promise<boolean>;
+    renderMessage(step: MessageStepConfig, state: WizardState, theme: ResolvedTheme): void;
+    renderStepHeader(stepIndex: number, totalVisible: number, message: string, theme: ResolvedTheme, description?: string): void;
+    renderGroupHeader(group: string, theme: ResolvedTheme): void;
+    renderSummary(answers: Record<string, unknown>, steps: StepConfig[], theme: ResolvedTheme): void;
+    clear(): void;
+}
+
+declare function parseWizardConfig(raw: unknown): WizardConfig;
+
+declare function loadWizardConfig(filePath: string): Promise<WizardConfig>;
+declare function parseWizardYAML(yamlString: string): WizardConfig;
+
+declare function evaluateCondition(condition: Condition, answers: Record<string, unknown>): boolean;
+declare function isStepVisible(step: StepConfig, answers: Record<string, unknown>): boolean;
+
+declare function createWizardState(config: WizardConfig): WizardState;
+declare function validateStepAnswer(step: StepConfig, value: unknown): string | null;
+declare function resolveNextStep(config: WizardConfig, currentStep: StepConfig, answer: unknown, answers: Record<string, unknown>): string;
+declare function getVisibleSteps(config: WizardConfig, answers: Record<string, unknown>): StepConfig[];
+declare function wizardReducer(state: WizardState, transition: WizardTransition, config: WizardConfig): WizardState;
+
+declare function resolveTheme(themeConfig?: ThemeConfig): ResolvedTheme;
+
+declare function resolveEnvDefault(value: string | undefined): string | undefined;
+
+interface StepPlugin {
+    render(config: Record<string, unknown>, state: WizardState, theme: ResolvedTheme): Promise<unknown>;
+    validate?(value: unknown, config: Record<string, unknown>): string | null;
+}
+interface GrimoirePlugin {
+    name: string;
+    steps: Record<string, StepPlugin>;
+}
+declare function registerPlugin(plugin: GrimoirePlugin): void;
+declare function getPluginStep(stepType: string): StepPlugin | undefined;
+declare function clearPlugins(): void;
+
+interface RunWizardOptions {
+    renderer?: WizardRenderer;
+    quiet?: boolean;
+    plain?: boolean;
+    mockAnswers?: Record<string, unknown>;
+    templateAnswers?: Record<string, unknown>;
+    onBeforeStep?: (stepId: string, step: StepConfig, state: WizardState) => Promise<void> | void;
+    onAfterStep?: (stepId: string, value: unknown, state: WizardState) => Promise<void> | void;
+    onStepComplete?: (stepId: string, value: unknown, state: WizardState) => void;
+    onCancel?: (state: WizardState) => void;
+    plugins?: GrimoirePlugin[];
+    asyncValidate?: (stepId: string, value: unknown, answers: Record<string, unknown>) => Promise<string | null>;
+    cache?: boolean | {
+        dir?: string;
+    };
+    mru?: boolean;
+}
+declare function runPreFlightChecks(checks: PreFlightCheck[], theme: ResolvedTheme): void;
+declare function runWizard(config: WizardConfig, options?: RunWizardOptions): Promise<Record<string, unknown>>;
+
+declare function defineWizard(config: WizardConfig): WizardConfig;
+
+declare class InquirerRenderer implements WizardRenderer {
+    renderStepHeader(stepIndex: number, totalVisible: number, message: string, theme: ResolvedTheme, description?: string): void;
+    renderText(step: TextStepConfig, state: WizardState, theme: ResolvedTheme): Promise<string>;
+    renderSelect(step: SelectStepConfig, state: WizardState, theme: ResolvedTheme): Promise<string>;
+    renderMultiSelect(step: MultiSelectStepConfig, state: WizardState, theme: ResolvedTheme): Promise<string[]>;
+    renderConfirm(step: ConfirmStepConfig, state: WizardState, theme: ResolvedTheme): Promise<boolean>;
+    renderPassword(step: PasswordStepConfig, _state: WizardState, theme: ResolvedTheme): Promise<string>;
+    renderNumber(step: NumberStepConfig, state: WizardState, theme: ResolvedTheme): Promise<number>;
+    renderSearch(step: SearchStepConfig, _state: WizardState, theme: ResolvedTheme): Promise<string>;
+    renderEditor(step: EditorStepConfig, _state: WizardState, theme: ResolvedTheme): Promise<string>;
+    renderPath(step: PathStepConfig, state: WizardState, theme: ResolvedTheme): Promise<string>;
+    renderToggle(step: ToggleStepConfig, state: WizardState, theme: ResolvedTheme): Promise<boolean>;
+    renderMessage(step: MessageStepConfig, _state: WizardState, theme: ResolvedTheme): void;
+    renderGroupHeader(group: string, theme: ResolvedTheme): void;
+    renderSummary(answers: Record<string, unknown>, steps: StepConfig[], theme: ResolvedTheme): void;
+    clear(): void;
+}
+
+/**
+ * Resolve {{stepId}} placeholders in a template string.
+ * Array values are joined with ", ". Unresolved placeholders remain as-is.
+ */
+declare function resolveTemplate(template: string, answers: Record<string, unknown>): string;
+
+/**
+ * Render a figlet ASCII art banner for the wizard name.
+ * Falls back to plain bold text if figlet rendering fails.
+ */
+declare function renderBanner(name: string, theme: ResolvedTheme, options?: {
+    plain?: boolean;
+}): string;
+
+declare function slugify(name: string): string;
+declare function getCacheDir(customDir?: string): string;
+declare function loadCachedAnswers(wizardName: string, customDir?: string): Record<string, unknown> | undefined;
+declare function saveCachedAnswers(wizardName: string, answers: Record<string, unknown>, customDir?: string): void;
+declare function clearCache(wizardName?: string, customDir?: string): void;
+
+declare function recordSelection(wizardName: string, stepId: string, value: string | string[]): void;
+declare function getOrderedOptions(wizardName: string, stepId: string, options: SelectChoice[]): SelectChoice[];
+declare function clearMruData(wizardName: string): void;
+
+declare class InkRenderer implements WizardRenderer {
+    renderStepHeader(stepIndex: number, totalVisible: number, message: string, theme: ResolvedTheme, description?: string): void;
+    renderText(step: TextStepConfig, state: WizardState, theme: ResolvedTheme): Promise<string>;
+    renderSelect(step: SelectStepConfig, state: WizardState, theme: ResolvedTheme): Promise<string>;
+    renderMultiSelect(step: MultiSelectStepConfig, state: WizardState, theme: ResolvedTheme): Promise<string[]>;
+    renderConfirm(step: ConfirmStepConfig, state: WizardState, theme: ResolvedTheme): Promise<boolean>;
+    renderPassword(step: PasswordStepConfig, _state: WizardState, theme: ResolvedTheme): Promise<string>;
+    renderNumber(step: NumberStepConfig, state: WizardState, theme: ResolvedTheme): Promise<number>;
+    renderSearch(step: SearchStepConfig, _state: WizardState, theme: ResolvedTheme): Promise<string>;
+    renderEditor(step: EditorStepConfig, _state: WizardState, theme: ResolvedTheme): Promise<string>;
+    renderPath(step: PathStepConfig, state: WizardState, theme: ResolvedTheme): Promise<string>;
+    renderToggle(step: ToggleStepConfig, state: WizardState, theme: ResolvedTheme): Promise<boolean>;
+    renderMessage(step: MessageStepConfig, _state: WizardState, theme: ResolvedTheme): void;
+    renderGroupHeader(group: string, theme: ResolvedTheme): void;
+    renderSummary(answers: Record<string, unknown>, steps: StepConfig[], theme: ResolvedTheme): void;
+    clear(): void;
+}
+
+declare function saveTemplate(wizardName: string, templateName: string, answers: Record<string, unknown>, excludeKeys?: string[]): void;
+declare function loadTemplate(wizardName: string, templateName: string): Record<string, unknown> | undefined;
+declare function listTemplates(wizardName: string): string[];
+declare function deleteTemplate(wizardName: string, templateName: string): void;
+
+export { type ActionConfig, type Condition, type ConfirmStepConfig, type EditorStepConfig, type GrimoirePlugin, InkRenderer, InquirerRenderer, type MessageStepConfig, type MultiSelectStepConfig, type NumberStepConfig, type PasswordStepConfig, type PathStepConfig, type PreFlightCheck, type ResolvedTheme, type RunWizardOptions, type SearchStepConfig, type SelectChoice, type SelectOption, type SelectStepConfig, type SeparatorOption, type StepConfig, type StepPlugin, type TextStepConfig, type ThemeConfig, type ToggleStepConfig, type ValidationRule, type WizardConfig, type WizardRenderer, type WizardState, type WizardTransition, clearCache, clearMruData, clearPlugins, createWizardState, defineWizard, deleteTemplate, evaluateCondition, getCacheDir, getOrderedOptions, getPluginStep, getVisibleSteps, isStepVisible, listTemplates, loadCachedAnswers, loadTemplate, loadWizardConfig, parseWizardConfig, parseWizardYAML, recordSelection, registerPlugin, renderBanner, resolveEnvDefault, resolveNextStep, resolveTemplate, resolveTheme, runPreFlightChecks, runWizard, saveCachedAnswers, saveTemplate, slugify, validateStepAnswer, wizardReducer };