grimoire-wizard 0.3.1 → 0.5.0

package/dist/index.d.ts

@@ -143,8 +143,12 @@ interface ToggleStepConfig extends BaseStepConfig {
 interface MessageStepConfig extends BaseStepConfig {
     type: 'message';
 }
-type StepConfig = TextStepConfig | SelectStepConfig | MultiSelectStepConfig | ConfirmStepConfig | PasswordStepConfig | NumberStepConfig | SearchStepConfig | EditorStepConfig | PathStepConfig | ToggleStepConfig | MessageStepConfig;
+interface NoteStepConfig extends BaseStepConfig {
+    type: 'note';
+}
+type StepConfig = TextStepConfig | SelectStepConfig | MultiSelectStepConfig | ConfirmStepConfig | PasswordStepConfig | NumberStepConfig | SearchStepConfig | EditorStepConfig | PathStepConfig | ToggleStepConfig | MessageStepConfig | NoteStepConfig;
 interface ThemeConfig {
+    preset?: string;
     tokens?: {
         primary?: string;
         success?: string;
@@ -160,6 +164,10 @@ interface ThemeConfig {
         stepPending?: string;
         pointer?: string;
     };
+    spinner?: string | {
+        frames: string[];
+        interval?: number;
+    };
 }
 interface PreFlightCheck {
     name: string;
@@ -171,11 +179,16 @@ interface ActionConfig {
     run: string;
     when?: Condition;
 }
+type OnCompleteHandler = (context: {
+    answers: Record<string, unknown>;
+    config: WizardConfig;
+}) => Promise<void> | void;
 interface WizardConfig {
     meta: {
         name: string;
         version?: string;
         description?: string;
+        review?: boolean;
     };
     theme?: ThemeConfig;
     steps: StepConfig[];
@@ -186,6 +199,7 @@ interface WizardConfig {
     extends?: string;
     checks?: PreFlightCheck[];
     actions?: ActionConfig[];
+    onComplete?: string;
 }
 interface WizardState {
     currentStepId: string;
@@ -205,6 +219,72 @@ type WizardTransition = {
 } | {
     type: 'CANCEL';
 };
+type WizardEvent = {
+    type: 'session:start';
+    wizard: string;
+    description?: string;
+    totalSteps: number;
+} | {
+    type: 'session:end';
+    answers: Record<string, unknown>;
+    cancelled: boolean;
+} | {
+    type: 'group:start';
+    group: string;
+} | {
+    type: 'step:start';
+    stepId: string;
+    stepIndex: number;
+    totalVisible: number;
+    step: StepConfig;
+} | {
+    type: 'step:complete';
+    stepId: string;
+    value: unknown;
+    step: StepConfig;
+} | {
+    type: 'step:error';
+    stepId: string;
+    error: string;
+} | {
+    type: 'step:back';
+    stepId: string;
+} | {
+    type: 'spinner:start';
+    message: string;
+} | {
+    type: 'spinner:stop';
+    message?: string;
+} | {
+    type: 'note';
+    title: string;
+    body: string;
+} | {
+    type: 'checks:start';
+    checks: PreFlightCheck[];
+} | {
+    type: 'check:pass';
+    name: string;
+} | {
+    type: 'check:fail';
+    name: string;
+    message: string;
+} | {
+    type: 'actions:start';
+} | {
+    type: 'action:pass';
+    name: string;
+} | {
+    type: 'action:fail';
+    name: string;
+} | {
+    type: 'oncomplete:start';
+} | {
+    type: 'oncomplete:pass';
+} | {
+    type: 'oncomplete:fail';
+    error: string;
+};
 interface ResolvedTheme {
     primary: (text: string) => string;
     success: (text: string) => string;
@@ -215,6 +295,10 @@ interface ResolvedTheme {
     accent: (text: string) => string;
     bold: (text: string) => string;
     icons: Required<NonNullable<ThemeConfig['icons']>>;
+    spinner: {
+        frames: string[];
+        interval: number;
+    };
 }
 interface WizardRenderer {
     renderText(step: TextStepConfig, state: WizardState, theme: ResolvedTheme): Promise<string>;
@@ -232,6 +316,7 @@ interface WizardRenderer {
     renderGroupHeader(group: string, theme: ResolvedTheme): void;
     renderSummary(answers: Record<string, unknown>, steps: StepConfig[], theme: ResolvedTheme): void;
     clear(): void;
+    onEvent?(event: WizardEvent, theme: ResolvedTheme): void;
 }
 
 declare function parseWizardConfig(raw: unknown): WizardConfig;
@@ -250,6 +335,79 @@ declare function wizardReducer(state: WizardState, transition: WizardTransition,
 
 declare function resolveTheme(themeConfig?: ThemeConfig): ResolvedTheme;
 
+interface SpinnerConfig {
+    frames: string[];
+    interval: number;
+}
+declare const spinners: {
+    readonly dots: {
+        readonly interval: 80;
+        readonly frames: ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+    };
+    readonly dots2: {
+        readonly interval: 80;
+        readonly frames: ["⣾", "⣽", "⣻", "⢿", "⡿", "⣟", "⣯", "⣷"];
+    };
+    readonly line: {
+        readonly interval: 130;
+        readonly frames: ["-", "\\", "|", "/"];
+    };
+    readonly arc: {
+        readonly interval: 100;
+        readonly frames: ["◜", "◠", "◝", "◞", "◡", "◟"];
+    };
+    readonly circle: {
+        readonly interval: 80;
+        readonly frames: ["◒", "◐", "◓", "◑"];
+    };
+    readonly circleHalves: {
+        readonly interval: 50;
+        readonly frames: ["◐", "◓", "◑", "◒"];
+    };
+    readonly triangle: {
+        readonly interval: 50;
+        readonly frames: ["◢", "◣", "◤", "◥"];
+    };
+    readonly pipe: {
+        readonly interval: 100;
+        readonly frames: ["┤", "┘", "┴", "└", "├", "┌", "┬", "┐"];
+    };
+    readonly arrow: {
+        readonly interval: 100;
+        readonly frames: ["←", "↖", "↑", "↗", "→", "↘", "↓", "↙"];
+    };
+    readonly arrow3: {
+        readonly interval: 120;
+        readonly frames: ["▹▹▹▹▹", "▸▹▹▹▹", "▹▸▹▹▹", "▹▹▸▹▹", "▹▹▹▸▹", "▹▹▹▹▸"];
+    };
+    readonly bouncingBar: {
+        readonly interval: 80;
+        readonly frames: ["[    ]", "[=   ]", "[==  ]", "[=== ]", "[====]", "[ ===]", "[  ==]", "[   =]", "[    ]", "[   =]", "[  ==]", "[ ===]", "[====]", "[=== ]", "[==  ]", "[=   ]"];
+    };
+    readonly bouncingBall: {
+        readonly interval: 80;
+        readonly frames: ["( ●    )", "(  ●   )", "(   ●  )", "(    ● )", "(     ●)", "(    ● )", "(   ●  )", "(  ●   )", "( ●    )", "(●     )"];
+    };
+    readonly simpleDots: {
+        readonly interval: 400;
+        readonly frames: [".  ", ".. ", "...", "   "];
+    };
+    readonly aesthetic: {
+        readonly interval: 80;
+        readonly frames: ["▰▱▱▱▱▱▱", "▰▰▱▱▱▱▱", "▰▰▰▱▱▱▱", "▰▰▰▰▱▱▱", "▰▰▰▰▰▱▱", "▰▰▰▰▰▰▱", "▰▰▰▰▰▰▰", "▰▱▱▱▱▱▱"];
+    };
+    readonly star: {
+        readonly interval: 70;
+        readonly frames: ["✶", "✸", "✹", "✺", "✹", "✷"];
+    };
+};
+type SpinnerName = keyof typeof spinners;
+declare const DEFAULT_SPINNER: SpinnerName;
+declare function resolveSpinner(config?: string | {
+    frames: string[];
+    interval?: number;
+}): SpinnerConfig;
+
 declare function resolveEnvDefault(value: string | undefined): string | undefined;
 
 interface StepPlugin {
@@ -280,8 +438,10 @@ interface RunWizardOptions {
         dir?: string;
     };
     mru?: boolean;
+    resume?: boolean;
+    configFilePath?: string;
 }
-declare function runPreFlightChecks(checks: PreFlightCheck[], theme: ResolvedTheme): void;
+declare function runPreFlightChecks(checks: PreFlightCheck[], theme: ResolvedTheme, renderer?: WizardRenderer): void;
 declare function runWizard(config: WizardConfig, options?: RunWizardOptions): Promise<Record<string, unknown>>;
 
 declare function defineWizard(config: WizardConfig): WizardConfig;
@@ -309,6 +469,12 @@ declare class InquirerRenderer implements WizardRenderer {
  * Array values are joined with ", ". Unresolved placeholders remain as-is.
  */
 declare function resolveTemplate(template: string, answers: Record<string, unknown>): string;
+/**
+ * Resolve {{stepId}} placeholders strictly — throws if any placeholder
+ * references a step-id not found in the answers map.
+ * Used by actions where missing answers indicate a config error.
+ */
+declare function resolveTemplateStrict(template: string, answers: Record<string, unknown>): string;
 
 /**
  * Render a figlet ASCII art banner for the wizard name.
@@ -346,9 +512,47 @@ declare class InkRenderer implements WizardRenderer {
     clear(): void;
 }
 
+declare class ClackRenderer extends InquirerRenderer {
+    private spinnerInterval;
+    private spinnerFrameIndex;
+    renderStepHeader(): void;
+    renderGroupHeader(): void;
+    renderSummary(answers: Record<string, unknown>, steps: StepConfig[], theme: ResolvedTheme): void;
+    onEvent(event: WizardEvent, theme: ResolvedTheme): void;
+    private handleSessionStart;
+    private handleSessionEnd;
+    private handleStepComplete;
+    private formatValue;
+    private writeNoteBox;
+    private startSpinner;
+    private stopSpinner;
+}
+
 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 };
+interface SavedProgress {
+    currentStepId: string;
+    answers: Record<string, unknown>;
+    history: string[];
+    savedAt: string;
+}
+declare function saveProgress(wizardName: string, state: {
+    currentStepId: string;
+    answers: Record<string, unknown>;
+    history: string[];
+}, customDir?: string, excludeStepIds?: string[]): void;
+declare function loadProgress(wizardName: string, customDir?: string): SavedProgress | null;
+declare function clearProgress(wizardName: string, customDir?: string): void;
+
+interface PipelineStep {
+    config: WizardConfig | string;
+    when?: Condition;
+    mockAnswers?: Record<string, unknown>;
+    options?: Omit<RunWizardOptions, 'mockAnswers' | 'templateAnswers'>;
+}
+declare function runPipeline(steps: PipelineStep[], globalOptions?: Omit<RunWizardOptions, 'mockAnswers' | 'templateAnswers'>): Promise<Record<string, Record<string, unknown>>>;
+
+export { type ActionConfig, ClackRenderer, type Condition, type ConfirmStepConfig, DEFAULT_SPINNER, type EditorStepConfig, type GrimoirePlugin, InkRenderer, InquirerRenderer, type MessageStepConfig, type MultiSelectStepConfig, type NoteStepConfig, type NumberStepConfig, type OnCompleteHandler, type PasswordStepConfig, type PathStepConfig, type PipelineStep, type PreFlightCheck, type ResolvedTheme, type RunWizardOptions, type SavedProgress, type SearchStepConfig, type SelectChoice, type SelectOption, type SelectStepConfig, type SeparatorOption, type SpinnerConfig, type SpinnerName, type StepConfig, type StepPlugin, type TextStepConfig, type ThemeConfig, type ToggleStepConfig, type ValidationRule, type WizardConfig, type WizardEvent, type WizardRenderer, type WizardState, type WizardTransition, clearCache, clearMruData, clearPlugins, clearProgress, createWizardState, defineWizard, deleteTemplate, evaluateCondition, getCacheDir, getOrderedOptions, getPluginStep, getVisibleSteps, isStepVisible, listTemplates, loadCachedAnswers, loadProgress, loadTemplate, loadWizardConfig, parseWizardConfig, parseWizardYAML, recordSelection, registerPlugin, renderBanner, resolveEnvDefault, resolveNextStep, resolveSpinner, resolveTemplate, resolveTemplateStrict, resolveTheme, runPipeline, runPreFlightChecks, runWizard, saveCachedAnswers, saveProgress, saveTemplate, slugify, spinners, validateStepAnswer, wizardReducer };