grimoire-wizard 0.3.1 → 0.5.0

package/dist/cli.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
 // src/cli.ts
-import chalk2 from "chalk";
+import chalk3 from "chalk";
 import { program } from "commander";
 
 // src/parser.ts
@@ -146,6 +146,10 @@ var messageStepSchema = z.object({
   ...baseStepFields,
   type: z.literal("message")
 });
+var noteStepSchema = z.object({
+  ...baseStepFields,
+  type: z.literal("note")
+});
 var stepConfigSchema = z.discriminatedUnion("type", [
   textStepSchema,
   selectStepSchema,
@@ -157,13 +161,15 @@ var stepConfigSchema = z.discriminatedUnion("type", [
   editorStepSchema,
   pathStepSchema,
   toggleStepSchema,
-  messageStepSchema
+  messageStepSchema,
+  noteStepSchema
 ]);
 var hexColorSchema = z.string().regex(
   /^#[0-9a-fA-F]{6}$/,
   "Must be a 6-digit hex color (e.g., #FF0000)"
 );
 var themeConfigSchema = z.object({
+  preset: z.enum(["default", "catppuccin", "dracula", "nord", "tokyonight", "monokai"]).optional(),
   tokens: z.object({
     primary: hexColorSchema.optional(),
     success: hexColorSchema.optional(),
@@ -178,7 +184,14 @@ var themeConfigSchema = z.object({
     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()
 });
 var preFlightCheckSchema = z.object({
   name: z.string(),
@@ -194,7 +207,8 @@ var wizardConfigSchema = z.object({
   meta: z.object({
     name: z.string(),
     version: z.string().optional(),
-    description: z.string().optional()
+    description: z.string().optional(),
+    review: z.boolean().optional()
   }),
   theme: themeConfigSchema.optional(),
   steps: z.array(stepConfigSchema).min(1),
@@ -204,7 +218,8 @@ var wizardConfigSchema = z.object({
   }).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) {
@@ -479,6 +494,8 @@ async function loadWizardConfig(filePath) {
 
 // src/runner.ts
 import { execSync } from "child_process";
+import { resolve as resolve2, dirname as dirname2 } from "path";
+import { pathToFileURL } from "url";
 
 // src/conditions.ts
 function isRecord(value) {
@@ -758,6 +775,102 @@ function applyValidationRule(rule, value) {
 
 // src/theme.ts
 import chalk from "chalk";
+
+// src/themes/presets.ts
+var THEME_PRESETS = {
+  default: {
+    primary: "#7C3AED",
+    success: "#10B981",
+    error: "#EF4444",
+    warning: "#F59E0B",
+    info: "#3B82F6",
+    muted: "#6B7280",
+    accent: "#8B5CF6"
+  },
+  catppuccin: {
+    primary: "#cba6f7",
+    success: "#a6e3a1",
+    error: "#f38ba8",
+    warning: "#fab387",
+    info: "#74c7ec",
+    muted: "#6c7086",
+    accent: "#f5c2e7"
+  },
+  dracula: {
+    primary: "#bd93f9",
+    success: "#50fa7b",
+    error: "#ff5555",
+    warning: "#ffb86c",
+    info: "#8be9fd",
+    muted: "#6272a4",
+    accent: "#ff79c6"
+  },
+  nord: {
+    primary: "#88c0d0",
+    success: "#a3be8c",
+    error: "#bf616a",
+    warning: "#ebcb8b",
+    info: "#81a1c1",
+    muted: "#4c566a",
+    accent: "#b48ead"
+  },
+  tokyonight: {
+    primary: "#7aa2f7",
+    success: "#9ece6a",
+    error: "#f7768e",
+    warning: "#e0af68",
+    info: "#7dcfff",
+    muted: "#565f89",
+    accent: "#bb9af7"
+  },
+  monokai: {
+    primary: "#ab9df2",
+    success: "#a9dc76",
+    error: "#ff6188",
+    warning: "#ffd866",
+    info: "#78dce8",
+    muted: "#727072",
+    accent: "#fc9867"
+  }
+};
+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",
   success: "#6BCB77",
@@ -774,7 +887,8 @@ var DEFAULT_ICONS = {
   pointer: "\u203A"
 };
 function resolveTheme(themeConfig) {
-  const tokens = { ...DEFAULT_TOKENS, ...themeConfig?.tokens };
+  const presetTokens = themeConfig?.preset ? THEME_PRESETS[themeConfig.preset] : void 0;
+  const tokens = { ...DEFAULT_TOKENS, ...presetTokens, ...themeConfig?.tokens };
   const icons = { ...DEFAULT_ICONS, ...themeConfig?.icons };
   return {
     primary: chalk.hex(tokens.primary),
@@ -785,7 +899,8 @@ function resolveTheme(themeConfig) {
     muted: chalk.hex(tokens.muted),
     accent: chalk.hex(tokens.accent),
     bold: chalk.bold,
-    icons
+    icons,
+    spinner: resolveSpinner(themeConfig?.spinner)
   };
 }
 
@@ -1009,6 +1124,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";
@@ -1116,14 +1242,66 @@ function clearCache(wizardName, customDir) {
   }
 }
 
-// src/mru.ts
-import { readFileSync as readFileSync3, writeFileSync as writeFileSync2, mkdirSync as mkdirSync2, existsSync } from "fs";
+// src/progress.ts
+import { mkdirSync as mkdirSync2, readFileSync as readFileSync3, writeFileSync as writeFileSync2, unlinkSync as unlinkSync2 } from "fs";
 import { join as join2 } from "path";
 import { homedir as homedir2 } from "os";
-var MRU_DIR = join2(homedir2(), ".config", "grimoire", "mru");
+var DEFAULT_PROGRESS_DIR = join2(homedir2(), ".config", "grimoire", "progress");
+function getProgressFilePath(wizardName, customDir) {
+  const dir = customDir ?? DEFAULT_PROGRESS_DIR;
+  return join2(dir, `${slugify(wizardName)}.json`);
+}
+function saveProgress(wizardName, state, customDir, excludeStepIds) {
+  try {
+    const dir = customDir ?? DEFAULT_PROGRESS_DIR;
+    mkdirSync2(dir, { recursive: true });
+    const excludeSet = new Set(excludeStepIds ?? []);
+    const filteredAnswers = {};
+    for (const [key, value] of Object.entries(state.answers)) {
+      if (!excludeSet.has(key)) {
+        filteredAnswers[key] = value;
+      }
+    }
+    const progress = {
+      currentStepId: state.currentStepId,
+      answers: filteredAnswers,
+      history: state.history,
+      savedAt: (/* @__PURE__ */ new Date()).toISOString()
+    };
+    const filePath = getProgressFilePath(wizardName, customDir);
+    writeFileSync2(filePath, JSON.stringify(progress, null, 2) + "\n", "utf-8");
+  } catch {
+  }
+}
+function loadProgress(wizardName, customDir) {
+  try {
+    const filePath = getProgressFilePath(wizardName, customDir);
+    const raw = readFileSync3(filePath, "utf-8");
+    const parsed = JSON.parse(raw);
+    if (typeof parsed === "object" && parsed !== null && !Array.isArray(parsed) && "currentStepId" in parsed && "answers" in parsed && "history" in parsed && "savedAt" in parsed) {
+      return parsed;
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+function clearProgress(wizardName, customDir) {
+  try {
+    const filePath = getProgressFilePath(wizardName, customDir);
+    unlinkSync2(filePath);
+  } catch {
+  }
+}
+
+// src/mru.ts
+import { readFileSync as readFileSync4, writeFileSync as writeFileSync3, mkdirSync as mkdirSync3, existsSync } from "fs";
+import { join as join3 } from "path";
+import { homedir as homedir3 } from "os";
+var MRU_DIR = join3(homedir3(), ".config", "grimoire", "mru");
 function getMruFilePath(wizardName) {
   const safeName = wizardName.replace(/[^a-zA-Z0-9_-]/g, "_");
-  return join2(MRU_DIR, `${safeName}.json`);
+  return join3(MRU_DIR, `${safeName}.json`);
 }
 function loadMruData(wizardName) {
   const filePath = getMruFilePath(wizardName);
@@ -1131,7 +1309,7 @@ function loadMruData(wizardName) {
     if (!existsSync(filePath)) {
       return {};
     }
-    const raw = readFileSync3(filePath, "utf-8");
+    const raw = readFileSync4(filePath, "utf-8");
     const parsed = JSON.parse(raw);
     if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
       return {};
@@ -1144,8 +1322,8 @@ function loadMruData(wizardName) {
 function saveMruData(wizardName, data) {
   const filePath = getMruFilePath(wizardName);
   try {
-    mkdirSync2(MRU_DIR, { recursive: true });
-    writeFileSync2(filePath, JSON.stringify(data, null, 2) + "\n", "utf-8");
+    mkdirSync3(MRU_DIR, { recursive: true });
+    writeFileSync3(filePath, JSON.stringify(data, null, 2) + "\n", "utf-8");
   } catch {
   }
 }
@@ -1199,13 +1377,21 @@ function getOrderedOptions(wizardName, stepId, options) {
 }
 
 // src/runner.ts
-function runPreFlightChecks(checks, theme) {
+function emitEvent(renderer, event, theme) {
+  if (renderer.onEvent) {
+    renderer.onEvent(event, theme);
+  }
+}
+function runPreFlightChecks(checks, theme, renderer) {
+  if (renderer) emitEvent(renderer, { type: "checks:start", checks }, theme);
   for (const check of checks) {
     try {
       execSync(check.run, { stdio: "pipe" });
       console.log(`  ${theme.success("\u2713")} ${check.name}`);
+      if (renderer) emitEvent(renderer, { type: "check:pass", name: check.name }, theme);
     } catch {
       console.log(`  ${theme.error("\u2717")} ${check.name}: ${check.message}`);
+      if (renderer) emitEvent(renderer, { type: "check:fail", name: check.name, message: check.message }, theme);
       throw new Error(`Pre-flight check failed: ${check.name} \u2014 ${check.message}`);
     }
   }
@@ -1215,7 +1401,7 @@ function getMockValue(step, mockAnswers) {
   if (step.id in mockAnswers) {
     return mockAnswers[step.id];
   }
-  if (step.type === "message") {
+  if (step.type === "message" || step.type === "note") {
     return true;
   }
   const defaultValue = getStepDefault(step);
@@ -1243,6 +1429,7 @@ function getStepDefault(step) {
       return step.default;
     case "password":
     case "message":
+    case "note":
       return void 0;
   }
 }
@@ -1256,6 +1443,21 @@ async function runWizard(config, options) {
   const cacheDir = typeof options?.cache === "object" ? options.cache.dir : void 0;
   const mruEnabled = !isMock && options?.mru !== false;
   let state = createWizardState(config);
+  const resumeEnabled = !isMock && options?.resume !== false;
+  if (resumeEnabled) {
+    const saved = loadProgress(config.meta.name);
+    if (saved) {
+      const stepExists = config.steps.some((s) => s.id === saved.currentStepId);
+      if (stepExists) {
+        state = {
+          ...state,
+          currentStepId: saved.currentStepId,
+          answers: { ...state.answers, ...saved.answers },
+          history: saved.history
+        };
+      }
+    }
+  }
   const cachedAnswers = cacheEnabled ? loadCachedAnswers(config.meta.name, cacheDir) : void 0;
   const userPlugins = options?.plugins;
   if (userPlugins) {
@@ -1265,103 +1467,174 @@ async function runWizard(config, options) {
   }
   try {
     if (!isMock && config.checks && config.checks.length > 0) {
-      runPreFlightChecks(config.checks, theme);
+      runPreFlightChecks(config.checks, theme, renderer);
     }
     if (!quiet) {
       printWizardHeader(config, theme, options?.plain);
     }
-    let previousGroup;
-    while (state.status === "running") {
-      const visibleSteps = getVisibleSteps(config, state.answers);
-      const currentStep = config.steps.find((s) => s.id === state.currentStepId);
-      if (!currentStep) {
-        throw new Error(`Current step not found: "${state.currentStepId}"`);
-      }
-      if (!isMock) {
+    const visibleStepsForCount = getVisibleSteps(config, state.answers);
+    emitEvent(renderer, { type: "session:start", wizard: config.meta.name, description: config.meta.description, totalSteps: visibleStepsForCount.length }, theme);
+    let needsReview = true;
+    while (needsReview) {
+      let previousGroup;
+      while (state.status === "running") {
+        const visibleSteps = getVisibleSteps(config, state.answers);
+        const currentStep = config.steps.find((s) => s.id === state.currentStepId);
+        if (!currentStep) {
+          throw new Error(`Current step not found: "${state.currentStepId}"`);
+        }
         if (currentStep.group !== void 0 && currentStep.group !== previousGroup) {
           const resolvedGroup = resolveTemplate(currentStep.group, state.answers);
-          renderer.renderGroupHeader(resolvedGroup, theme);
+          if (!isMock) {
+            renderer.renderGroupHeader(resolvedGroup, theme);
+          }
+          emitEvent(renderer, { type: "group:start", group: resolvedGroup }, theme);
         }
         previousGroup = currentStep.group;
         const stepIndex = visibleSteps.findIndex((s) => s.id === state.currentStepId);
         const resolvedMessage = resolveTemplate(currentStep.message, state.answers);
         const resolvedDescription = currentStep.description ? resolveTemplate(currentStep.description, state.answers) : void 0;
-        renderer.renderStepHeader(stepIndex, visibleSteps.length, resolvedMessage, theme, resolvedDescription);
-      }
-      if (options?.onBeforeStep) {
-        await options.onBeforeStep(currentStep.id, currentStep, state);
-      }
-      const pluginStep = getPluginStep(currentStep.type);
-      const resolvedStep = pluginStep ? currentStep : resolveStepDefaults(currentStep, cachedAnswers);
-      const withTemplate = options?.templateAnswers ? applyTemplateDefaults(resolvedStep, options.templateAnswers) : resolvedStep;
-      const templatedStep = resolveStepTemplates(withTemplate, state.answers);
-      const mruStep = mruEnabled ? applyMruOrdering(templatedStep, config.meta.name) : templatedStep;
-      try {
-        const value = isMock ? getMockValue(mruStep, mockAnswers) : pluginStep ? await pluginStep.render(toStepRecord(mruStep), state, theme) : await renderStep(renderer, mruStep, state, theme);
-        if (pluginStep?.validate) {
-          const pluginError = pluginStep.validate(value, toStepRecord(templatedStep));
-          if (pluginError) {
+        if (!isMock) {
+          renderer.renderStepHeader(stepIndex, visibleSteps.length, resolvedMessage, theme, resolvedDescription);
+        }
+        emitEvent(renderer, { type: "step:start", stepId: currentStep.id, stepIndex, totalVisible: visibleSteps.length, step: currentStep }, theme);
+        if (currentStep.type === "note") {
+          emitEvent(renderer, { type: "note", title: resolvedMessage, body: resolvedDescription ?? "" }, theme);
+        }
+        if (options?.onBeforeStep) {
+          await options.onBeforeStep(currentStep.id, currentStep, state);
+        }
+        const pluginStep = getPluginStep(currentStep.type);
+        const resolvedStep = pluginStep ? currentStep : resolveStepDefaults(currentStep, cachedAnswers);
+        const withTemplate = options?.templateAnswers ? applyTemplateDefaults(resolvedStep, options.templateAnswers) : resolvedStep;
+        const templatedStep = resolveStepTemplates(withTemplate, state.answers);
+        const mruStep = mruEnabled ? applyMruOrdering(templatedStep, config.meta.name) : templatedStep;
+        try {
+          const value = isMock ? getMockValue(mruStep, mockAnswers) : pluginStep ? await pluginStep.render(toStepRecord(mruStep), state, theme) : await renderStep(renderer, mruStep, state, theme);
+          if (pluginStep?.validate) {
+            const pluginError = pluginStep.validate(value, toStepRecord(templatedStep));
+            if (pluginError) {
+              if (isMock) {
+                throw new Error(
+                  `Mock mode: validation failed for step "${currentStep.id}": ${pluginError}`
+                );
+              }
+              console.log(theme.error(`
+  ${pluginError}
+`));
+              continue;
+            }
+          }
+          const nextState = wizardReducer(state, { type: "NEXT", value }, config);
+          if (nextState.errors[currentStep.id]) {
+            const errorMsg = resolveTemplate(nextState.errors[currentStep.id] ?? "", state.answers);
+            emitEvent(renderer, { type: "step:error", stepId: currentStep.id, error: errorMsg }, theme);
             if (isMock) {
               throw new Error(
-                `Mock mode: validation failed for step "${currentStep.id}": ${pluginError}`
+                `Mock mode: validation failed for step "${currentStep.id}": ${errorMsg}`
               );
             }
             console.log(theme.error(`
-  ${pluginError}
+  ${errorMsg}
 `));
+            state = { ...nextState, errors: {} };
             continue;
           }
-        }
-        const nextState = wizardReducer(state, { type: "NEXT", value }, config);
-        if (nextState.errors[currentStep.id]) {
-          const errorMsg = resolveTemplate(nextState.errors[currentStep.id] ?? "", state.answers);
-          if (isMock) {
-            throw new Error(
-              `Mock mode: validation failed for step "${currentStep.id}": ${errorMsg}`
-            );
-          }
-          console.log(theme.error(`
-  ${errorMsg}
-`));
-          state = { ...nextState, errors: {} };
-          continue;
-        }
-        if (!isMock && options?.asyncValidate) {
-          const asyncError = await options.asyncValidate(currentStep.id, value, nextState.answers);
-          if (asyncError !== null) {
-            console.log(theme.error(`
+          if (!isMock && options?.asyncValidate) {
+            const asyncError = await options.asyncValidate(currentStep.id, value, nextState.answers);
+            if (asyncError !== null) {
+              console.log(theme.error(`
   ${asyncError}
 `));
-            state = { ...nextState, errors: {} };
-            continue;
+              state = { ...nextState, errors: {} };
+              continue;
+            }
+          }
+          if (options?.onAfterStep) {
+            await options.onAfterStep(currentStep.id, value, nextState);
+          }
+          state = nextState;
+          emitEvent(renderer, { type: "step:complete", stepId: currentStep.id, value, step: currentStep }, theme);
+          if (mruEnabled && isSelectLikeStep(currentStep.type)) {
+            recordSelection(config.meta.name, currentStep.id, value);
           }
+          options?.onStepComplete?.(currentStep.id, value, state);
+        } catch (error) {
+          if (!isMock && isUserCancel(error)) {
+            state = wizardReducer(state, { type: "CANCEL" }, config);
+            options?.onCancel?.(state);
+            const passwordStepIds = config.steps.filter((s) => s.type === "password").map((s) => s.id);
+            saveProgress(config.meta.name, {
+              currentStepId: state.currentStepId,
+              answers: state.answers,
+              history: state.history
+            }, void 0, passwordStepIds);
+            emitEvent(renderer, { type: "session:end", answers: state.answers, cancelled: true }, theme);
+            if (!quiet) {
+              console.log(theme.warning("\n  Wizard cancelled.\n"));
+            }
+            return state.answers;
+          }
+          throw error;
         }
-        if (options?.onAfterStep) {
-          await options.onAfterStep(currentStep.id, value, nextState);
+      }
+      if (config.meta.review && !isMock && state.status === "done") {
+        const reviewLines = [];
+        for (const step of config.steps) {
+          const answer = state.answers[step.id];
+          if (answer === void 0) continue;
+          const display = step.type === "password" ? "****" : Array.isArray(answer) ? answer.map(String).join(", ") : String(answer);
+          reviewLines.push(`${step.id}: ${display}`);
         }
-        state = nextState;
-        if (mruEnabled && isSelectLikeStep(currentStep.type)) {
-          recordSelection(config.meta.name, currentStep.id, value);
+        emitEvent(renderer, { type: "note", title: "Review your answers", body: reviewLines.join("\n") }, theme);
+        console.log(`
+  ${theme.bold("Review your answers:")}
+`);
+        for (const line of reviewLines) {
+          console.log(`  ${line}`);
         }
-        options?.onStepComplete?.(currentStep.id, value, state);
-      } catch (error) {
-        if (!isMock && isUserCancel(error)) {
-          state = wizardReducer(state, { type: "CANCEL" }, config);
-          options?.onCancel?.(state);
-          if (!quiet) {
-            console.log(theme.warning("\n  Wizard cancelled.\n"));
-          }
-          return state.answers;
+        console.log();
+        const { confirm: confirmPrompt } = await import("@inquirer/prompts");
+        const ok = await confirmPrompt({
+          message: "Everything look right?",
+          default: true
+        });
+        if (ok) {
+          needsReview = false;
+        } else {
+          const { select: selectPrompt } = await import("@inquirer/prompts");
+          const stepsWithAnswers = config.steps.filter(
+            (s) => state.answers[s.id] !== void 0 && s.type !== "note" && s.type !== "message"
+          );
+          const stepToRevisit = await selectPrompt({
+            message: "Which step would you like to change?",
+            choices: stepsWithAnswers.map((s) => ({
+              name: `${s.id}: ${s.type === "password" ? "****" : String(state.answers[s.id] ?? "")}`,
+              value: s.id
+            }))
+          });
+          state = {
+            ...state,
+            currentStepId: stepToRevisit,
+            status: "running"
+          };
         }
-        throw error;
+      } else {
+        needsReview = false;
       }
     }
     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);
+    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) {
       const passwordStepIds = new Set(
         config.steps.filter((s) => s.type === "password").map((s) => s.id)
@@ -1374,6 +1647,9 @@ async function runWizard(config, options) {
       }
       saveCachedAnswers(config.meta.name, answersToCache, cacheDir);
     }
+    if (state.status === "done") {
+      clearProgress(config.meta.name);
+    }
     return state.answers;
   } finally {
     if (userPlugins) {
@@ -1413,6 +1689,8 @@ function renderStep(renderer, step, state, theme) {
     case "message":
       renderer.renderMessage(step, state, theme);
       return Promise.resolve(true);
+    case "note":
+      return Promise.resolve(true);
   }
 }
 function resolveStepDefaults(step, cachedAnswers) {
@@ -1463,6 +1741,7 @@ function resolveStepDefaults(step, cachedAnswers) {
     }
     case "password":
     case "message":
+    case "note":
       return step;
   }
 }
@@ -1472,7 +1751,7 @@ function getCachedDefault(stepId, cachedAnswers) {
 }
 function applyTemplateDefaults(step, templateAnswers) {
   if (!(step.id in templateAnswers)) return step;
-  if (step.type === "password" || step.type === "message") return step;
+  if (step.type === "password" || step.type === "message" || step.type === "note") return step;
   const value = templateAnswers[step.id];
   switch (step.type) {
     case "text":
@@ -1561,13 +1840,34 @@ function resolveStepTemplates(step, answers) {
     case "confirm":
     case "toggle":
     case "message":
+    case "note":
       return {
         ...step,
         description: step.description ? resolveTemplate(step.description, answers) : void 0
       };
   }
 }
-async function executeActions(actions, answers, theme) {
+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(`
   ${theme.bold("Running actions...")}
 `);
@@ -1575,14 +1875,16 @@ async function executeActions(actions, answers, theme) {
     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" });
       console.log(`  ${theme.success("\u2713")} ${label}`);
+      if (renderer) emitEvent(renderer, { type: "action:pass", name: label }, theme);
     } catch {
       console.log(`  ${theme.error("\u2717")} ${label}`);
+      if (renderer) emitEvent(renderer, { type: "action:fail", name: label }, theme);
       throw new Error(`Action failed: ${label}`);
     }
   }
@@ -1606,7 +1908,7 @@ function isUserCancel(error) {
 // src/scaffolder.ts
 import { input as input2, select as select2, confirm as confirm2, number as number2 } from "@inquirer/prompts";
 import { stringify } from "yaml";
-import { writeFileSync as writeFileSync3 } from "fs";
+import { writeFileSync as writeFileSync4 } from "fs";
 import { relative } from "path";
 var STEP_TYPE_CHOICES = [
   { name: "text", value: "text" },
@@ -1723,7 +2025,7 @@ async function scaffoldWizard(outputPath) {
       config.theme = { tokens: { primary: primaryColor } };
     }
     const yamlContent = stringify(config);
-    writeFileSync3(outputPath, yamlContent, "utf-8");
+    writeFileSync4(outputPath, yamlContent, "utf-8");
     const displayPath = relative(process.cwd(), outputPath);
     console.log(`
   \u2713 Created wizard config: ${outputPath}`);
@@ -1914,20 +2216,20 @@ complete -c grimoire -n "__fish_seen_subcommand_from completion" -f -a "fish" -d
 }
 
 // src/templates.ts
-import { mkdirSync as mkdirSync3, readFileSync as readFileSync4, writeFileSync as writeFileSync4, unlinkSync as unlinkSync2, readdirSync as readdirSync2, existsSync as existsSync2 } from "fs";
-import { join as join3 } from "path";
-import { homedir as homedir3 } from "os";
-var TEMPLATES_DIR = join3(homedir3(), ".config", "grimoire", "templates");
+import { mkdirSync as mkdirSync4, readFileSync as readFileSync5, writeFileSync as writeFileSync5, unlinkSync as unlinkSync3, readdirSync as readdirSync2, existsSync as existsSync2 } from "fs";
+import { join as join4 } from "path";
+import { homedir as homedir4 } from "os";
+var TEMPLATES_DIR = join4(homedir4(), ".config", "grimoire", "templates");
 function getWizardTemplateDir(wizardName) {
-  return join3(TEMPLATES_DIR, slugify(wizardName));
+  return join4(TEMPLATES_DIR, slugify(wizardName));
 }
 function getTemplateFilePath(wizardName, templateName) {
-  return join3(getWizardTemplateDir(wizardName), `${slugify(templateName)}.json`);
+  return join4(getWizardTemplateDir(wizardName), `${slugify(templateName)}.json`);
 }
 function loadTemplate(wizardName, templateName) {
   try {
     const filePath = getTemplateFilePath(wizardName, templateName);
-    const raw = readFileSync4(filePath, "utf-8");
+    const raw = readFileSync5(filePath, "utf-8");
     const parsed = JSON.parse(raw);
     if (typeof parsed === "object" && parsed !== null && !Array.isArray(parsed)) {
       return parsed;
@@ -1949,7 +2251,7 @@ function listTemplates(wizardName) {
 function deleteTemplate(wizardName, templateName) {
   try {
     const filePath = getTemplateFilePath(wizardName, templateName);
-    unlinkSync2(filePath);
+    unlinkSync3(filePath);
   } catch {
   }
 }
@@ -2149,25 +2451,205 @@ var InkRenderer = class {
   }
 };
 
+// src/renderers/clack.ts
+import chalk2 from "chalk";
+
+// src/renderers/symbols.ts
+function isUnicodeSupported() {
+  if (process.platform === "win32") {
+    return Boolean(process.env["WT_SESSION"]) || process.env["TERM_PROGRAM"] === "vscode";
+  }
+  return process.env["TERM"] !== "linux";
+}
+var unicode = isUnicodeSupported();
+var u = (unicodeChar, fallback) => unicode ? unicodeChar : fallback;
+var S_BAR_START = u("\u250C", "T");
+var S_BAR = u("\u2502", "|");
+var S_BAR_END = u("\u2514", "\u2014");
+var S_STEP_ACTIVE = u("\u25C6", "*");
+var S_STEP_SUBMIT = u("\u25C7", "o");
+var S_STEP_CANCEL = u("\u25A0", "x");
+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", "-");
+
+// src/renderers/clack.ts
+var ClackRenderer = class extends InquirerRenderer {
+  spinnerInterval;
+  spinnerFrameIndex = 0;
+  renderStepHeader() {
+  }
+  renderGroupHeader() {
+  }
+  renderSummary(answers, steps, theme) {
+    const entries = [];
+    for (const step of steps) {
+      const answer = answers[step.id];
+      if (answer === void 0) continue;
+      const display = Array.isArray(answer) ? answer.map(String).join(", ") : String(answer);
+      entries.push({ id: step.id, display });
+    }
+    if (entries.length === 0) return;
+    const title = "Summary";
+    const lines = entries.map((e) => `${e.id}: ${e.display}`);
+    this.writeNoteBox(title, lines, theme);
+  }
+  onEvent(event, theme) {
+    switch (event.type) {
+      case "session:start":
+        this.handleSessionStart(event, theme);
+        break;
+      case "session:end":
+        this.handleSessionEnd(event, theme);
+        break;
+      case "step:start":
+        process.stdout.write(`${chalk2.gray(S_BAR)}
+`);
+        break;
+      case "step:complete":
+        this.handleStepComplete(event, theme);
+        break;
+      case "step:error":
+        process.stdout.write(`${chalk2.gray(S_BAR)}  ${theme.error(`${S_STEP_ERROR}  ${event.error}`)}
+`);
+        break;
+      case "step:back":
+        process.stdout.write(`${chalk2.gray(S_BAR)}  ${theme.muted("\u21A9 Back")}
+`);
+        break;
+      case "group:start":
+        process.stdout.write(`${chalk2.gray(S_BAR)}
+`);
+        process.stdout.write(`${chalk2.gray(S_BAR)}  ${theme.accent(event.group)}
+`);
+        break;
+      case "note":
+        this.writeNoteBox(event.title, event.body.split("\n"), theme);
+        break;
+      case "spinner:start":
+        this.startSpinner(event.message, theme);
+        break;
+      case "spinner:stop":
+        this.stopSpinner(event.message, theme);
+        break;
+      case "checks:start":
+        process.stdout.write(`${chalk2.gray(S_BAR)}
+`);
+        process.stdout.write(`${chalk2.gray(S_BAR)}  ${theme.bold("Running checks...")}
+`);
+        break;
+      case "check:pass":
+        process.stdout.write(`${chalk2.gray(S_BAR)}  ${theme.success(S_STEP_SUBMIT)}  ${event.name}
+`);
+        break;
+      case "check:fail":
+        process.stdout.write(`${chalk2.gray(S_BAR)}  ${theme.error(S_STEP_ERROR)}  ${event.name}: ${event.message}
+`);
+        break;
+      case "actions:start":
+        process.stdout.write(`${chalk2.gray(S_BAR)}
+`);
+        process.stdout.write(`${chalk2.gray(S_BAR)}  ${theme.bold("Running actions...")}
+`);
+        break;
+      case "action:pass":
+        process.stdout.write(`${chalk2.gray(S_BAR)}  ${theme.success(S_STEP_SUBMIT)}  ${event.name}
+`);
+        break;
+      case "action:fail":
+        process.stdout.write(`${chalk2.gray(S_BAR)}  ${theme.error(S_STEP_ERROR)}  ${event.name}
+`);
+        break;
+    }
+  }
+  handleSessionStart(event, theme) {
+    process.stdout.write(`${chalk2.gray(S_BAR_START)}  ${theme.bold(event.wizard)}
+`);
+    if (event.description) {
+      process.stdout.write(`${chalk2.gray(S_BAR)}  ${theme.muted(event.description)}
+`);
+    }
+    process.stdout.write(`${chalk2.gray(S_BAR)}
+`);
+  }
+  handleSessionEnd(event, theme) {
+    if (event.cancelled) {
+      process.stdout.write(`${theme.warning(S_STEP_CANCEL)}  Cancelled
+`);
+    } else {
+      process.stdout.write(`${chalk2.gray(S_BAR_END)}  ${theme.success("You're all set!")}
+`);
+    }
+  }
+  handleStepComplete(event, theme) {
+    const displayValue = event.step.type === "password" ? "****" : this.formatValue(event.value);
+    process.stdout.write(
+      `${chalk2.gray(S_STEP_SUBMIT)}  ${event.step.message} ${chalk2.gray("\xB7")} ${theme.muted(displayValue)}
+`
+    );
+  }
+  formatValue(value) {
+    if (Array.isArray(value)) return value.map(String).join(", ");
+    if (typeof value === "boolean") return value ? "Yes" : "No";
+    return String(value);
+  }
+  writeNoteBox(title, lines, _theme) {
+    const maxLen = Math.max(title.length, ...lines.map((l) => l.length));
+    const padded = maxLen + 2;
+    const topLine = `${S_BAR_H.repeat(padded - title.length - 1)}${S_CORNER_TR}`;
+    const bottomLine = `${S_BAR_H.repeat(padded)}${S_CORNER_BR}`;
+    process.stdout.write(`${chalk2.gray(S_BAR)}
+`);
+    process.stdout.write(`${chalk2.gray(S_BAR)}  ${chalk2.gray(`\u256D${S_BAR_H} ${title} ${topLine}`)}
+`);
+    for (const line of lines) {
+      const pad = " ".repeat(maxLen - line.length);
+      process.stdout.write(`${chalk2.gray(S_BAR)}  ${chalk2.gray(S_BAR)} ${line}${pad} ${chalk2.gray(S_BAR)}
+`);
+    }
+    process.stdout.write(`${chalk2.gray(S_BAR)}  ${chalk2.gray(`\u256E${bottomLine}`)}
+`);
+  }
+  startSpinner(message, theme) {
+    this.spinnerFrameIndex = 0;
+    const { frames, interval } = theme.spinner;
+    this.spinnerInterval = setInterval(() => {
+      const frame = frames[this.spinnerFrameIndex % frames.length];
+      process.stdout.write(`\r${chalk2.gray(S_BAR)}  ${chalk2.cyan(frame ?? "")}  ${message}`);
+      this.spinnerFrameIndex++;
+    }, interval);
+  }
+  stopSpinner(message, theme) {
+    if (this.spinnerInterval) {
+      clearInterval(this.spinnerInterval);
+      this.spinnerInterval = void 0;
+    }
+    const finalMessage = message ?? "Done";
+    process.stdout.write(`\r${chalk2.gray(S_BAR)}  ${theme.success(S_STEP_SUBMIT)}  ${finalMessage}
+`);
+  }
+};
+
 // src/cli.ts
-import { writeFileSync as writeFileSync5 } from "fs";
-import { resolve as resolve2 } from "path";
+import { writeFileSync as writeFileSync6 } from "fs";
+import { resolve as resolve3 } from "path";
 import { fileURLToPath } from "url";
 import { stringify as yamlStringify } from "yaml";
 var plainMode = false;
 function applyColorMode(opts) {
   if (opts.plain || opts.color === false || process.env["NO_COLOR"] !== void 0) {
-    chalk2.level = 0;
+    chalk3.level = 0;
     plainMode = true;
   }
 }
-program.name("grimoire").description("Config-driven CLI wizard framework").version("0.3.1").option("--no-color", "Disable colored output").option("--plain", "Plain output mode (no colors, no banner)").hook("preAction", () => {
+program.name("grimoire").description("Config-driven CLI wizard framework").version("0.4.0").option("--no-color", "Disable colored output").option("--plain", "Plain output mode (no colors, no banner)").hook("preAction", () => {
   const globalOpts = program.opts();
   applyColorMode(globalOpts);
 });
-program.command("run").description("Run a wizard from a config file").argument("<config>", "Path to wizard config file (.yaml, .json, .js, .ts)").option("-o, --output <path>", "Write answers to file").option("-f, --format <format>", "Output format: json, env, yaml", "json").option("-q, --quiet", "Suppress header and summary output").option("--dry-run", "Show step plan without running the wizard").option("--mock <json>", "Run wizard with preset answers (JSON string)").option("--json", "Output structured JSON result to stdout").option("--no-cache", "Disable answer caching for this run").option("--renderer <type>", "Renderer to use: inquirer (default) or ink", "inquirer").option("--template <name>", "Load a saved template as defaults").action(async (configPath, opts) => {
+program.command("run").description("Run a wizard from a config file").argument("<config>", "Path to wizard config file (.yaml, .json, .js, .ts)").option("-o, --output <path>", "Write answers to file").option("-f, --format <format>", "Output format: json, env, yaml", "json").option("-q, --quiet", "Suppress header and summary output").option("--dry-run", "Show step plan without running the wizard").option("--mock <json>", "Run wizard with preset answers (JSON string)").option("--json", "Output structured JSON result to stdout").option("--no-cache", "Disable answer caching for this run").option("--no-resume", "Disable progress resume for this run").option("--renderer <type>", "Renderer to use: inquirer (default), ink, or clack", "inquirer").option("--template <name>", "Load a saved template as defaults").action(async (configPath, opts) => {
   try {
-    const fullPath = resolve2(configPath);
+    const fullPath = resolve3(configPath);
     const config = await loadWizardConfig(fullPath);
     if (opts.dryRun) {
       printDryRun(config);
@@ -2192,10 +2674,12 @@ program.command("run").description("Run a wizard from a config file").argument("
       plain: plainMode,
       mockAnswers,
       templateAnswers,
-      cache: opts.cache
+      cache: opts.cache,
+      resume: opts.resume,
+      configFilePath: fullPath
     });
     const rawOutputPath = opts.output ?? config.output?.path;
-    const outputPath = rawOutputPath ? resolve2(resolveTemplate(rawOutputPath, answers)) : void 0;
+    const outputPath = rawOutputPath ? resolve3(resolveTemplate(rawOutputPath, answers)) : void 0;
     if (isJsonOutput) {
       const stepsCompleted = Object.keys(answers).length;
       const result = {
@@ -2208,14 +2692,14 @@ program.command("run").description("Run a wizard from a config file").argument("
       const jsonStr = JSON.stringify(result, null, 2);
       console.log(jsonStr);
       if (outputPath) {
-        writeFileSync5(outputPath, jsonStr + "\n", "utf-8");
+        writeFileSync6(outputPath, jsonStr + "\n", "utf-8");
       }
       return;
     }
     if (outputPath) {
       const format = opts.format ?? config.output?.format ?? "json";
       const content = formatOutput(answers, format);
-      writeFileSync5(outputPath, content, "utf-8");
+      writeFileSync6(outputPath, content, "utf-8");
       if (!opts.quiet) {
         console.log(`
   Answers written to: ${outputPath}
@@ -2241,7 +2725,7 @@ program.command("run").description("Run a wizard from a config file").argument("
 });
 program.command("validate").description("Validate a wizard config file without running it").argument("<config>", "Path to wizard config file").action(async (configPath) => {
   try {
-    const fullPath = resolve2(configPath);
+    const fullPath = resolve3(configPath);
     const config = await loadWizardConfig(fullPath);
     console.log(`
   \u2713 Valid wizard config: "${config.meta.name}"`);
@@ -2258,7 +2742,7 @@ program.command("validate").description("Validate a wizard config file without r
 });
 program.command("create").description("Interactively scaffold a new wizard config file").argument("[output]", "Output file path", "wizard.yaml").action(async (output) => {
   try {
-    const resolvedPath = resolve2(output);
+    const resolvedPath = resolve3(output);
     await scaffoldWizard(resolvedPath);
   } catch (error) {
     if (error instanceof Error) {
@@ -2271,11 +2755,12 @@ program.command("create").description("Interactively scaffold a new wizard confi
 });
 program.command("demo").description("Run a demo wizard showcasing all step types").action(async () => {
   try {
-    const demoPath = resolve2(
+    const demoPath = resolve3(
       fileURLToPath(import.meta.url),
       "..",
       "..",
       "examples",
+      "yaml",
       "demo.yaml"
     );
     const config = await loadWizardConfig(demoPath);
@@ -2409,6 +2894,11 @@ function printDryRun(config) {
     console.log(`  Step ${num}  ${typeStr} ${idStr} ${msg}${suffix}`);
   }
   console.log();
+  if (config.onComplete) {
+    console.log(`  ${theme.bold("onComplete handler:")}`);
+    console.log(`    ${theme.muted(config.onComplete)}`);
+    console.log();
+  }
   if (config.actions && config.actions.length > 0) {
     console.log(`  ${theme.bold("Post-wizard actions:")}`);
     for (const action of config.actions) {
@@ -2462,7 +2952,10 @@ function resolveRenderer(rendererName) {
   if (rendererName === "ink") {
     return new InkRenderer();
   }
-  throw new Error(`Unknown renderer: "${rendererName}". Supported: inquirer, ink`);
+  if (rendererName === "clack") {
+    return new ClackRenderer();
+  }
+  throw new Error(`Unknown renderer: "${rendererName}". Supported: inquirer, ink, clack`);
 }
 function toEnvKey(key) {
   return key.replace(/[^a-zA-Z0-9]/g, "_").toUpperCase();