grimoire-wizard 0.4.0 → 0.5.0

package/dist/index.d.ts

@@ -164,6 +164,10 @@ interface ThemeConfig {
         stepPending?: string;
         pointer?: string;
     };
+    spinner?: string | {
+        frames: string[];
+        interval?: number;
+    };
 }
 interface PreFlightCheck {
     name: string;
@@ -175,6 +179,10 @@ interface ActionConfig {
     run: string;
     when?: Condition;
 }
+type OnCompleteHandler = (context: {
+    answers: Record<string, unknown>;
+    config: WizardConfig;
+}) => Promise<void> | void;
 interface WizardConfig {
     meta: {
         name: string;
@@ -191,6 +199,7 @@ interface WizardConfig {
     extends?: string;
     checks?: PreFlightCheck[];
     actions?: ActionConfig[];
+    onComplete?: string;
 }
 interface WizardState {
     currentStepId: string;
@@ -268,6 +277,13 @@ type WizardEvent = {
 } | {
     type: 'action:fail';
     name: string;
+} | {
+    type: 'oncomplete:start';
+} | {
+    type: 'oncomplete:pass';
+} | {
+    type: 'oncomplete:fail';
+    error: string;
 };
 interface ResolvedTheme {
     primary: (text: string) => string;
@@ -279,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>;
@@ -315,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 {
@@ -346,6 +439,7 @@ interface RunWizardOptions {
     };
     mru?: boolean;
     resume?: boolean;
+    configFilePath?: string;
 }
 declare function runPreFlightChecks(checks: PreFlightCheck[], theme: ResolvedTheme, renderer?: WizardRenderer): void;
 declare function runWizard(config: WizardConfig, options?: RunWizardOptions): Promise<Record<string, unknown>>;
@@ -375,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.
@@ -455,4 +555,4 @@ interface PipelineStep {
 }
 declare function runPipeline(steps: PipelineStep[], globalOptions?: Omit<RunWizardOptions, 'mockAnswers' | 'templateAnswers'>): Promise<Record<string, Record<string, unknown>>>;
 
-export { type ActionConfig, ClackRenderer, type Condition, type ConfirmStepConfig, type EditorStepConfig, type GrimoirePlugin, InkRenderer, InquirerRenderer, type MessageStepConfig, type MultiSelectStepConfig, type NoteStepConfig, type NumberStepConfig, 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 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, resolveTemplate, resolveTheme, runPipeline, runPreFlightChecks, runWizard, saveCachedAnswers, saveProgress, saveTemplate, slugify, validateStepAnswer, wizardReducer };
+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 };

package/dist/index.js

@@ -218,7 +218,14 @@ var init_schema = __esm({
         stepDone: z.string().optional(),
         stepPending: z.string().optional(),
         pointer: z.string().optional()
-      }).optional()
+      }).optional(),
+      spinner: z.union([
+        z.string(),
+        z.object({
+          frames: z.array(z.string()).min(1),
+          interval: z.number().positive().optional()
+        })
+      ]).optional()
     });
     preFlightCheckSchema = z.object({
       name: z.string(),
@@ -245,7 +252,8 @@ var init_schema = __esm({
       }).optional(),
       extends: z.string().optional(),
       checks: z.array(preFlightCheckSchema).optional(),
-      actions: z.array(actionConfigSchema).optional()
+      actions: z.array(actionConfigSchema).optional(),
+      onComplete: z.string().optional()
     }).superRefine((config, ctx) => {
       const stepIds = /* @__PURE__ */ new Set();
       for (const step of config.steps) {
@@ -869,6 +877,41 @@ var THEME_PRESETS = {
 };
 var PRESET_NAMES = Object.keys(THEME_PRESETS);
 
+// src/spinners.ts
+var spinners = {
+  dots: { interval: 80, frames: ["\u280B", "\u2819", "\u2839", "\u2838", "\u283C", "\u2834", "\u2826", "\u2827", "\u2807", "\u280F"] },
+  dots2: { interval: 80, frames: ["\u28FE", "\u28FD", "\u28FB", "\u28BF", "\u287F", "\u28DF", "\u28EF", "\u28F7"] },
+  line: { interval: 130, frames: ["-", "\\", "|", "/"] },
+  arc: { interval: 100, frames: ["\u25DC", "\u25E0", "\u25DD", "\u25DE", "\u25E1", "\u25DF"] },
+  circle: { interval: 80, frames: ["\u25D2", "\u25D0", "\u25D3", "\u25D1"] },
+  circleHalves: { interval: 50, frames: ["\u25D0", "\u25D3", "\u25D1", "\u25D2"] },
+  triangle: { interval: 50, frames: ["\u25E2", "\u25E3", "\u25E4", "\u25E5"] },
+  pipe: { interval: 100, frames: ["\u2524", "\u2518", "\u2534", "\u2514", "\u251C", "\u250C", "\u252C", "\u2510"] },
+  arrow: { interval: 100, frames: ["\u2190", "\u2196", "\u2191", "\u2197", "\u2192", "\u2198", "\u2193", "\u2199"] },
+  arrow3: { interval: 120, frames: ["\u25B9\u25B9\u25B9\u25B9\u25B9", "\u25B8\u25B9\u25B9\u25B9\u25B9", "\u25B9\u25B8\u25B9\u25B9\u25B9", "\u25B9\u25B9\u25B8\u25B9\u25B9", "\u25B9\u25B9\u25B9\u25B8\u25B9", "\u25B9\u25B9\u25B9\u25B9\u25B8"] },
+  bouncingBar: { interval: 80, frames: ["[    ]", "[=   ]", "[==  ]", "[=== ]", "[====]", "[ ===]", "[  ==]", "[   =]", "[    ]", "[   =]", "[  ==]", "[ ===]", "[====]", "[=== ]", "[==  ]", "[=   ]"] },
+  bouncingBall: { interval: 80, frames: ["( \u25CF    )", "(  \u25CF   )", "(   \u25CF  )", "(    \u25CF )", "(     \u25CF)", "(    \u25CF )", "(   \u25CF  )", "(  \u25CF   )", "( \u25CF    )", "(\u25CF     )"] },
+  simpleDots: { interval: 400, frames: [".  ", ".. ", "...", "   "] },
+  aesthetic: { interval: 80, frames: ["\u25B0\u25B1\u25B1\u25B1\u25B1\u25B1\u25B1", "\u25B0\u25B0\u25B1\u25B1\u25B1\u25B1\u25B1", "\u25B0\u25B0\u25B0\u25B1\u25B1\u25B1\u25B1", "\u25B0\u25B0\u25B0\u25B0\u25B1\u25B1\u25B1", "\u25B0\u25B0\u25B0\u25B0\u25B0\u25B1\u25B1", "\u25B0\u25B0\u25B0\u25B0\u25B0\u25B0\u25B1", "\u25B0\u25B0\u25B0\u25B0\u25B0\u25B0\u25B0", "\u25B0\u25B1\u25B1\u25B1\u25B1\u25B1\u25B1"] },
+  star: { interval: 70, frames: ["\u2736", "\u2738", "\u2739", "\u273A", "\u2739", "\u2737"] }
+};
+var DEFAULT_SPINNER = "circle";
+function resolveSpinner(config) {
+  if (!config) {
+    return spinners[DEFAULT_SPINNER];
+  }
+  if (typeof config === "string") {
+    if (config in spinners) {
+      return spinners[config];
+    }
+    throw new Error(`Unknown spinner preset: "${config}". Available: ${Object.keys(spinners).join(", ")}`);
+  }
+  return {
+    frames: config.frames,
+    interval: config.interval ?? 80
+  };
+}
+
 // src/theme.ts
 var DEFAULT_TOKENS = {
   primary: "#5B9BD5",
@@ -898,7 +941,8 @@ function resolveTheme(themeConfig) {
     muted: chalk.hex(tokens.muted),
     accent: chalk.hex(tokens.accent),
     bold: chalk.bold,
-    icons
+    icons,
+    spinner: resolveSpinner(themeConfig?.spinner)
   };
 }
 
@@ -925,6 +969,8 @@ function resolveEnvDefaultBoolean(value) {
 
 // src/runner.ts
 import { execSync } from "child_process";
+import { resolve as resolve2, dirname as dirname2 } from "path";
+import { pathToFileURL } from "url";
 
 // src/renderers/inquirer.ts
 import {
@@ -1125,6 +1171,17 @@ function resolveTemplate(template, answers) {
     return _match;
   });
 }
+function resolveTemplateStrict(template, answers) {
+  return template.replace(/\{\{([^}]+)\}\}/g, (_match, key) => {
+    const trimmedKey = key.trim();
+    if (!(trimmedKey in answers)) {
+      throw new Error(`Action references unknown step "${trimmedKey}"`);
+    }
+    const value = answers[trimmedKey];
+    if (Array.isArray(value)) return value.join(", ");
+    return String(value);
+  });
+}
 
 // src/banner.ts
 import figlet from "figlet";
@@ -1625,8 +1682,13 @@ async function runWizard(config, options) {
     if (state.status === "done" && !quiet) {
       renderer.renderSummary(state.answers, config.steps, theme);
     }
-    if (state.status === "done" && config.actions && config.actions.length > 0 && !isMock) {
-      await executeActions(config.actions, state.answers, theme, renderer);
+    if (state.status === "done" && !isMock) {
+      if (config.onComplete) {
+        await executeOnComplete(config.onComplete, options?.configFilePath, state.answers, config, theme, renderer);
+      }
+      if (config.actions && config.actions.length > 0) {
+        await executeActions(config.actions, state.answers, theme, renderer);
+      }
     }
     emitEvent(renderer, { type: "session:end", answers: state.answers, cancelled: state.status === "cancelled" }, theme);
     if (state.status === "done" && cacheEnabled) {
@@ -1841,6 +1903,25 @@ function resolveStepTemplates(step, answers) {
       };
   }
 }
+async function executeOnComplete(handlerPath, configFilePath, answers, config, theme, renderer) {
+  if (renderer) emitEvent(renderer, { type: "oncomplete:start" }, theme);
+  const resolvedPath = configFilePath ? resolve2(dirname2(configFilePath), handlerPath) : resolve2(handlerPath);
+  try {
+    const mod = await import(pathToFileURL(resolvedPath).href);
+    if (typeof mod.default !== "function") {
+      throw new Error(`onComplete handler "${handlerPath}" must export a default function`);
+    }
+    await mod.default({ answers, config });
+    if (renderer) emitEvent(renderer, { type: "oncomplete:pass" }, theme);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    if (renderer) emitEvent(renderer, { type: "oncomplete:fail", error: message }, theme);
+    console.log(`
+  ${theme.error("\u2717")} onComplete handler failed: ${message}
+`);
+    throw error;
+  }
+}
 async function executeActions(actions, answers, theme, renderer) {
   if (renderer) emitEvent(renderer, { type: "actions:start" }, theme);
   console.log(`
@@ -1850,8 +1931,8 @@ async function executeActions(actions, answers, theme, renderer) {
     if (action.when && !evaluateCondition(action.when, answers)) {
       continue;
     }
-    const resolvedCommand = resolveTemplate(action.run, answers);
-    const resolvedName = action.name ? resolveTemplate(action.name, answers) : void 0;
+    const resolvedCommand = resolveTemplateStrict(action.run, answers);
+    const resolvedName = action.name ? resolveTemplateStrict(action.name, answers) : void 0;
     const label = resolvedName ?? resolvedCommand;
     try {
       execSync(resolvedCommand, { stdio: "pipe" });
@@ -2102,7 +2183,6 @@ var S_STEP_ERROR = u("\u25B2", "x");
 var S_CORNER_TR = u("\u256E", "+");
 var S_CORNER_BR = u("\u256F", "+");
 var S_BAR_H = u("\u2500", "-");
-var S_SPINNER_FRAMES = unicode ? ["\u25D2", "\u25D0", "\u25D3", "\u25D1"] : ["\u2022", "o", "O", "0"];
 
 // src/renderers/clack.ts
 var ClackRenderer = class extends InquirerRenderer {
@@ -2241,13 +2321,14 @@ var ClackRenderer = class extends InquirerRenderer {
     process.stdout.write(`${chalk2.gray(S_BAR)}  ${chalk2.gray(`\u256E${bottomLine}`)}
 `);
   }
-  startSpinner(message, _theme) {
+  startSpinner(message, theme) {
     this.spinnerFrameIndex = 0;
+    const { frames, interval } = theme.spinner;
     this.spinnerInterval = setInterval(() => {
-      const frame = S_SPINNER_FRAMES[this.spinnerFrameIndex % S_SPINNER_FRAMES.length];
+      const frame = frames[this.spinnerFrameIndex % frames.length];
       process.stdout.write(`\r${chalk2.gray(S_BAR)}  ${chalk2.cyan(frame ?? "")}  ${message}`);
       this.spinnerFrameIndex++;
-    }, 80);
+    }, interval);
   }
   stopSpinner(message, theme) {
     if (this.spinnerInterval) {
@@ -2345,6 +2426,7 @@ async function runPipeline(steps, globalOptions) {
 }
 export {
   ClackRenderer,
+  DEFAULT_SPINNER,
   InkRenderer,
   InquirerRenderer,
   clearCache,
@@ -2372,7 +2454,9 @@ export {
   renderBanner,
   resolveEnvDefault,
   resolveNextStep,
+  resolveSpinner,
   resolveTemplate,
+  resolveTemplateStrict,
   resolveTheme,
   runPipeline,
   runPreFlightChecks,
@@ -2381,6 +2465,7 @@ export {
   saveProgress,
   saveTemplate,
   slugify,
+  spinners,
   validateStepAnswer,
   wizardReducer
 };