grimoire-wizard 0.4.0 → 0.5.0

package/README.md

@@ -1549,6 +1549,18 @@ grimoire run examples/yaml/pipeline.yaml
 
 ---
 
+## AI Agent Integration
+
+Building wizard configs with an AI assistant? Give it this reference:
+
+```
+https://raw.githubusercontent.com/YosefHayim/grimoire/main/docs/GRIMOIRE_REFERENCE.md
+```
+
+This single file contains the complete grimoire-wizard schema, all step types, conditions, actions, handler contracts, and annotated examples — everything an AI agent needs to generate correct configs in one shot.
+
+---
+
 ## License
 
 MIT. PRs welcome.

package/dist/cli.js

@@ -184,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(),
@@ -211,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) {
@@ -486,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) {
@@ -825,6 +835,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",
@@ -854,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)
   };
 }
 
@@ -1078,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";
@@ -1569,8 +1626,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) {
@@ -1785,6 +1847,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(`
@@ -1794,8 +1875,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" });
@@ -2392,7 +2473,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 {
@@ -2531,13 +2611,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) {
@@ -2552,7 +2633,7 @@ var ClackRenderer = class extends InquirerRenderer {
 
 // src/cli.ts
 import { writeFileSync as writeFileSync6 } from "fs";
-import { resolve as resolve2 } from "path";
+import { resolve as resolve3 } from "path";
 import { fileURLToPath } from "url";
 import { stringify as yamlStringify } from "yaml";
 var plainMode = false;
@@ -2568,7 +2649,7 @@ program.name("grimoire").description("Config-driven CLI wizard framework").versi
 });
 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);
@@ -2594,10 +2675,11 @@ program.command("run").description("Run a wizard from a config file").argument("
       mockAnswers,
       templateAnswers,
       cache: opts.cache,
-      resume: opts.resume
+      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 = {
@@ -2643,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}"`);
@@ -2660,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) {
@@ -2673,7 +2755,7 @@ 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),
       "..",
       "..",
@@ -2812,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) {