@sundaeswap/sprinkles 0.4.0 → 0.6.0

package/src/Sprinkle/menus/array-menu.ts

@@ -0,0 +1,191 @@
+/**
+ * Array menu module for menu-based struct editing.
+ * Shows array items and allows adding/removing/editing.
+ */
+
+import { Separator } from "@inquirer/core";
+import type { TArray, TSchema } from "@sinclair/typebox";
+import { selectWithClear } from "../prompts.js";
+import type { ArrayMenuResult, FieldState } from "../types.js";
+import { UserCancelledError } from "../types.js";
+import { formatValuePreview, formatBreadcrumb } from "../utils/formatting.js";
+import { promptFieldMenu, displayFullValue } from "./field-menu.js";
+import type { FillFunction } from "./object-menu.js";
+
+/**
+ * Options for the array menu prompt.
+ */
+export interface ArrayMenuOptions {
+  /** The array schema */
+  type: TArray;
+  /** Current path for display */
+  path: string[];
+  /** Type definitions for resolving refs */
+  defs: Record<string, TSchema>;
+  /** Existing array values */
+  defaults?: unknown[];
+  /** Function to fill individual items */
+  fillField: FillFunction;
+}
+
+/**
+ * Show a menu-based editor for an array.
+ * Allows adding, removing, and editing items.
+ *
+ * @param options - Array menu options
+ * @returns The edited array or back result
+ */
+export async function promptArray<T>(
+  options: ArrayMenuOptions,
+): Promise<ArrayMenuResult<T>> {
+  const { type, path, defs, defaults = [], fillField } = options;
+
+  const itemType = type.items as TSchema;
+
+  // Initialize items from defaults
+  const items: T[] = [...(defaults as T[])];
+
+  // Main menu loop
+  while (true) {
+    // Build menu choices
+    const choices: Array<{ name: string; value: string } | Separator> = [];
+
+    // Add existing items
+    for (let i = 0; i < items.length; i++) {
+      const preview = formatValuePreview(items[i], 40);
+      choices.push({ name: `[${i}]: ${preview}`, value: `item:${i}` });
+    }
+
+    // Add separator and actions
+    choices.push(new Separator("\u2500\u2500\u2500 Actions \u2500\u2500\u2500"));
+    choices.push({ name: "Add item", value: "add" });
+
+    if (items.length > 0) {
+      choices.push({ name: "Remove item...", value: "remove" });
+    }
+
+    choices.push({ name: `Done (${items.length} item${items.length === 1 ? "" : "s"})`, value: "done" });
+    choices.push({ name: "Back", value: "back" });
+
+    // Show menu
+    const breadcrumb = formatBreadcrumb(path);
+    const message = breadcrumb
+      ? `Edit ${breadcrumb} [${items.length} items]:`
+      : `Edit array [${items.length} items]:`;
+
+    const selection = await selectWithClear({
+      message,
+      choices,
+    });
+
+    // Handle escape - same as done
+    if (selection === null) {
+      return { action: "done", value: items };
+    }
+
+    // Handle done
+    if (selection === "done") {
+      return { action: "done", value: items };
+    }
+
+    // Handle back
+    if (selection === "back") {
+      return { action: "back" };
+    }
+
+    // Handle add
+    if (selection === "add") {
+      try {
+        const newItem = await fillField(
+          itemType,
+          [...path, `[${items.length}]`],
+          defs,
+          undefined,
+        );
+        items.push(newItem as T);
+      } catch (e) {
+        if (e instanceof UserCancelledError) {
+          // Return to menu without adding
+          continue;
+        }
+        throw e;
+      }
+      continue;
+    }
+
+    // Handle remove
+    if (selection === "remove") {
+      const removeChoices = items.map((item, i) => ({
+        name: `[${i}]: ${formatValuePreview(item, 40)}`,
+        value: i,
+      }));
+      removeChoices.push({ name: "Cancel", value: -1 } as { name: string; value: number });
+
+      const indexToRemove = await selectWithClear({
+        message: "Select item to remove:",
+        choices: removeChoices,
+      });
+
+      if (indexToRemove !== null && indexToRemove !== -1) {
+        items.splice(indexToRemove as number, 1);
+      }
+      continue;
+    }
+
+    // Handle item selection
+    if (typeof selection === "string" && selection.startsWith("item:")) {
+      const index = parseInt(selection.slice(5), 10);
+      const currentValue = items[index];
+
+      // Create a FieldState for the item
+      const itemState: FieldState<T> = { status: "set", value: currentValue as T };
+
+      const menuResult = await promptFieldMenu({
+        fieldName: `[${index}]`,
+        fieldType: itemType,
+        state: itemState,
+      });
+
+      switch (menuResult.action) {
+        case "edit": {
+          try {
+            const newValue = await fillField(
+              itemType,
+              [...path, `[${index}]`],
+              defs,
+              currentValue,
+            );
+            items[index] = newValue as T;
+          } catch (e) {
+            if (e instanceof UserCancelledError) {
+              continue;
+            }
+            throw e;
+          }
+          break;
+        }
+
+        case "view": {
+          await displayFullValue(`[${index}]`, currentValue);
+          break;
+        }
+
+        case "clear": {
+          // Remove the item
+          items.splice(index, 1);
+          break;
+        }
+
+        case "setNull": {
+          items[index] = null as T;
+          break;
+        }
+
+        case "reset":
+        case "back":
+          // Do nothing
+          break;
+      }
+    }
+  }
+}

package/src/Sprinkle/menus/field-menu.ts

@@ -0,0 +1,145 @@
+/**
+ * Field menu module for menu-based struct editing.
+ * Handles the sub-menu shown when selecting a field with an existing value.
+ */
+
+import { Separator } from "@inquirer/core";
+import type { TSchema } from "@sinclair/typebox";
+import { selectWithClear } from "../prompts.js";
+import type { FieldMenuResult, FieldState } from "../types.js";
+import { isNullable, hasDefault, getDefault } from "../type-guards.js";
+import { formatValuePreview } from "../utils/formatting.js";
+import { bigIntReplacer } from "../encryption.js";
+
+/**
+ * Options for the field menu prompt.
+ */
+export interface FieldMenuOptions<T> {
+  /** The field name */
+  fieldName: string;
+  /** The field's schema */
+  fieldType: TSchema;
+  /** Current state of the field */
+  state: FieldState<T>;
+}
+
+/**
+ * Show a sub-menu for a field that has a value.
+ * Provides options to edit, view, clear, set null, or reset to default.
+ *
+ * @param options - Field menu options
+ * @returns The user's chosen action
+ */
+export async function promptFieldMenu<T>(
+  options: FieldMenuOptions<T>,
+): Promise<FieldMenuResult<T>> {
+  const { fieldName, fieldType, state } = options;
+
+  const nullable = isNullable(fieldType);
+  const hasDefaultVal = hasDefault(fieldType);
+  const defaultVal = hasDefaultVal ? getDefault(fieldType) : undefined;
+
+  // Build the display of current value
+  const currentDisplay =
+    state.status === "null"
+      ? "null"
+      : state.status === "set"
+        ? formatValuePreview(state.value, 40)
+        : "[not set]";
+
+  const choices: Array<{ name: string; value: string } | Separator> = [];
+
+  // Always offer edit
+  choices.push({ name: "Edit value", value: "edit" });
+
+  // View full value (only if there's a value to view)
+  if (state.status === "set") {
+    choices.push({ name: "View full value", value: "view" });
+  }
+
+  // For nullable fields with value: offer "Set to null" and "Clear value"
+  if (nullable && state.status === "set") {
+    choices.push({ name: "Set to null", value: "setNull" });
+    choices.push({ name: "Clear value (remove from output)", value: "clear" });
+  }
+
+  // For nullable fields that are null: offer "Clear value" to remove null
+  if (nullable && state.status === "null") {
+    choices.push({ name: "Clear value (remove from output)", value: "clear" });
+  }
+
+  // For non-nullable fields with default: offer "Reset to default"
+  if (hasDefaultVal && !nullable && state.status === "set") {
+    const defaultPreview = formatValuePreview(defaultVal, 20);
+    choices.push({
+      name: `Reset to default (${defaultPreview})`,
+      value: "reset",
+    });
+  }
+
+  choices.push(new Separator());
+  choices.push({ name: "Back (keep current)", value: "back" });
+
+  const selection = await selectWithClear({
+    message: `${fieldName}: ${currentDisplay}`,
+    choices,
+  });
+
+  // Escape returns to menu
+  if (selection === null) {
+    return { action: "back" };
+  }
+
+  switch (selection) {
+    case "edit":
+      // Caller will handle the actual editing
+      return { action: "edit" };
+
+    case "view":
+      return { action: "view" };
+
+    case "clear":
+      return { action: "clear" };
+
+    case "setNull":
+      return { action: "setNull" };
+
+    case "reset":
+      return { action: "reset", defaultValue: defaultVal as T };
+
+    case "back":
+    default:
+      return { action: "back" };
+  }
+}
+
+/**
+ * Display the full value of a field.
+ * Shows formatted JSON and waits for user to press Enter.
+ *
+ * @param fieldName - The field name
+ * @param value - The value to display
+ */
+export async function displayFullValue(
+  fieldName: string,
+  value: unknown,
+): Promise<void> {
+  const header = `Current value of ${fieldName}:`;
+  const jsonStr = JSON.stringify(value, bigIntReplacer, 2);
+  const jsonLines = jsonStr.split("\n").length;
+
+  console.log("");
+  console.log(header);
+  console.log(jsonStr);
+  console.log("");
+
+  // Wait for user to press Enter
+  await selectWithClear({
+    message: "Press Enter to continue...",
+    choices: [{ name: "Continue", value: "continue" }],
+  });
+
+  // Clear all the output lines: empty line + header + json lines + empty line
+  const totalLines = 1 + 1 + jsonLines + 1;
+  process.stdout.write("\x1b[1A\x1b[2K".repeat(totalLines) + "\x1b[G");
+}

package/src/Sprinkle/menus/index.ts

@@ -0,0 +1,12 @@
+/**
+ * Menu modules for menu-based struct editing.
+ */
+
+export { promptFieldMenu, displayFullValue } from "./field-menu.js";
+export type { FieldMenuOptions } from "./field-menu.js";
+
+export { promptObject } from "./object-menu.js";
+export type { ObjectMenuOptions, FillFunction } from "./object-menu.js";
+
+export { promptArray } from "./array-menu.js";
+export type { ArrayMenuOptions } from "./array-menu.js";

package/src/Sprinkle/menus/object-menu.ts

@@ -0,0 +1,336 @@
+/**
+ * Object menu module for menu-based struct editing.
+ * Shows all fields of an object and allows non-linear editing.
+ */
+
+import { Separator } from "@inquirer/core";
+import type { TObject, TSchema } from "@sinclair/typebox";
+import { selectWithClear, confirmWithClear, clearLines } from "../prompts.js";
+import colors from "yoctocolors-cjs";
+import type { FieldState, ObjectMenuResult } from "../types.js";
+import { UserCancelledError } from "../types.js";
+import { isOptional, hasDefault, getDefault, isNullable, isLiteral } from "../type-guards.js";
+import {
+  buildFieldLabel,
+  countRequiredFields,
+  allRequiredFieldsFilled,
+  getInitialFieldState,
+  isFieldRequired,
+} from "../utils/field-utils.js";
+import { formatBreadcrumb } from "../utils/formatting.js";
+import { promptFieldMenu, displayFullValue } from "./field-menu.js";
+
+/**
+ * Type for the fill function that handles individual field types.
+ */
+export type FillFunction = <U extends TSchema>(
+  type: U,
+  path: string[],
+  defs: Record<string, TSchema>,
+  def?: unknown,
+) => Promise<unknown>;
+
+/**
+ * Options for the object menu prompt.
+ */
+export interface ObjectMenuOptions {
+  /** The object schema */
+  type: TObject;
+  /** Current path for display */
+  path: string[];
+  /** Type definitions for resolving refs */
+  defs: Record<string, TSchema>;
+  /** Default/existing values */
+  defaults?: Record<string, unknown>;
+  /** Function to fill individual fields */
+  fillField: FillFunction;
+}
+
+/**
+ * Show a menu-based editor for an object.
+ * Allows non-linear editing of fields with Submit/Cancel.
+ *
+ * @param options - Object menu options
+ * @returns The edited object or cancel result
+ */
+export async function promptObject<T extends Record<string, unknown>>(
+  options: ObjectMenuOptions,
+): Promise<ObjectMenuResult<T>> {
+  const { type, path, defs, defaults = {}, fillField } = options;
+
+  const fields = type.properties as Record<string, TSchema>;
+  const fieldNames = Object.keys(fields);
+
+  // Edge case: empty struct
+  if (fieldNames.length === 0) {
+    return { action: "submit", value: {} as T };
+  }
+
+  // Edge case: single required field with no optionals - skip menu
+  const requiredFields = fieldNames.filter((name) =>
+    isFieldRequired(fields[name]!),
+  );
+  const optionalFields = fieldNames.filter(
+    (name) => !isFieldRequired(fields[name]!),
+  );
+
+  if (requiredFields.length === 1 && optionalFields.length === 0) {
+    const fieldName = requiredFields[0]!;
+    const fieldType = fields[fieldName]!;
+    try {
+      const value = await fillField(
+        fieldType,
+        [...path, fieldName],
+        defs,
+        defaults[fieldName],
+      );
+      return {
+        action: "submit",
+        value: { [fieldName]: value } as T,
+      };
+    } catch (e) {
+      if (e instanceof UserCancelledError) {
+        return { action: "cancel" };
+      }
+      throw e;
+    }
+  }
+
+  // Initialize state for all fields
+  const state = new Map<string, FieldState>();
+  for (const fieldName of fieldNames) {
+    const fieldType = fields[fieldName]!;
+    // Auto-fill Literal fields with their const value
+    if (isLiteral(fieldType)) {
+      state.set(fieldName, { status: "set", value: fieldType.const });
+    } else {
+      state.set(fieldName, getInitialFieldState(fieldType, defaults[fieldName]));
+    }
+  }
+
+  // Main menu loop
+  while (true) {
+    const { total, filled } = countRequiredFields(type, state);
+    const canSubmit = allRequiredFieldsFilled(type, state);
+
+    // Build menu choices
+    const choices: Array<{ name: string; value: string; disabled?: boolean | string } | Separator> = [];
+
+    // Add field items
+    for (const fieldName of fieldNames) {
+      const fieldType = fields[fieldName]!;
+      const fieldState = state.get(fieldName)!;
+      const label = buildFieldLabel(fieldName, fieldType, fieldState);
+      choices.push({ name: label, value: `field:${fieldName}` });
+    }
+
+    // Add separator and actions
+    choices.push(new Separator("\u2500\u2500\u2500 Actions \u2500\u2500\u2500"));
+
+    // Submit button
+    if (canSubmit) {
+      choices.push({ name: "Submit", value: "submit" });
+    } else {
+      choices.push({
+        name: `Submit (${filled} of ${total} required complete)`,
+        value: "submit",
+        disabled: true,
+      });
+    }
+
+    choices.push({ name: "Cancel", value: "cancel" });
+
+    // Show breadcrumb header if we're in a nested path
+    const breadcrumb = formatBreadcrumb(path);
+    if (breadcrumb) {
+      console.log(colors.dim(`📍 ${breadcrumb}`));
+    }
+
+    // Show menu
+    const selection = await selectWithClear({
+      message: "Edit:",
+      choices,
+    });
+
+    // Clear the breadcrumb line too if we printed one
+    if (breadcrumb) {
+      clearLines(1);
+    }
+
+    // Handle escape
+    if (selection === null) {
+      // Check if any values have been set
+      const hasValues = Array.from(state.values()).some(
+        (s) => s.status === "set" || s.status === "null",
+      );
+
+      if (hasValues) {
+        const confirmCancel = await confirmWithClear({
+          message: "Discard changes?",
+          default: false,
+        });
+        if (confirmCancel === null || confirmCancel === false) {
+          continue; // Return to menu
+        }
+      }
+      return { action: "cancel" };
+    }
+
+    // Handle submit
+    if (selection === "submit") {
+      if (!canSubmit) {
+        continue; // Shouldn't happen due to disabled, but be safe
+      }
+      const result = buildResultObject(fields, state, defs);
+      return { action: "submit", value: result as T };
+    }
+
+    // Handle cancel
+    if (selection === "cancel") {
+      const hasValues = Array.from(state.values()).some(
+        (s) => s.status === "set" || s.status === "null",
+      );
+
+      if (hasValues) {
+        const confirmCancel = await confirmWithClear({
+          message: "Discard changes?",
+          default: false,
+        });
+        if (confirmCancel === null || confirmCancel === false) {
+          continue;
+        }
+      }
+      return { action: "cancel" };
+    }
+
+    // Handle field selection
+    if (typeof selection === "string" && selection.startsWith("field:")) {
+      const fieldName = selection.slice(6);
+      const fieldType = fields[fieldName]!;
+      const fieldState = state.get(fieldName)!;
+
+      // If field has a value, show field sub-menu
+      if (fieldState.status === "set" || fieldState.status === "null") {
+        const menuResult = await promptFieldMenu({
+          fieldName,
+          fieldType,
+          state: fieldState,
+        });
+
+        switch (menuResult.action) {
+          case "edit": {
+            // Edit the field
+            try {
+              const newValue = await fillField(
+                fieldType,
+                [...path, fieldName],
+                defs,
+                fieldState.status === "set" ? fieldState.value : undefined,
+              );
+              state.set(fieldName, { status: "set", value: newValue });
+            } catch (e) {
+              if (e instanceof UserCancelledError) {
+                // Return to menu without changing
+                continue;
+              }
+              throw e;
+            }
+            break;
+          }
+
+          case "view": {
+            if (fieldState.status === "set") {
+              await displayFullValue(fieldName, fieldState.value);
+            }
+            break;
+          }
+
+          case "clear": {
+            state.set(fieldName, { status: "unset" });
+            break;
+          }
+
+          case "setNull": {
+            state.set(fieldName, { status: "null" });
+            break;
+          }
+
+          case "reset": {
+            // Reset to default value - show as unset, will use default on submit
+            state.set(fieldName, { status: "unset" });
+            break;
+          }
+
+          case "back":
+            // Do nothing, return to main menu
+            break;
+        }
+      } else {
+        // Field is unset - directly prompt for value
+        try {
+          const newValue = await fillField(
+            fieldType,
+            [...path, fieldName],
+            defs,
+            defaults[fieldName],
+          );
+          // If user skipped an optional field (returned undefined), leave as unset
+          if (newValue === undefined) {
+            // Don't change state - field remains unset
+          } else {
+            state.set(fieldName, { status: "set", value: newValue });
+          }
+        } catch (e) {
+          if (e instanceof UserCancelledError) {
+            // Return to menu without changing
+            continue;
+          }
+          throw e;
+        }
+      }
+    }
+  }
+}
+
+/**
+ * Build the result object from the state map.
+ * Applies defaults for unset fields with defaults.
+ */
+function buildResultObject(
+  fields: Record<string, TSchema>,
+  state: Map<string, FieldState>,
+  _defs: Record<string, TSchema>,
+): Record<string, unknown> {
+  const result: Record<string, unknown> = {};
+
+  for (const [fieldName, fieldType] of Object.entries(fields)) {
+    const fieldState = state.get(fieldName);
+
+    if (!fieldState || fieldState.status === "unset") {
+      // If optional, skip (undefined)
+      if (isOptional(fieldType)) {
+        continue;
+      }
+
+      // If field has a default, use it
+      if (hasDefault(fieldType)) {
+        result[fieldName] = getDefault(fieldType);
+        continue;
+      }
+
+      // No value, no default: omit from output
+      continue;
+    }
+
+    if (fieldState.status === "null") {
+      result[fieldName] = null;
+      continue;
+    }
+
+    if (fieldState.status === "set") {
+      result[fieldName] = fieldState.value;
+    }
+  }
+
+  return result;
+}