@sundaeswap/sprinkles 0.4.0 → 0.6.0

package/src/Sprinkle/prompts.ts

@@ -0,0 +1,551 @@
+/**
+ * Cancellable prompt wrappers with escape key support.
+ * Uses @inquirer/core's createPrompt and useKeypress for proper escape handling.
+ */
+
+import {
+  createPrompt,
+  useState,
+  useKeypress,
+  usePrefix,
+  usePagination,
+  useMemo,
+  makeTheme,
+  isEnterKey,
+  isUpKey,
+  isDownKey,
+  isBackspaceKey,
+  Separator,
+  ValidationError,
+  type Theme,
+} from "@inquirer/core";
+import type { PartialDeep } from "@inquirer/type";
+import colors from "yoctocolors-cjs";
+import figures from "@inquirer/figures";
+
+// Check if key is escape
+const isEscapeKey = (key: { name: string }) => key.name === "escape";
+
+// Theme for select prompt
+const selectTheme = {
+  icon: { cursor: figures.pointer },
+  style: {
+    disabled: (text: string) => colors.dim(`- ${text}`),
+    description: (text: string) => colors.cyan(text),
+    helpTip: colors.dim("(Use arrow keys, Enter to select, Esc to cancel)"),
+  },
+  helpMode: "always" as const,
+};
+
+// Theme for input prompt
+const inputTheme = {
+  style: {
+    helpTip: colors.dim("(Esc to cancel)"),
+  },
+};
+
+interface SelectChoice<T> {
+  name?: string;
+  value: T;
+  description?: string;
+  short?: string;
+  disabled?: boolean | string;
+}
+
+interface SelectConfig<T> {
+  message: string;
+  choices: ReadonlyArray<SelectChoice<T> | Separator | string>;
+  default?: T;
+  pageSize?: number;
+  loop?: boolean;
+  theme?: PartialDeep<Theme<typeof selectTheme>>;
+}
+
+function isSelectable<T>(item: SelectChoice<T> | Separator): item is SelectChoice<T> {
+  return !Separator.isSeparator(item) && !item.disabled;
+}
+
+function normalizeChoices<T>(
+  choices: ReadonlyArray<SelectChoice<T> | Separator | string>,
+): Array<SelectChoice<T> | Separator> {
+  return choices.map((choice) => {
+    if (Separator.isSeparator(choice)) return choice;
+    if (typeof choice === "string") {
+      return {
+        value: choice as unknown as T,
+        name: choice,
+        short: choice,
+        disabled: false,
+      };
+    }
+    const name = choice.name ?? String(choice.value);
+    return {
+      value: choice.value,
+      name,
+      short: choice.short ?? name,
+      disabled: choice.disabled ?? false,
+      description: choice.description,
+    };
+  });
+}
+
+/**
+ * Select prompt with escape key support.
+ * Returns null if user presses Escape.
+ */
+export const selectCancellable = createPrompt<
+  unknown | null,
+  SelectConfig<unknown>
+>((config, done) => {
+  const { loop = true, pageSize = 15 } = config;
+  const theme = makeTheme(selectTheme, config.theme);
+  const [status, setStatus] = useState<"idle" | "done" | "cancelled">("idle");
+  const prefix = usePrefix({ status: status === "cancelled" ? "done" : status, theme });
+
+  const items = useMemo(
+    () => normalizeChoices(config.choices),
+    [config.choices],
+  );
+
+  const bounds = useMemo(() => {
+    const first = items.findIndex(isSelectable);
+    // Find last selectable item (compatible with es2022)
+    let last = -1;
+    for (let i = items.length - 1; i >= 0; i--) {
+      if (isSelectable(items[i]!)) {
+        last = i;
+        break;
+      }
+    }
+    if (first === -1) {
+      throw new ValidationError(
+        "[select prompt] No selectable choices. All choices are disabled.",
+      );
+    }
+    return { first, last };
+  }, [items]);
+
+  const defaultItemIndex = useMemo(() => {
+    if (!("default" in config)) return -1;
+    return items.findIndex(
+      (item) => isSelectable(item) && item.value === config.default,
+    );
+  }, [config.default, items]);
+
+  const [active, setActive] = useState(
+    defaultItemIndex === -1 ? bounds.first : defaultItemIndex,
+  );
+
+  const selectedChoice = items[active] as SelectChoice<unknown>;
+
+  useKeypress((key, rl) => {
+    if (isEscapeKey(key)) {
+      setStatus("cancelled");
+      done(null);
+    } else if (isEnterKey(key)) {
+      setStatus("done");
+      done(selectedChoice.value);
+    } else if (isUpKey(key)) {
+      rl.clearLine(0);
+      if (active === bounds.first && loop) {
+        setActive(bounds.last);
+      } else {
+        let newActive = active - 1;
+        while (newActive >= bounds.first && !isSelectable(items[newActive]!)) {
+          newActive--;
+        }
+        if (newActive >= bounds.first) setActive(newActive);
+      }
+    } else if (isDownKey(key)) {
+      rl.clearLine(0);
+      if (active === bounds.last && loop) {
+        setActive(bounds.first);
+      } else {
+        let newActive = active + 1;
+        while (newActive <= bounds.last && !isSelectable(items[newActive]!)) {
+          newActive++;
+        }
+        if (newActive <= bounds.last) setActive(newActive);
+      }
+    }
+  });
+
+  const page = usePagination({
+    items,
+    active,
+    renderItem: ({ item, isActive }) => {
+      if (Separator.isSeparator(item)) {
+        return ` ${item.separator}`;
+      }
+      const line = item.name;
+      if (item.disabled) {
+        const disabledLabel =
+          typeof item.disabled === "string" ? item.disabled : "(disabled)";
+        return colors.dim(`- ${line} ${disabledLabel}`);
+      }
+      const cursor = isActive ? figures.pointer : " ";
+      const color = isActive ? colors.cyan : (x: string) => x;
+      return color(`${cursor} ${line}`);
+    },
+    pageSize,
+    loop,
+  });
+
+  if (status === "cancelled") {
+    return `${prefix} ${config.message} ${colors.dim("(cancelled)")}`;
+  }
+
+  if (status === "done") {
+    return `${prefix} ${config.message} ${colors.cyan(selectedChoice?.short ?? selectedChoice?.name ?? "")}`;
+  }
+
+  const helpTip = colors.dim("(Use arrow keys, Enter to select, Esc to cancel)");
+  return `${prefix} ${config.message} ${helpTip}\n${page}`;
+});
+
+/**
+ * Clears N lines above the cursor.
+ * Used after prompts to clean up menu output.
+ */
+export function clearLines(count: number): void {
+  // Move up and clear each line
+  process.stdout.write("\x1b[1A\x1b[2K".repeat(count));
+}
+
+/**
+ * Select prompt that clears its output after completion.
+ * Returns the selected value or null if cancelled.
+ */
+export async function selectWithClear<T>(
+  config: SelectConfig<T>,
+): Promise<T | null> {
+  const result = await selectCancellable(config as SelectConfig<unknown>);
+
+  // Clear the "done" line that inquirer left behind
+  // Move up one line, clear it, move cursor to start
+  process.stdout.write("\x1b[1A\x1b[2K\x1b[G");
+
+  return result as T | null;
+}
+
+/**
+ * Input prompt that clears its output after completion.
+ * Returns the input value or null if cancelled.
+ */
+export async function inputWithClear(
+  config: InputConfig,
+): Promise<string | null> {
+  const result = await inputCancellable(config);
+
+  // Clear the "done" line
+  process.stdout.write("\x1b[1A\x1b[2K\x1b[G");
+
+  return result;
+}
+
+/**
+ * Password prompt that clears its output after completion.
+ * Returns the password or null if cancelled.
+ */
+export async function passwordWithClear(
+  config: PasswordConfig,
+): Promise<string | null> {
+  const result = await passwordCancellable(config);
+
+  // Clear the "done" line
+  process.stdout.write("\x1b[1A\x1b[2K\x1b[G");
+
+  return result;
+}
+
+/**
+ * Confirm prompt that clears its output after completion.
+ * Returns true/false or null if cancelled.
+ */
+export async function confirmWithClear(
+  config: ConfirmConfig,
+): Promise<boolean | null> {
+  const result = await confirmCancellable(config);
+
+  // Clear the "done" line
+  process.stdout.write("\x1b[1A\x1b[2K\x1b[G");
+
+  return result;
+}
+
+interface InputConfig {
+  message: string;
+  default?: string;
+  transformer?: (value: string, options: { isFinal: boolean }) => string;
+  validate?: (value: string) => boolean | string | Promise<boolean | string>;
+}
+
+/**
+ * Input prompt with escape key support.
+ * Returns null if user presses Escape.
+ */
+export const inputCancellable = createPrompt<string | null, InputConfig>(
+  (config, done) => {
+    const [status, setStatus] = useState<"idle" | "done" | "cancelled">("idle");
+    const [value, setValue] = useState(config.default ?? "");
+    const [touched, setTouched] = useState(false);
+    const [error, setError] = useState<string | null>(null);
+    const theme = makeTheme(inputTheme);
+    const prefix = usePrefix({ status: status === "cancelled" ? "done" : status, theme });
+
+    useKeypress(async (key, rl) => {
+      if (isEscapeKey(key)) {
+        setStatus("cancelled");
+        done(null);
+      } else if (isEnterKey(key)) {
+        // If user has edited, use their value (even if empty); otherwise use default
+        const answer = touched ? value : (config.default ?? "");
+        if (config.validate) {
+          const result = await config.validate(answer);
+          if (result !== true) {
+            setError(typeof result === "string" ? result : "Invalid input");
+            return;
+          }
+        }
+        setStatus("done");
+        done(answer);
+      } else if (isBackspaceKey(key)) {
+        // Sync with readline's buffer after backspace
+        setValue(rl.line);
+        setTouched(true);
+        setError(null);
+      } else if (key.name !== "tab" && !key.ctrl && !(key as any).meta) {
+        // Sync state with readline's current line buffer
+        setValue(rl.line);
+        setTouched(true);
+        setError(null);
+      }
+    });
+
+    const displayValue = config.transformer
+      ? config.transformer(value, { isFinal: status === "done" })
+      : value;
+
+    if (status === "cancelled") {
+      return `${prefix} ${config.message} ${colors.dim("(cancelled)")}`;
+    }
+
+    if (status === "done") {
+      return `${prefix} ${config.message} ${colors.cyan(displayValue)}`;
+    }
+
+    const helpTip = colors.dim("(Esc to cancel)");
+    const errorMsg = error ? colors.red(`\n> ${error}`) : "";
+    return `${prefix} ${config.message} ${helpTip} ${displayValue}${errorMsg}`;
+  },
+);
+
+interface PasswordConfig {
+  message: string;
+  mask?: string;
+  validate?: (value: string) => boolean | string | Promise<boolean | string>;
+}
+
+/**
+ * Password prompt with escape key support.
+ * Returns null if user presses Escape.
+ */
+export const passwordCancellable = createPrompt<string | null, PasswordConfig>(
+  (config, done) => {
+    const [status, setStatus] = useState<"idle" | "done" | "cancelled">("idle");
+    const [value, setValue] = useState("");
+    const [error, setError] = useState<string | null>(null);
+    const theme = makeTheme(inputTheme);
+    const prefix = usePrefix({ status: status === "cancelled" ? "done" : status, theme });
+    const mask = config.mask ?? "*";
+
+    useKeypress(async (key, rl) => {
+      if (isEscapeKey(key)) {
+        setStatus("cancelled");
+        done(null);
+      } else if (isEnterKey(key)) {
+        if (config.validate) {
+          const result = await config.validate(value);
+          if (result !== true) {
+            setError(typeof result === "string" ? result : "Invalid input");
+            return;
+          }
+        }
+        setStatus("done");
+        done(value);
+      } else if (isBackspaceKey(key)) {
+        setValue(value.slice(0, -1));
+        setError(null);
+      } else if (key.name !== "tab" && !key.ctrl && !(key as any).meta) {
+        // Use key.sequence for single character to avoid rl.line buffer issues
+        const char = (key as any).sequence ?? "";
+        if (char) {
+          rl.clearLine(0);
+          setValue(value + char);
+          setError(null);
+        }
+      }
+    });
+
+    const masked = mask.repeat(value.length);
+
+    if (status === "cancelled") {
+      return `${prefix} ${config.message} ${colors.dim("(cancelled)")}`;
+    }
+
+    if (status === "done") {
+      return `${prefix} ${config.message} ${colors.dim(masked)}`;
+    }
+
+    const helpTip = colors.dim("(Esc to cancel)");
+    const errorMsg = error ? colors.red(`\n> ${error}`) : "";
+    return `${prefix} ${config.message} ${helpTip} ${masked}${errorMsg}`;
+  },
+);
+
+interface ConfirmConfig {
+  message: string;
+  default?: boolean;
+}
+
+/**
+ * Confirm prompt with escape key support.
+ * Returns null if user presses Escape.
+ */
+export const confirmCancellable = createPrompt<boolean | null, ConfirmConfig>(
+  (config, done) => {
+    const [status, setStatus] = useState<"idle" | "done" | "cancelled">("idle");
+    // Track value as undefined when no default, requiring explicit y/n
+    const [value, setValue] = useState<boolean | undefined>(config.default);
+    const theme = makeTheme(inputTheme);
+    const prefix = usePrefix({ status: status === "cancelled" ? "done" : status, theme });
+
+    useKeypress((key) => {
+      if (isEscapeKey(key)) {
+        setStatus("cancelled");
+        done(null);
+      } else if (isEnterKey(key)) {
+        // Only accept Enter if a value has been chosen (explicit or default)
+        if (value !== undefined) {
+          setStatus("done");
+          done(value);
+        }
+      } else if (key.name === "y" || key.name === "Y") {
+        setValue(true);
+      } else if (key.name === "n" || key.name === "N") {
+        setValue(false);
+      }
+    });
+
+    const hint = config.default === true ? "(Y/n)" : config.default === false ? "(y/N)" : "(y/n)";
+    const displayValue = value === true ? "Yes" : value === false ? "No" : "";
+
+    if (status === "cancelled") {
+      return `${prefix} ${config.message} ${colors.dim("(cancelled)")}`;
+    }
+
+    if (status === "done") {
+      return `${prefix} ${config.message} ${colors.cyan(displayValue)}`;
+    }
+
+    const helpTip = colors.dim("(Esc to cancel)");
+    return `${prefix} ${config.message} ${helpTip} ${hint} ${displayValue}`;
+  },
+);
+
+/**
+ * Type-safe wrapper for selectCancellable.
+ * Returns the selected value with proper typing, or null if cancelled.
+ */
+export async function select<T>(config: SelectConfig<T>): Promise<T | null> {
+  return selectCancellable(config as SelectConfig<unknown>) as Promise<T | null>;
+}
+
+interface SearchConfig<T> {
+  message: string;
+  source: (
+    term: string | undefined,
+  ) => Promise<{ name: string; value: T }[]> | { name: string; value: T }[];
+}
+
+/**
+ * Search prompt with escape key support.
+ * Returns null if user presses Escape.
+ *
+ * Note: This wraps @inquirer/search which has built-in escape handling,
+ * but we provide a consistent API with other cancellable prompts.
+ */
+export const searchCancellable = createPrompt<unknown | null, SearchConfig<unknown>>(
+  (config, done) => {
+    const [status, setStatus] = useState<"idle" | "done" | "cancelled">("idle");
+    const [searchTerm, setSearchTerm] = useState("");
+    const [results, setResults] = useState<{ name: string; value: unknown }[]>([]);
+    const [active, setActive] = useState(0);
+    const [loading, setLoading] = useState(false);
+    const theme = makeTheme(selectTheme);
+    const prefix = usePrefix({ status: status === "cancelled" ? "done" : status, theme });
+
+    // Fetch results when search term changes
+    useMemo(async () => {
+      setLoading(true);
+      try {
+        const items = await config.source(searchTerm || undefined);
+        setResults(items);
+        setActive(0);
+      } finally {
+        setLoading(false);
+      }
+    }, [searchTerm]);
+
+    useKeypress((key, rl) => {
+      if (isEscapeKey(key)) {
+        setStatus("cancelled");
+        done(null);
+      } else if (isEnterKey(key) && results.length > 0) {
+        setStatus("done");
+        done(results[active]?.value ?? null);
+      } else if (isUpKey(key) && results.length > 0) {
+        rl.clearLine(0);
+        setActive(active > 0 ? active - 1 : results.length - 1);
+      } else if (isDownKey(key) && results.length > 0) {
+        rl.clearLine(0);
+        setActive(active < results.length - 1 ? active + 1 : 0);
+      } else if (isBackspaceKey(key)) {
+        setSearchTerm(rl.line);
+      } else if (key.name !== "tab" && !key.ctrl && !(key as any).meta) {
+        setSearchTerm(rl.line);
+      }
+    });
+
+    if (status === "cancelled") {
+      return `${prefix} ${config.message} ${colors.dim("(cancelled)")}`;
+    }
+
+    if (status === "done") {
+      const selected = results[active];
+      return `${prefix} ${config.message} ${colors.cyan(selected?.name ?? "")}`;
+    }
+
+    const helpTip = colors.dim("(Type to search, Esc to cancel)");
+    const searchLine = `${prefix} ${config.message} ${helpTip} ${searchTerm}`;
+
+    if (loading) {
+      return `${searchLine}\n${colors.dim("  Searching...")}`;
+    }
+
+    if (results.length === 0) {
+      return `${searchLine}\n${colors.dim("  No results")}`;
+    }
+
+    const resultLines = results
+      .slice(0, 7)
+      .map((item, i) => {
+        const cursor = i === active ? figures.pointer : " ";
+        const color = i === active ? colors.cyan : (x: string) => x;
+        return color(`${cursor} ${item.name}`);
+      })
+      .join("\n");
+
+    return `${searchLine}\n${resultLines}`;
+  },
+);

package/src/Sprinkle/schemas.ts

@@ -0,0 +1,111 @@
+import { Type } from "@sinclair/typebox";
+import type { TExact } from "./types.js";
+
+/**
+ * Network selection schema (mainnet, preview, preprod).
+ */
+export const NetworkSchema = Type.Union([
+  Type.Literal("mainnet"),
+  Type.Literal("preview"),
+  Type.Literal("preprod"),
+]);
+
+/**
+ * Recursive multisig script module for Cardano native scripts.
+ */
+export const MultisigScriptModule = Type.Module({
+  MultisigScript: Type.Union([
+    Type.Object({
+      Signature: Type.Object(
+        {
+          key_hash: Type.String(),
+        },
+        { ctor: 0n },
+      ),
+    }),
+    Type.Object({
+      AllOf: Type.Object(
+        {
+          scripts: Type.Array(Type.Ref("MultisigScript")),
+        },
+        { ctor: 1n },
+      ),
+    }),
+    Type.Object({
+      AnyOf: Type.Object(
+        {
+          scripts: Type.Array(Type.Ref("MultisigScript")),
+        },
+        { ctor: 2n },
+      ),
+    }),
+    Type.Object({
+      AtLeast: Type.Object(
+        {
+          required: Type.BigInt(),
+          scripts: Type.Array(Type.Ref("MultisigScript")),
+        },
+        { ctor: 3n },
+      ),
+    }),
+    Type.Object({
+      Before: Type.Object(
+        {
+          time: Type.BigInt(),
+        },
+        { ctor: 4n },
+      ),
+    }),
+    Type.Object({
+      After: Type.Object(
+        {
+          time: Type.BigInt(),
+        },
+        { ctor: 5n },
+      ),
+    }),
+    Type.Object({
+      Script: Type.Object(
+        {
+          script_hash: Type.String(),
+        },
+        { ctor: 6n },
+      ),
+    }),
+  ]),
+});
+
+export const MultisigScript = MultisigScriptModule.Import("MultisigScript");
+export type TMultisigScript = TExact<typeof MultisigScript>;
+
+/**
+ * Provider settings schema for blockchain data providers.
+ */
+export const ProviderSettingsSchema = Type.Union([
+  Type.Object({
+    type: Type.Literal("blockfrost"),
+    projectId: Type.String({ minLength: 1, title: "Blockfrost Project ID" }),
+  }),
+  Type.Object({
+    type: Type.Literal("maestro"),
+    apiKey: Type.String({ minLength: 1, title: "Maestro API Key" }),
+  }),
+]);
+
+/**
+ * Wallet settings schema for hot and cold wallets.
+ */
+export const WalletSettingsSchema = Type.Union([
+  Type.Object({
+    type: Type.Literal("hot"),
+    privateKey: Type.String({
+      minLength: 1,
+      title: "Hot Wallet Private Key",
+      sensitive: true,
+    }),
+  }),
+  Type.Object({
+    type: Type.Literal("cold"),
+    address: Type.String({ minLength: 1, title: "Cold Wallet Address" }),
+  }),
+]);