@sundaeswap/sprinkles 0.5.0 → 0.6.0

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;
+}

package/src/Sprinkle/prompts.ts

@@ -97,7 +97,7 @@ export const selectCancellable = createPrompt<
   unknown | null,
   SelectConfig<unknown>
 >((config, done) => {
-  const { loop = true, pageSize = 7 } = config;
+  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 });
@@ -203,6 +203,76 @@ export const selectCancellable = createPrompt<
   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;

package/src/Sprinkle/type-guards.ts

@@ -7,6 +7,7 @@ import {
   Kind,
   type TBigInt,
   type TLiteral,
+  type TNull,
   type TObject,
   type TSchema,
   type TString,
@@ -17,6 +18,7 @@ import {
   type TRef,
   type TImport,
   type TOptional,
+  type Static,
   OptionalKind,
 } from "@sinclair/typebox";
 
@@ -49,3 +51,43 @@ export const isUnion = (t: TSchema): t is TUnion => t[Kind] === "Union";
  */
 export const isSensitive = (t: TSchema): boolean =>
   isString(t) && t.sensitive === true;
+
+/**
+ * Check if a schema is a Null type.
+ */
+export const isNull = (t: TSchema): t is TNull => t[Kind] === "Null";
+
+/**
+ * Check if a schema allows null values.
+ * Returns true for TNull or unions containing TNull.
+ */
+export const isNullable = (t: TSchema): boolean => {
+  if (isNull(t)) return true;
+  if (isUnion(t)) return t.anyOf.some((member) => isNull(member));
+  return false;
+};
+
+/**
+ * Unwrap a nullable type to get the non-null inner type.
+ * For unions with Null, returns the union without the Null member.
+ * For single non-null member unions, returns just that type.
+ */
+export const unwrapNullable = (t: TSchema): TSchema => {
+  if (isUnion(t)) {
+    const nonNull = t.anyOf.filter((member) => !isNull(member));
+    if (nonNull.length === 1) return nonNull[0]!;
+    return { ...t, anyOf: nonNull } as TSchema;
+  }
+  return t;
+};
+
+/**
+ * Check if a schema has a default value defined.
+ */
+export const hasDefault = (t: TSchema): boolean => "default" in t;
+
+/**
+ * Get the default value from a schema, if defined.
+ */
+export const getDefault = <T extends TSchema>(t: T): Static<T> | undefined =>
+  t.default as Static<T> | undefined;

package/src/Sprinkle/types.ts

@@ -71,3 +71,46 @@ export class UserCancelledError extends Error {
     this.name = "UserCancelledError";
   }
 }
+
+// --- Menu-based FillInStruct types ---
+
+/**
+ * State tracking for a single field during menu-based editing.
+ */
+export type FieldState<T = unknown> =
+  | { status: "unset" }
+  | { status: "set"; value: T }
+  | { status: "null" }; // explicitly set to null
+
+/**
+ * Result of counting required fields in a schema.
+ */
+export interface RequiredFieldCount {
+  total: number;
+  filled: number;
+}
+
+/**
+ * Result from field menu interaction.
+ */
+export type FieldMenuResult<T = unknown> =
+  | { action: "edit" }
+  | { action: "view" }
+  | { action: "clear" }
+  | { action: "setNull" }
+  | { action: "reset"; defaultValue: T }
+  | { action: "back" };
+
+/**
+ * Result from object menu interaction.
+ */
+export type ObjectMenuResult<T = unknown> =
+  | { action: "submit"; value: T }
+  | { action: "cancel" };
+
+/**
+ * Result from array menu interaction.
+ */
+export type ArrayMenuResult<T = unknown> =
+  | { action: "done"; value: T[] }
+  | { action: "back" };