@portosaur/wizard 0.1.0

package/README.md

@@ -0,0 +1,66 @@
+# @portosaur/wizard
+
+A general-purpose interactive CLI prompt library designed for managing complex, multi-step workflows. Built on top of `@clack/prompts`. It adds many additional features like back-navigation, history persistence, and dynamic branching.
+
+## 🧩 Features
+
+- **🔙 Back-Navigation** — Return to previous steps using the **Escape** key without terminal artifacts.
+- **🔄 History Replay** — Maintains session context by redrawing previous responses at the top of the terminal.
+- **🛡️ Signal Handling** — Robust handling for `Ctrl+C` with clean terminal termination.
+- **🔀 Dynamic Branching** — Skip or modify steps based on previous answers.
+
+## 🚀 Installation
+
+```bash
+npm install @portosaur/wizard
+```
+
+## 📖 Usage
+
+```javascript
+import { runWizard } from "@portosaur/wizard";
+
+const state = await runWizard({
+  intro: "Project Setup",
+  steps: [
+    {
+      id: "name",
+      type: "text",
+      label: "Project Name",
+      message: "Enter your project name",
+      required: true,
+    },
+    {
+      id: "vcs",
+      type: "select",
+      label: "VCS",
+      message: "Choose a provider",
+      options: [
+        { value: "github", label: "GitHub" },
+        { value: "gitlab", label: "GitLab" },
+      ],
+    },
+    {
+      id: "confirm",
+      type: "confirm",
+      label: "Confirm",
+      message: "Are you sure?",
+      backOn: false, // Return to previous step if "No" is selected
+    },
+  ],
+});
+
+console.log(state);
+```
+
+- Output:
+
+```json
+{ "name": "sosf", "vcs": "github", "confirm": true }
+```
+
+## 📖 Documentation
+
+For the full API reference, advanced examples, and detailed guides on dynamic branching, please visit our official documentation site:
+
+👉 **[Wizard Documentation](https://soymadip.github.io/portosaur/dev/wizard)**

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@portosaur/wizard",
+  "version": "0.1.0",
+  "description": "Wizard: Interactive CLI prompt library with back-navigation.",
+  "license": "GPL-3.0-only",
+  "author": "soymadip",
+  "homepage": "https://soymadip.github.io/portosaur",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/soymadip/portosaur"
+  },
+  "keywords": [
+    "cli",
+    "prompt",
+    "wizard",
+    "clack",
+    "workflow",
+    "interactive"
+  ],
+  "files": [
+    "src"
+  ],
+  "type": "module",
+  "types": "./src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "import": "./src/index.mjs",
+      "default": "./src/index.mjs"
+    }
+  },
+  "dependencies": {
+    "@clack/prompts": "^1.2.0",
+    "chalk": "^5.6.2"
+  }
+}

package/src/index.d.ts

@@ -0,0 +1,87 @@
+export * from "@clack/prompts";
+
+export interface WizardStep {
+  /** Unique identifier for the step value in the state object. */
+  id: string;
+
+  /** Interaction pattern for the prompt. */
+  type:
+    | "text"
+    | "password"
+    | "number"
+    | "select"
+    | "multiselect"
+    | "confirm"
+    | "pause";
+
+  /** Short label used in the history display (e.g., "vcs › github"). */
+  label: string;
+
+  /** Main question shown to the user. Can be a string or a function of current state. */
+  prompt: string | ((state: any) => string);
+
+  /** Secondary context shown in parentheses. */
+  hint?: string | ((state: any) => string);
+
+  /** Grayed-out placeholder text inside the input. */
+  placeholder?: string;
+
+  /** Initial value for the prompt or the default if skipped. */
+  initialValue?: any | ((state: any) => any);
+
+  /** Custom validation logic. Return a string to show an error. */
+  validate?: (value: any) => string | undefined | void;
+
+  /** Mutates the answer before it hits the state. */
+  transform?: (value: any, state: any) => any;
+
+  /** If false, the step is skipped and reactive defaults are applied. */
+  runIf?: (state: any) => boolean;
+
+  /** Required for select/multiselect types. */
+  options?: any[] | ((state: any) => any[]);
+
+  /** If true, validation fails on empty input. */
+  required?: boolean;
+
+  /** Minimum value for "number" type. */
+  min?: number;
+
+  /** Maximum value for "number" type. */
+  max?: number;
+
+  /** Visual style for the message (e.g., "warn" for yellow). */
+  level?: "info" | "warn" | "error" | "success";
+
+  /** Custom formatter for the history view. */
+  display?: (value: any, state: any) => string;
+
+  /** Programmatic back-navigation based on the answer. */
+  backOn?: any | ((value: any, state: any) => boolean);
+
+  /** Post-submission hook for side-effects or manual navigation. */
+  onResponse?: (
+    value: any,
+    state: any,
+    tools: { back: () => "back" },
+  ) => void | "back" | Promise<void | "back">;
+}
+
+export interface WizardOptions {
+  /** Heading displayed at the very start. */
+  intro?: string;
+
+  /** Closing behavior. string = message, false = skip, undefined = bare line. */
+  outro?: string | false;
+
+  /** Sequential list of interactive steps. */
+  steps: WizardStep[];
+
+  /** Optional starting values. */
+  initialState?: Record<string, any>;
+}
+
+/**
+ * Runs an interactive, multi-step CLI wizard with back-navigation and state persistence.
+ */
+export function runWizard(options: WizardOptions): Promise<Record<string, any>>;

package/src/index.mjs

@@ -0,0 +1,180 @@
+import * as prmpt from "@clack/prompts";
+import chalk from "chalk";
+import { renderHistory } from "./renderer.mjs";
+import { renderStep, coerceAnswer, buildPromptOpts } from "./prompts.mjs";
+import readline from "readline";
+
+export * from "@clack/prompts";
+import * as prmpt_original from "@clack/prompts";
+
+/**
+ * Custom cancel that adds a connector bar for the tree-style logs
+ */
+export const cancel = (msg) => {
+  process.stdout.write(`${chalk.gray("│")}\n`);
+  prmpt_original.cancel(msg);
+};
+
+/**
+ * Runs an interactive CLI wizard.
+ * Handles navigation (forward/back), state management, and alternate screen buffering.
+ * @param {Object} options - Wizard configuration.
+ * @param {string} [options.intro] - Text to show at the start.
+ * @param {string|false} [options.outro] - Text to show at the end.
+ * @param {Array<Object>} options.steps - List of step definitions.
+ * @param {Object} [options.initialState={}] - Initial state for the wizard.
+ * @returns {Promise<Object>} The final state object.
+ */
+export async function runWizard({ intro, outro, steps, initialState = {} }) {
+  const ENTER_ALT_SCREEN = "\x1b[?1049h";
+  const EXIT_ALT_SCREEN = "\x1b[?1049l";
+  const CLEAR_SCREEN = "\x1b[2J\x1b[H";
+
+  let currentStep = 0;
+  const state = { ...initialState };
+  const maxSteps = steps.length;
+  let isAltScreenActive = false;
+
+  const handleInterrupt = (_char, key) => {
+    if (key?.ctrl && key.name === "c") {
+      if (isAltScreenActive) {
+        process.stdout.write(EXIT_ALT_SCREEN);
+      }
+      process.stdout.write("\x1B[2A\x1B[0J");
+      process.stdout.write(`\n${chalk.gray("│")}\n`);
+      prmpt.cancel("Setup aborted.");
+      process.exit(130);
+    }
+  };
+
+  if (process.stdin.isTTY) {
+    readline.emitKeypressEvents(process.stdin);
+    process.stdin.on("keypress", handleInterrupt);
+
+    if (process.stdout.isTTY) {
+      process.stdout.write(ENTER_ALT_SCREEN + CLEAR_SCREEN);
+      isAltScreenActive = true;
+    }
+  }
+
+  try {
+    const goBack = () => {
+      currentStep--;
+
+      while (
+        currentStep > 0 &&
+        steps[currentStep].runIf &&
+        !steps[currentStep].runIf(state)
+      ) {
+        currentStep--;
+      }
+      renderHistory(steps, currentStep, state, intro);
+    };
+
+    renderHistory(steps, currentStep, state, intro);
+
+    while (currentStep >= 0 && currentStep < maxSteps) {
+      const step = steps[currentStep];
+
+      if (step.runIf && !step.runIf(state)) {
+        if (state[step.id] == null && step.initialValue !== undefined) {
+          const { initialValue } = buildPromptOpts(step, state);
+          state[step.id] = initialValue;
+        }
+        currentStep++;
+        continue;
+      }
+
+      // Note: `onEnter` hooks were removed to avoid automatic side-effects
+      // (e.g. reopening a browser) when a user navigates back to a step.
+
+      // Race the prompt with an Escape watcher: some prompts don't always
+      // surface a cancel sentinel, so we listen for raw Escape and treat it
+      // as a back/cancel. The watcher is only active for TTY sessions.
+      let answer;
+      if (process.stdin.isTTY) {
+        let removeEscListener;
+        const escPromise = new Promise((resolve) => {
+          const escHandler = (_char, key) => {
+            if (
+              key?.name === "escape" ||
+              key?.name === "esc" ||
+              key?.sequence === "\u001b"
+            ) {
+              resolve({ __escape: true });
+            }
+          };
+          process.stdin.on("keypress", escHandler);
+          removeEscListener = () =>
+            process.stdin.removeListener("keypress", escHandler);
+        });
+
+        const renderPromise = renderStep(step, state);
+        answer = await Promise.race([renderPromise, escPromise]);
+        if (removeEscListener) removeEscListener();
+      } else {
+        answer = await renderStep(step, state);
+      }
+
+      // Special case: pause step can return its own escape marker; handle
+      // both that and the generic escape marker here.
+      if (answer && (answer.__pauseEscape || answer.__escape)) {
+        goBack();
+        continue;
+      }
+
+      if (prmpt.isCancel(answer)) {
+        if (currentStep === 0) {
+          process.stdout.write("\x1B[2A\x1B[0J");
+          process.stdout.write(`\n${chalk.gray("│")}\n`);
+          prmpt.cancel("Setup aborted.");
+
+          if (isAltScreenActive) {
+            process.stdout.write(EXIT_ALT_SCREEN);
+          }
+          process.exit(0);
+        }
+        goBack();
+        continue;
+      }
+
+      const shouldGoBack =
+        typeof step.backOn === "function"
+          ? step.backOn(answer, state)
+          : step.backOn !== undefined && answer === step.backOn;
+
+      if (shouldGoBack) {
+        goBack();
+        continue;
+      }
+
+      if (step.onResponse) {
+        const action = step.onResponse(answer, state, { back: () => "back" });
+        if (action === "back") {
+          goBack();
+          continue;
+        }
+      }
+
+      state[step.id] = coerceAnswer(step, answer, state);
+      currentStep++;
+      renderHistory(steps, currentStep, state, intro);
+    }
+  } finally {
+    if (isAltScreenActive) {
+      process.stdout.write(EXIT_ALT_SCREEN);
+    }
+
+    if (process.stdin.isTTY) {
+      process.stdin.removeListener("keypress", handleInterrupt);
+    }
+  }
+
+  if (outro !== false) {
+    typeof outro === "string"
+      ? prmpt.outro(outro)
+      : console.log(chalk.gray("└"));
+  }
+
+  return state;
+}

package/src/prompts.mjs

@@ -0,0 +1,210 @@
+import * as prmpt from "@clack/prompts";
+import chalk from "chalk";
+import readline from "readline";
+
+const levelStyles = {
+  info: chalk.blueBright,
+  warn: chalk.yellowBright,
+  error: chalk.redBright,
+  success: chalk.greenBright,
+};
+
+/**
+ * Builds the options for a Clack prompt based on a wizard step definition.
+ * @param {Object} step - The step definition.
+ * @param {Object} state - The current wizard state.
+ * @returns {Object} An object containing the initial value and Clack options.
+ */
+export function buildPromptOpts(step, state) {
+  const promptText =
+    typeof step.prompt === "function" ? step.prompt(state) : step.prompt;
+  const hint = typeof step.hint === "function" ? step.hint(state) : step.hint;
+
+  const levelStyle = levelStyles[step.level] || ((str) => str);
+  const styledMessage = chalk.bold(levelStyle(promptText));
+
+  const initialValue =
+    typeof step.initialValue === "function"
+      ? step.initialValue(state)
+      : (state[step.id] ?? step.initialValue);
+
+  return {
+    initialValue,
+    opts: {
+      message: `${styledMessage}${hint ? ` ${chalk.gray(`(${hint})`)}` : ""}`,
+      placeholder: step.placeholder ? chalk.gray(step.placeholder) : undefined,
+      initialValue,
+      validate: (val) => {
+        if (step.validate) {
+          return step.validate(val);
+        }
+        if (step.required && (!val || !val.trim())) {
+          return `${step.label || step.id} is required!`;
+        }
+      },
+    },
+  };
+}
+
+/**
+ * Renders a single wizard step.
+ * @param {Object} step - The step definition to render.
+ * @param {Object} state - The current wizard state.
+ * @returns {Promise<any>} The answer from the user.
+ */
+export async function renderStep(step, state) {
+  const { initialValue, opts } = buildPromptOpts(step, state);
+
+  switch (step.type) {
+    case "text":
+      return await prmpt.text(opts);
+
+    case "password":
+      return await prmpt.password(opts);
+
+    case "select":
+      return await prmpt.select({
+        ...opts,
+        options:
+          typeof step.options === "function"
+            ? step.options(state)
+            : step.options,
+      });
+
+    case "multiselect":
+      return await prmpt.multiselect({
+        ...opts,
+        options:
+          typeof step.options === "function"
+            ? step.options(state)
+            : step.options,
+        initialValues: initialValue || [],
+      });
+
+    case "confirm":
+      return await prmpt.confirm(opts);
+
+    case "number": {
+      const raw = await prmpt.text({
+        ...opts,
+        validate: (val) => {
+          if (step.validate) {
+            return step.validate(val);
+          }
+          if (step.required && !val?.trim()) {
+            return `${step.label || step.id} is required!`;
+          }
+          if (val && isNaN(Number(val))) {
+            return "Please enter a valid number.";
+          }
+          if (step.min !== undefined && Number(val) < step.min) {
+            return `Must be at least ${step.min}.`;
+          }
+          if (step.max !== undefined && Number(val) > step.max) {
+            return `Must be at most ${step.max}.`;
+          }
+        },
+      });
+      return raw;
+    }
+
+    case "pause": {
+      const frames = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+      let frameIdx = 0;
+
+      if (!process.stdin.isTTY) {
+        process.stdout.write(
+          `${chalk.gray("│")}\n${chalk.gray("◆")}  ${opts.message}\n`,
+        );
+        return true;
+      }
+
+      process.stdout.write(
+        `${chalk.gray("│")}\n${chalk.gray("◆")}  ${opts.message}\n`,
+      );
+
+      const animate = setInterval(() => {
+        process.stdout.write(
+          `\r${chalk.gray("│")}  ${chalk.cyan(frames[frameIdx++ % frames.length])}  ${chalk.dim("press Enter to continue...")}`,
+        );
+      }, 80);
+
+      await new Promise((resolve) => {
+        let resolved = false;
+        const rl = readline.createInterface({
+          input: process.stdin,
+          output: process.stdout,
+        });
+
+        let onKey;
+        const cleanup = () => {
+          clearInterval(animate);
+          try {
+            rl.close();
+          } catch (e) {}
+          if (onKey) {
+            process.stdin.removeListener("keypress", onKey);
+          }
+        };
+
+        const onDone = () => {
+          if (resolved) {
+            return;
+          }
+          resolved = true;
+          cleanup();
+          process.stdout.write(
+            `\r${chalk.gray("│")}  ${chalk.green("✓")}  ${chalk.dim("done")}\n`,
+          );
+          resolve();
+        };
+
+        onKey = (_char, key) => {
+          if (key?.name === "return" || key?.name === "enter") {
+            onDone();
+          }
+
+          if (
+            key?.name === "escape" ||
+            key?.name === "esc" ||
+            key?.sequence === "\u001b"
+          ) {
+            if (resolved) {
+              return;
+            }
+            resolved = true;
+            cleanup();
+            resolve({ __pauseEscape: true });
+          }
+        };
+
+        rl.once("line", onDone);
+        process.stdin.on("keypress", onKey);
+      });
+
+      return true;
+    }
+
+    default:
+      throw new Error(`Unsupported wizard step type: ${step.type}`);
+  }
+}
+
+/**
+ * Coerces and transforms a user's answer based on the step configuration.
+ * @param {Object} step - The step definition.
+ * @param {any} answer - The raw answer from the prompt.
+ * @param {Object} state - The current wizard state.
+ * @returns {any} The transformed value.
+ */
+export function coerceAnswer(step, answer, state) {
+  let value =
+    step.type === "number" && typeof answer === "string"
+      ? answer === ""
+        ? answer
+        : Number(answer)
+      : answer;
+
+  if (step.transform) value = step.transform(value, state);
+  return value;
+}

package/src/renderer.mjs

@@ -0,0 +1,37 @@
+import * as prmpt from "@clack/prompts";
+import chalk from "chalk";
+
+export function renderHistory(steps, currentStep, state, intro) {
+  if (process.env.NODE_ENV !== "test") {
+    console.log("\n\u200B\n\n\n\n\n\u200B\n\u00A0");
+    process.stdout.write("\x1B[2J\x1B[H");
+  }
+
+  console.log("");
+
+  if (intro) {
+    prmpt.intro(chalk.bgCyan.black(` ${intro} `));
+    console.log(chalk.gray("│"));
+    console.log(chalk.gray("│  [Enter] submit • [Esc] back • [Ctrl+C] exit "));
+  }
+
+  for (let i = 0; i < currentStep; i++) {
+    const step = steps[i];
+    if (step.runIf && !step.runIf(state)) continue;
+    if (step.type === "pause" || step.type === "password") continue;
+
+    if (i === 0) console.log(chalk.gray("│"));
+
+    const value = state[step.id];
+
+    if (value !== undefined) {
+      const displayValue = step.display ? step.display(value, state) : value;
+
+      if (displayValue !== null && displayValue !== "") {
+        console.log(
+          `${chalk.gray("│")}  ${chalk.dim(step.label || step.id)} ${chalk.gray("›")} ${chalk.cyan(displayValue)}`,
+        );
+      }
+    }
+  }
+}