@sundaeswap/sprinkles 0.6.1 → 0.8.0

package/src/Sprinkle/index.ts

@@ -58,10 +58,14 @@ export {
   NetworkSchema,
   MultisigScriptModule,
   MultisigScript,
+  NativeScriptInputSchema,
+  NativeScriptsParam,
   ProviderSettingsSchema,
   WalletSettingsSchema,
 } from "./schemas.js";
 export type { TMultisigScript } from "./schemas.js";
+import type { TMultisigScript } from "./schemas.js";
+import { MultisigScript as MultisigScriptSchema } from "./schemas.js";
 
 // Import and re-export type guards
 import {
@@ -69,7 +73,10 @@ import {
   isImport,
   isArray,
   isBigInt,
+  isBoolean,
+  isInteger,
   isLiteral,
+  isNumber,
   isObject,
   isRef,
   isString,
@@ -88,7 +95,10 @@ export {
   isImport,
   isArray,
   isBigInt,
+  isBoolean,
+  isInteger,
   isLiteral,
+  isNumber,
   isObject,
   isRef,
   isString,
@@ -146,6 +156,53 @@ 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";
+import { toNativeScript } 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";
+import {
+  mintToken,
+  simpleSend,
+  registerStakeScript,
+} from "./actions/builtin/utility-actions.js";
+
 export interface IMenuAction<S extends TSchema> {
   title: string;
   action: (sprinkle: Sprinkle<S>) => Promise<Sprinkle<S> | void>;
@@ -162,14 +219,17 @@ export class Sprinkle<S extends TSchema> {
   settings: TExact<S> = {} as TExact<S>;
   type: S;
   defaults: Record<string, unknown> = {};
+  addressbook: Record<string, TMultisigScript> = {};
   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 ---
@@ -252,6 +312,7 @@ export class Sprinkle<S extends TSchema> {
     this.profileMeta = parsed.meta;
     this.settings = await this.decryptSettings(parsed.settings as TExact<S>);
     this.defaults = parsed.defaults ?? {};
+    this.addressbook = parsed.addressbook ?? {};
     // Update active profile pointer
     fs.writeFileSync(Sprinkle.activeProfilePath(this.storagePath), id, "utf-8");
   }
@@ -274,6 +335,7 @@ export class Sprinkle<S extends TSchema> {
         meta: this.profileMeta,
         settings: settingsToSave,
         defaults: this.defaults,
+        addressbook: this.addressbook,
       },
       bigIntReplacer,
       2,
@@ -354,6 +416,7 @@ export class Sprinkle<S extends TSchema> {
           },
           settings: parsed.settings,
           defaults: parsed.defaults ?? {},
+          addressbook: parsed.addressbook ?? {},
         };
         fs.mkdirSync(profilesDir, { recursive: true });
         fs.writeFileSync(
@@ -438,6 +501,7 @@ export class Sprinkle<S extends TSchema> {
         meta: { name, description, createdAt: now, updatedAt: now },
         settings: settingsToSave,
         defaults: this.defaults,
+        addressbook: this.addressbook,
       },
       bigIntReplacer,
       2,
@@ -549,6 +613,7 @@ export class Sprinkle<S extends TSchema> {
     if (!main) {
       choices.push({ name: "Back", value: -1 });
     } else {
+      choices.push({ name: "Utilities", value: -6 });
       choices.push({ name: "Settings & Profiles", value: -5 });
       choices.push({ name: "Exit", value: -1 });
     }
@@ -567,6 +632,74 @@ export class Sprinkle<S extends TSchema> {
       return;
     }
     const selection = selectionResult as number;
+    if (selection === -6) {
+      const utilitiesMenu: IMenu<S> = {
+        title: "Utilities",
+        items: [
+          {
+            title: "Mint Token",
+            action: async () => {
+              const result = await promptAndExecute(this, mintToken);
+              if (!result.success) {
+                if (result.error.code === "USER_CANCELLED") return;
+                console.error(`\nError (${result.error.code}): ${result.error.message}\n`);
+                return;
+              }
+              const data = result.data as { txCbor: string; policyId: string; tokenName: string; amount: string };
+              console.log(`\nPolicy: ${data.policyId}\nToken: ${data.tokenName}\nAmount: ${data.amount}\n`);
+              const blaze = await Sprinkle.GetBlaze(
+                (this.settings as Record<string, unknown>).network as TExact<typeof NetworkSchema>,
+                (this.settings as Record<string, unknown>).provider as TExact<typeof ProviderSettingsSchema>,
+                (this.settings as Record<string, unknown>).wallet as TExact<typeof WalletSettingsSchema>,
+              );
+              const tx = Core.Transaction.fromCbor(Core.TxCBOR(data.txCbor));
+              await this.TxDialog(blaze, tx);
+            },
+          },
+          {
+            title: "Simple Send",
+            action: async () => {
+              const result = await promptAndExecute(this, simpleSend);
+              if (!result.success) {
+                if (result.error.code === "USER_CANCELLED") return;
+                console.error(`\nError (${result.error.code}): ${result.error.message}\n`);
+                return;
+              }
+              const data = result.data as { txCbor: string };
+              const blaze = await Sprinkle.GetBlaze(
+                (this.settings as Record<string, unknown>).network as TExact<typeof NetworkSchema>,
+                (this.settings as Record<string, unknown>).provider as TExact<typeof ProviderSettingsSchema>,
+                (this.settings as Record<string, unknown>).wallet as TExact<typeof WalletSettingsSchema>,
+              );
+              const tx = Core.Transaction.fromCbor(Core.TxCBOR(data.txCbor));
+              await this.TxDialog(blaze, tx);
+            },
+          },
+          {
+            title: "Register Stake Script",
+            action: async () => {
+              const result = await promptAndExecute(this, registerStakeScript);
+              if (!result.success) {
+                if (result.error.code === "USER_CANCELLED") return;
+                console.error(`\nError (${result.error.code}): ${result.error.message}\n`);
+                return;
+              }
+              const data = result.data as { txCbor: string };
+              const blaze = await Sprinkle.GetBlaze(
+                (this.settings as Record<string, unknown>).network as TExact<typeof NetworkSchema>,
+                (this.settings as Record<string, unknown>).provider as TExact<typeof ProviderSettingsSchema>,
+                (this.settings as Record<string, unknown>).wallet as TExact<typeof WalletSettingsSchema>,
+              );
+              const tx = Core.Transaction.fromCbor(Core.TxCBOR(data.txCbor));
+              await this.TxDialog(blaze, tx);
+            },
+          },
+        ],
+      };
+      await this._showMenu(utilitiesMenu, false, [...path, "Utilities"], true);
+      await this._showMenu(menu, main, path, true);
+      return;
+    }
     if (selection === -5) {
       const settingsMenu: IMenu<S> = {
         title: "Settings & Profiles",
@@ -640,6 +773,114 @@ export class Sprinkle<S extends TSchema> {
               await this.deleteProfile();
             },
           },
+          {
+            title: "Addressbook",
+            items: [
+              {
+                title: "View entries",
+                action: async () => {
+                  const entries = Object.entries(this.addressbook);
+                  if (entries.length === 0) {
+                    console.log("Addressbook is empty.");
+                  } else {
+                    for (const [name, ms] of entries) {
+                      const json = JSON.stringify(ms, bigIntReplacer, 2);
+                      let hashStr = "unknown";
+                      try {
+                        hashStr = toNativeScript(ms).hash();
+                      } catch { /* skip */ }
+                      console.log(colors.bold(name) + "  " + colors.dim(hashStr));
+                      console.log(json);
+                      console.log();
+                    }
+                  }
+                  await selectWithClear({
+                    message: "Press Enter to continue...",
+                    choices: [{ name: "Continue", value: "continue" }],
+                  });
+                },
+              },
+              {
+                title: "Add entry",
+                action: async () => {
+                  const name = await inputCancellable({
+                    message: "Entry name:",
+                    validate: (v) =>
+                      v.trim().length > 0 ? true : "Name cannot be empty",
+                  });
+                  if (name === null) return;
+                  if (this.addressbook[name]) {
+                    const overwrite = await confirmCancellable({
+                      message: `Entry "${name}" already exists. Overwrite?`,
+                      default: false,
+                    });
+                    if (!overwrite) return;
+                  }
+                  try {
+                    const script = await this.FillInStruct(MultisigScriptSchema);
+                    this.addressbook[name] = script as TMultisigScript;
+                    this.saveSettings();
+                    console.log(`Added "${name}" to addressbook.`);
+                  } catch (e) {
+                    if (e instanceof UserCancelledError) return;
+                    throw e;
+                  }
+                },
+              },
+              {
+                title: "Edit entry",
+                action: async () => {
+                  const entries = Object.keys(this.addressbook);
+                  if (entries.length === 0) {
+                    console.log("Addressbook is empty.");
+                    return;
+                  }
+                  const selected = await selectCancellable({
+                    message: "Select entry to edit:",
+                    choices: entries.map((n) => ({ name: n, value: n })),
+                  });
+                  if (selected === null) return;
+                  const editName = selected as string;
+                  try {
+                    const updated = await this.EditStruct(
+                      MultisigScriptSchema,
+                      this.addressbook[editName] as any,
+                    );
+                    this.addressbook[editName] = updated as TMultisigScript;
+                    this.saveSettings();
+                    console.log(`Updated "${editName}".`);
+                  } catch (e) {
+                    if (e instanceof UserCancelledError) return;
+                    throw e;
+                  }
+                },
+              },
+              {
+                title: "Delete entry",
+                action: async () => {
+                  const entries = Object.keys(this.addressbook);
+                  if (entries.length === 0) {
+                    console.log("Addressbook is empty.");
+                    return;
+                  }
+                  const delSelected = await selectCancellable({
+                    message: "Select entry to delete:",
+                    choices: entries.map((n) => ({ name: n, value: n })),
+                  });
+                  if (delSelected === null) return;
+                  const delName = delSelected as string;
+                  const confirmed = await confirmCancellable({
+                    message: `Delete "${delName}"?`,
+                    default: false,
+                  });
+                  if (!confirmed) return;
+                  delete this.addressbook[delName];
+                  this.saveSettings();
+                  console.log(`Deleted "${delName}".`);
+                },
+              },
+            ],
+          } as IMenu<S>,
         ],
       };
       await this._showMenu(settingsMenu, false, [...path, "Settings & Profiles"], true);
@@ -771,6 +1012,105 @@ 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: {},
+      addressbook: {},
+    };
+
+    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,
@@ -1095,9 +1435,58 @@ export class Sprinkle<S extends TSchema> {
           `Could not resolve type ${type["$ref"]} at ${path.join(".")}`,
         );
       }
-      return this._fillInStruct(resolvedType, path, defs, def) as Promise<
-        TExact<U>
-      >;
+
+      // Addressbook integration for MultisigScript fields
+      if (type["$ref"] === "MultisigScript" && Object.keys(this.addressbook).length > 0) {
+        const sourceChoice = await selectWithClear({
+          message: "Select source for native script:",
+          choices: [
+            { name: "Enter manually", value: "manual" },
+            { name: "Select from addressbook", value: "addressbook" },
+          ],
+        });
+        if (sourceChoice === null) throw new UserCancelledError();
+        if (sourceChoice === "addressbook") {
+          const entries = Object.entries(this.addressbook);
+          const abChoices = entries.map(([name, ms]) => {
+            let hashStr = "";
+            try { hashStr = "  " + colors.dim(toNativeScript(ms).hash()); } catch { /* skip */ }
+            return { name: name + hashStr, value: name };
+          });
+          const selected = await selectWithClear({
+            message: "Select addressbook entry:",
+            choices: abChoices,
+          });
+          if (selected === null) throw new UserCancelledError();
+          return this.addressbook[selected as string] as TExact<U>;
+        }
+      }
+
+      const result = await this._fillInStruct(resolvedType, path, defs, def) as TExact<U>;
+
+      // Offer to save manually entered MultisigScript to addressbook
+      if (type["$ref"] === "MultisigScript" && result !== undefined) {
+        const shouldSave = await selectWithClear({
+          message: "Save this script to the addressbook?",
+          choices: [
+            { name: "No", value: false },
+            { name: "Yes", value: true },
+          ],
+        });
+        if (shouldSave) {
+          const entryName = await inputCancellable({
+            message: "Addressbook entry name:",
+            validate: (v) => v.trim().length > 0 ? true : "Name cannot be empty",
+          });
+          if (entryName !== null) {
+            this.addressbook[entryName] = result as TMultisigScript;
+            this.saveSettings();
+            console.log(`Saved "${entryName}" to addressbook.`);
+          }
+        }
+      }
+
+      return result;
     }
     if (isOptional(type)) {
       const pathDisplay = formatPath(path) || "value";
@@ -1254,6 +1643,22 @@ export class Sprinkle<S extends TSchema> {
       return BigInt(answer) as TExact<U>;
     }
 
+    if (isBoolean(type)) {
+      const pathDisplay = formatPath(path) || "value";
+      const answer = await selectWithClear({
+        message: Sprinkle.ExtractMessage(type, `${pathDisplay}?`),
+        choices: [
+          { name: "Yes", value: true },
+          { name: "No", value: false },
+        ],
+        default: def !== undefined ? (def as boolean) : hasDefault(type) ? getDefault(type) : undefined,
+      });
+      if (answer === null) {
+        throw new UserCancelledError();
+      }
+      return answer as TExact<U>;
+    }
+
     if (isLiteral(type)) {
       return type.const as TExact<U>;
     }
@@ -1376,4 +1781,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;
+    }
+  }
 }