@sundaeswap/sprinkles 0.6.1 → 0.7.0

package/src/Sprinkle/index.ts

@@ -69,7 +69,10 @@ import {
   isImport,
   isArray,
   isBigInt,
+  isBoolean,
+  isInteger,
   isLiteral,
+  isNumber,
   isObject,
   isRef,
   isString,
@@ -88,7 +91,10 @@ export {
   isImport,
   isArray,
   isBigInt,
+  isBoolean,
+  isInteger,
   isLiteral,
+  isNumber,
   isObject,
   isRef,
   isString,
@@ -146,6 +152,47 @@ import {
 import { promptObject, promptArray } from "./menus/index.js";
 import { formatPath } from "./utils/formatting.js";
 
+// Import and re-export action system
+import {
+  ActionRegistry,
+  ActionError,
+  executeAction,
+  detectMode,
+  parseCliArgs,
+  generateActionHelp,
+  camelToKebab,
+  kebabToCamel,
+  coerceValue,
+  parseArgvWithSchema,
+  generateAppHelp,
+  runCli,
+  runMcp,
+  promptAndExecute,
+} from "./actions/index.js";
+import type { AnyAction, IActionContext, IActionResult } from "./actions/index.js";
+export type { IAction, IActionContext, IActionResult, IActionSuccess, IActionFailure, AnyAction } from "./actions/index.js";
+export {
+  ActionRegistry,
+  ActionError,
+  executeAction,
+  detectMode,
+  parseCliArgs,
+  generateActionHelp,
+  camelToKebab,
+  kebabToCamel,
+  coerceValue,
+  parseArgvWithSchema,
+  generateAppHelp,
+  runCli,
+  typeboxToJsonSchema,
+  coerceMcpInput,
+  getMcpSdk,
+  createMcpServer,
+  runMcp,
+  getBuiltinActions,
+  promptAndExecute,
+} from "./actions/index.js";
+
 export interface IMenuAction<S extends TSchema> {
   title: string;
   action: (sprinkle: Sprinkle<S>) => Promise<Sprinkle<S> | void>;
@@ -165,11 +212,13 @@ export class Sprinkle<S extends TSchema> {
   options: ISprinkleOptions;
   profileId: string = "";
   profileMeta: IProfileMeta = { name: "", createdAt: "", updatedAt: "" };
+  actionRegistry: ActionRegistry<S>;
 
   constructor(type: S, storagePath: string, options?: ISprinkleOptions) {
     this.type = type;
     this.storagePath = storagePath;
     this.options = options ?? {};
+    this.actionRegistry = new ActionRegistry<S>();
   }
 
   // --- Current Profile Accessor ---
@@ -771,6 +820,104 @@ export class Sprinkle<S extends TSchema> {
     return maskSensitiveFields(this.settings, this.type);
   }
 
+  // --- Non-interactive profile management (for CLI/MCP actions) ---
+
+  /**
+   * Look up a profile entry by its ID without loading it.
+   * Returns undefined if no profile with the given ID exists.
+   */
+  getProfileById(id: string): IProfileEntry | undefined {
+    return this.scanProfiles().find((p) => p.id === id);
+  }
+
+  /**
+   * Create a new profile file without interactive prompts.
+   * Does NOT switch the active profile.
+   *
+   * @throws ActionError with code DUPLICATE_PROFILE if a profile with the same name already exists.
+   * @returns The created IProfileEntry
+   */
+  async createProfileNonInteractive(
+    name: string,
+    description?: string,
+    initialSettings?: Partial<TExact<S>>,
+  ): Promise<IProfileEntry> {
+    const profiles = this.scanProfiles();
+    const nameLower = name.toLowerCase();
+    const duplicate = profiles.find(
+      (p) => p.meta.name.toLowerCase() === nameLower,
+    );
+    if (duplicate) {
+      throw new ActionError(
+        `A profile named "${name}" already exists.`,
+        "DUPLICATE_PROFILE",
+        { existingId: duplicate.id },
+      );
+    }
+
+    const profilesDir = Sprinkle.profilesDir(this.storagePath);
+    if (!fs.existsSync(profilesDir)) {
+      fs.mkdirSync(profilesDir, { recursive: true });
+    }
+
+    const baseId = Sprinkle.sanitizeProfileId(name);
+    const id = Sprinkle.findAvailableId(profilesDir, baseId);
+    const now = new Date().toISOString();
+    const meta: IProfileMeta = { name, description, createdAt: now, updatedAt: now };
+
+    const profileData = {
+      meta,
+      settings: initialSettings ?? {},
+      defaults: {},
+    };
+
+    fs.writeFileSync(
+      path.join(profilesDir, `${id}.json`),
+      JSON.stringify(profileData, bigIntReplacer, 2),
+      "utf-8",
+    );
+
+    return { id, meta };
+  }
+
+  /**
+   * Delete a profile file by ID.
+   *
+   * @throws ActionError with code PROFILE_NOT_FOUND if no profile with the given ID exists.
+   * @throws ActionError with code CANNOT_DELETE_ONLY_PROFILE if this is the only profile.
+   * @throws ActionError with code CANNOT_DELETE_ACTIVE_PROFILE if this is the currently active profile.
+   */
+  deleteProfileById(id: string): void {
+    const profiles = this.scanProfiles();
+    const profile = profiles.find((p) => p.id === id);
+
+    if (!profile) {
+      throw new ActionError(
+        `Profile "${id}" not found.`,
+        "PROFILE_NOT_FOUND",
+        { id },
+      );
+    }
+
+    if (profiles.length === 1) {
+      throw new ActionError(
+        "Cannot delete the only profile.",
+        "CANNOT_DELETE_ONLY_PROFILE",
+        { id },
+      );
+    }
+
+    if (id === this.profileId) {
+      throw new ActionError(
+        "Cannot delete the active profile. Switch to a different profile first.",
+        "CANNOT_DELETE_ACTIVE_PROFILE",
+        { id },
+      );
+    }
+
+    fs.unlinkSync(Sprinkle.profilePath(this.storagePath, id));
+  }
+
   async TxDialog<P extends Provider, W extends Wallet>(
     blaze: Blaze<P, W>,
     tx: Core.Transaction,
@@ -1376,4 +1523,208 @@ export class Sprinkle<S extends TSchema> {
 
     return def;
   }
+
+  // --- Action System ---
+
+  /**
+   * Register an action on this Sprinkle instance.
+   * Delegates to the internal ActionRegistry with name and schema validation.
+   */
+  registerAction(action: AnyAction<S>): void {
+    this.actionRegistry.register(action);
+  }
+
+  /**
+   * Retrieve a registered action by name.
+   * @returns The action, or undefined if not registered
+   */
+  getAction(name: string): AnyAction<S> | undefined {
+    return this.actionRegistry.get(name);
+  }
+
+  /**
+   * List all registered actions.
+   */
+  listActions(): AnyAction<S>[] {
+    return this.actionRegistry.list();
+  }
+
+  /**
+   * List all registered actions grouped by category.
+   * Uncategorized actions are grouped under "default".
+   */
+  listActionsByCategory(): Map<string, AnyAction<S>[]> {
+    return this.actionRegistry.listByCategory();
+  }
+
+  /**
+   * Execute a registered action by name with raw (unvalidated) input.
+   * Input is validated against the action's inputSchema before execution.
+   *
+   * @throws Error if the action name is not registered
+   */
+  async runAction(
+    name: string,
+    input: unknown,
+  ): Promise<IActionResult<unknown>> {
+    const action = this.actionRegistry.get(name);
+    if (!action) {
+      throw new Error(
+        `Action "${name}" is not registered. Available actions: ${this.actionRegistry.list().map((a) => a.name).join(", ") || "(none)"}`,
+      );
+    }
+
+    const context: IActionContext<S> = {
+      sprinkle: this,
+      settings: this.settings,
+    };
+
+    return executeAction(action, input, context);
+  }
+
+  /**
+   * Non-interactive profile initialization for CLI/MCP modes.
+   * Resolves a profile without any user prompts.
+   *
+   * Resolution order:
+   * 1. If profileName provided, load that profile directly
+   * 2. If exactly one profile exists, auto-select it
+   * 3. If multiple profiles exist and no name given, throw with available names
+   * 4. If no profiles exist, throw instructing user to run in interactive mode
+   */
+  private async initNonInteractive(profileName?: string): Promise<void> {
+    await this.migrateIfNeeded();
+
+    if (profileName) {
+      await this.loadProfile(profileName);
+      return;
+    }
+
+    const profiles = this.scanProfiles();
+
+    if (profiles.length === 0) {
+      throw new Error(
+        "No profiles found. Run in interactive mode to create one.",
+      );
+    }
+
+    if (profiles.length === 1) {
+      await this.loadProfile(profiles[0]!.id);
+      return;
+    }
+
+    // Multiple profiles without a --profile flag
+    const names = profiles.map((p) => `"${p.id}" (${p.meta.name})`).join(", ");
+    throw new Error(
+      `Multiple profiles found. Specify one with --profile <id>. Available profiles: ${names}`,
+    );
+  }
+
+  /**
+   * Static entry point that detects mode and runs accordingly.
+   *
+   * Modes:
+   * - "tui"  -- Interactive TUI menu (requires menu option)
+   * - "cli"  -- CLI action execution (parses argv for action name and args)
+   * - "mcp"  -- MCP protocol mode (not yet implemented)
+   * - "help" -- Print available actions and exit
+   */
+  static async run<S extends TSchema>(opts: {
+    type: S;
+    storagePath: string;
+    menu?: IMenu<S>;
+    actions?: AnyAction<S>[];
+    options?: ISprinkleOptions;
+    argv?: string[];
+  }): Promise<void> {
+    const argv = opts.argv ?? process.argv.slice(2);
+    const mode = detectMode(argv);
+
+    if (mode === "tui") {
+      if (!opts.menu) {
+        throw new Error(
+          "TUI mode requires a menu. Provide a menu option or pass --help to see available actions.",
+        );
+      }
+      const sprinkle = await Sprinkle.New(
+        opts.type,
+        opts.storagePath,
+        opts.options,
+      );
+      // Register any provided actions
+      for (const action of opts.actions ?? []) {
+        sprinkle.registerAction(action);
+      }
+      await sprinkle.showMenu(opts.menu);
+      return;
+    }
+
+    if (mode === "help") {
+      const sprinkle = new Sprinkle(opts.type, opts.storagePath, opts.options);
+      for (const action of opts.actions ?? []) {
+        sprinkle.registerAction(action);
+      }
+      console.log(generateAppHelp(sprinkle.listActions()));
+      return;
+    }
+
+    if (mode === "cli") {
+      const { actionName, args } = parseCliArgs(argv);
+
+      // Extract --profile flag from args if present
+      const profileName =
+        typeof args["profile"] === "string" ? args["profile"] : undefined;
+
+      const sprinkle = new Sprinkle(opts.type, opts.storagePath, opts.options);
+      for (const action of opts.actions ?? []) {
+        sprinkle.registerAction(action);
+      }
+
+      // Handle action-specific --help BEFORE profile initialization
+      // (help should work without a profile)
+      if (args["help"] === true) {
+        const action = sprinkle.getAction(actionName);
+        if (action) {
+          console.log(generateActionHelp(action));
+        } else {
+          console.log(`Unknown action "${actionName}". Run --help to see available actions.`);
+        }
+        return;
+      }
+
+      await sprinkle.initNonInteractive(profileName);
+
+      // Remove internal flags from args before passing to action
+      const actionArgs = { ...args };
+      delete actionArgs["profile"];
+      delete actionArgs["help"];
+
+      // Build context and delegate to runCli for proper error routing
+      const context = {
+        sprinkle,
+        settings: sprinkle.settings,
+      };
+      await runCli(sprinkle, actionName, actionArgs, context);
+      return;
+    }
+
+    if (mode === "mcp") {
+      // Derive a server name from the storage path basename, falling back to a
+      // sensible default.
+      const serverName = path.basename(opts.storagePath) || "sprinkle-mcp";
+
+      const sprinkle = new Sprinkle(opts.type, opts.storagePath, opts.options);
+      for (const action of opts.actions ?? []) {
+        sprinkle.registerAction(action);
+      }
+
+      // Read profile name from environment variable (MCP clients have no
+      // interactive terminal to prompt for profile selection).
+      const profileName = process.env["SPRINKLE_PROFILE"];
+
+      await sprinkle.initNonInteractive(profileName);
+      await runMcp(sprinkle, serverName);
+      return;
+    }
+  }
 }

package/src/Sprinkle/prompts.ts

@@ -61,7 +61,9 @@ interface SelectConfig<T> {
   theme?: PartialDeep<Theme<typeof selectTheme>>;
 }
 
-function isSelectable<T>(item: SelectChoice<T> | Separator): item is SelectChoice<T> {
+function isSelectable<T>(
+  item: SelectChoice<T> | Separator,
+): item is SelectChoice<T> {
   return !Separator.isSeparator(item) && !item.disabled;
 }
 
@@ -100,7 +102,10 @@ export const selectCancellable = createPrompt<
   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 prefix = usePrefix({
+    status: status === "cancelled" ? "done" : status,
+    theme,
+  });
 
   const items = useMemo(
     () => normalizeChoices(config.choices),
@@ -199,7 +204,9 @@ export const selectCancellable = createPrompt<
     return `${prefix} ${config.message} ${colors.cyan(selectedChoice?.short ?? selectedChoice?.name ?? "")}`;
   }
 
-  const helpTip = colors.dim("(Use arrow keys, Enter to select, Esc to cancel)");
+  const helpTip = colors.dim(
+    "(Use arrow keys, Enter to select, Esc to cancel)",
+  );
   return `${prefix} ${config.message} ${helpTip}\n${page}`;
 });
 
@@ -291,7 +298,10 @@ export const inputCancellable = createPrompt<string | null, InputConfig>(
     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 });
+    const prefix = usePrefix({
+      status: status === "cancelled" ? "done" : status,
+      theme,
+    });
 
     useKeypress(async (key, rl) => {
       if (isEscapeKey(key)) {
@@ -356,7 +366,10 @@ export const passwordCancellable = createPrompt<string | null, PasswordConfig>(
     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 prefix = usePrefix({
+      status: status === "cancelled" ? "done" : status,
+      theme,
+    });
     const mask = config.mask ?? "*";
 
     useKeypress(async (key, rl) => {
@@ -418,7 +431,10 @@ export const confirmCancellable = createPrompt<boolean | null, ConfirmConfig>(
     // 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 });
+    const prefix = usePrefix({
+      status: status === "cancelled" ? "done" : status,
+      theme,
+    });
 
     useKeypress((key) => {
       if (isEscapeKey(key)) {
@@ -437,7 +453,12 @@ export const confirmCancellable = createPrompt<boolean | null, ConfirmConfig>(
       }
     });
 
-    const hint = config.default === true ? "(Y/n)" : config.default === false ? "(y/N)" : "(y/n)";
+    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") {
@@ -458,7 +479,9 @@ export const confirmCancellable = createPrompt<boolean | null, ConfirmConfig>(
  * 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>;
+  return selectCancellable(
+    config as SelectConfig<unknown>,
+  ) as Promise<T | null>;
 }
 
 interface SearchConfig<T> {
@@ -475,77 +498,100 @@ interface SearchConfig<T> {
  * 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);
-      }
-    });
+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);
+  // Store selected item when Enter is pressed to avoid stale closure issues
+  const [selectedName, setSelectedName] = useState<string>("");
+  const theme = makeTheme(selectTheme);
+  const prefix = usePrefix({
+    status: status === "cancelled" ? "done" : status,
+    theme,
+  });
 
-    if (status === "cancelled") {
-      return `${prefix} ${config.message} ${colors.dim("(cancelled)")}`;
+  // Fetch results when search term changes
+  useMemo(async () => {
+    setLoading(true);
+    try {
+      const items = await config.source(searchTerm || undefined);
+      setResults(items);
+      // Don't reset active here - it's reset in keypress handler when user types
+    } finally {
+      setLoading(false);
     }
+  }, [searchTerm]);
 
-    if (status === "done") {
+  useKeypress((key, rl) => {
+    if (isEscapeKey(key)) {
+      setStatus("cancelled");
+      done(null);
+    } else if (isEnterKey(key) && results.length > 0) {
       const selected = results[active];
-      return `${prefix} ${config.message} ${colors.cyan(selected?.name ?? "")}`;
+      setSelectedName(selected?.name ?? "");
+      setStatus("done");
+      done(selected?.value ?? null);
+    } else if (isUpKey(key) && results.length > 0) {
+      setActive(active > 0 ? active - 1 : results.length - 1);
+    } else if (isDownKey(key) && results.length > 0) {
+      setActive(active < results.length - 1 ? active + 1 : 0);
+    } else if (isBackspaceKey(key)) {
+      // Reset active when user modifies search term
+      setActive(0);
+      setSearchTerm(rl.line);
+    } else if (
+      key.name !== "tab" &&
+      key.name !== "return" &&
+      key.name !== "enter" &&
+      key.name !== "up" &&
+      key.name !== "down" &&
+      key.name !== "left" &&
+      key.name !== "right" &&
+      key.name !== "escape" &&
+      key.name !== "backspace" &&
+      !key.ctrl &&
+      !(key as any).meta
+    ) {
+      // Reset active when user types new characters (not navigation/action keys)
+      setActive(0);
+      setSearchTerm(rl.line);
     }
+  });
+
+  if (status === "cancelled") {
+    return `${prefix} ${config.message} ${colors.dim("(cancelled)")}`;
+  }
 
-    const helpTip = colors.dim("(Type to search, Esc to cancel)");
-    const searchLine = `${prefix} ${config.message} ${helpTip} ${searchTerm}`;
+  if (status === "done") {
+    return `${prefix} ${config.message} ${colors.cyan(selectedName)}`;
+  }
 
-    if (loading) {
-      return `${searchLine}\n${colors.dim("  Searching...")}`;
-    }
+  const helpTip = colors.dim("(Type to search, Esc to cancel)");
+  const searchLine = `${prefix} ${config.message} ${helpTip} ${searchTerm}`;
 
-    if (results.length === 0) {
-      return `${searchLine}\n${colors.dim("  No results")}`;
-    }
+  if (loading) {
+    return `${searchLine}\n${colors.dim("  Searching...")}`;
+  }
 
-    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");
+  if (results.length === 0) {
+    return `${searchLine}\n${colors.dim("  No results")}`;
+  }
 
-    return `${searchLine}\n${resultLines}`;
-  },
-);
+  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/type-guards.ts

@@ -6,8 +6,11 @@
 import {
   Kind,
   type TBigInt,
+  type TBoolean,
+  type TInteger,
   type TLiteral,
   type TNull,
+  type TNumber,
   type TObject,
   type TSchema,
   type TString,
@@ -31,6 +34,12 @@ export const isArray = (t: TSchema): t is TArray => t[Kind] === "Array";
 
 export const isBigInt = (t: TSchema): t is TBigInt => t[Kind] === "BigInt";
 
+export const isBoolean = (t: TSchema): t is TBoolean => t[Kind] === "Boolean";
+
+export const isInteger = (t: TSchema): t is TInteger => t[Kind] === "Integer";
+
+export const isNumber = (t: TSchema): t is TNumber => t[Kind] === "Number";
+
 export const isLiteral = (t: TSchema): t is TLiteral => t[Kind] === "Literal";
 
 export const isObject = (t: TSchema): t is TObject => t[Kind] === "Object";