@sundaeswap/sprinkles 0.6.0 → 0.7.0

package/src/Sprinkle/actions/builtin/blaze-helper.ts

@@ -0,0 +1,89 @@
+/**
+ * Shared helper utilities for wallet and transaction actions.
+ * Provides Blaze instance creation from action context settings.
+ */
+
+import type { TSchema } from "@sinclair/typebox";
+import { Blaze, HotWallet } from "@blaze-cardano/sdk";
+import type { Provider } from "@blaze-cardano/query";
+import type { Wallet } from "@blaze-cardano/sdk";
+import { GetBlaze } from "../../wallet.js";
+import { ActionError } from "../types.js";
+import type { IActionContext } from "../types.js";
+import type {
+  NetworkSchema,
+  ProviderSettingsSchema,
+  WalletSettingsSchema,
+} from "../../schemas.js";
+import type { TExact } from "../../types.js";
+
+/** Settings shape expected on context.settings for wallet access */
+export interface IWalletSettings {
+  network?: TExact<typeof NetworkSchema>;
+  provider?: TExact<typeof ProviderSettingsSchema>;
+  wallet?: TExact<typeof WalletSettingsSchema>;
+}
+
+/** Optional overrides for Blaze initialization, in case field names differ */
+export interface IBlazeOverrides {
+  network?: TExact<typeof NetworkSchema>;
+  provider?: TExact<typeof ProviderSettingsSchema>;
+  wallet?: TExact<typeof WalletSettingsSchema>;
+}
+
+/**
+ * Creates a Blaze instance from action context settings.
+ *
+ * Falls back to `context.settings.network`, `context.settings.provider`,
+ * and `context.settings.wallet` when overrides are not provided.
+ *
+ * @throws `ActionError("WALLET_NOT_CONFIGURED")` if required settings are missing
+ * @throws `ActionError("BLAZE_INIT_ERROR")` if Blaze fails to initialize
+ */
+export async function getBlazeFromContext<S extends TSchema>(
+  context: IActionContext<S>,
+  overrides?: IBlazeOverrides,
+): Promise<Blaze<Provider, Wallet>> {
+  const settings = context.settings as unknown as IWalletSettings;
+
+  const network = overrides?.network ?? settings.network;
+  const provider = overrides?.provider ?? settings.provider;
+  const wallet = overrides?.wallet ?? settings.wallet;
+
+  // Validate required fields and collect missing ones for a helpful error message
+  const missing: string[] = [];
+  if (!network) missing.push("network");
+  if (!provider) missing.push("provider");
+  if (!wallet) missing.push("wallet");
+
+  if (missing.length > 0) {
+    throw new ActionError(
+      `Wallet is not configured. Missing settings: ${missing.join(", ")}. ` +
+        `Set these fields in your profile settings before using wallet actions.`,
+      "WALLET_NOT_CONFIGURED",
+      { missingFields: missing },
+    );
+  }
+
+  try {
+    return await GetBlaze(
+      network as TExact<typeof NetworkSchema>,
+      provider as TExact<typeof ProviderSettingsSchema>,
+      wallet as TExact<typeof WalletSettingsSchema>,
+    );
+  } catch (err) {
+    throw new ActionError(
+      `Failed to initialize Blaze wallet: ${err instanceof Error ? err.message : String(err)}`,
+      "BLAZE_INIT_ERROR",
+      { error: err instanceof Error ? err.message : String(err) },
+    );
+  }
+}
+
+/**
+ * Checks whether the wallet in a Blaze instance is a hot wallet.
+ * Cold wallets cannot sign transactions.
+ */
+export function isHotWallet(blaze: Blaze<Provider, Wallet>): boolean {
+  return blaze.wallet instanceof HotWallet;
+}

package/src/Sprinkle/actions/builtin/index.ts

@@ -0,0 +1,86 @@
+/**
+ * Barrel export for built-in Sprinkle actions.
+ *
+ * Provides a `getBuiltinActions()` factory that returns all 14 built-in actions
+ * ready for registration on an ActionRegistry.
+ */
+
+import type { TSchema } from "@sinclair/typebox";
+import type { AnyAction } from "../types.js";
+
+export {
+  listProfiles,
+  getProfile,
+  setProfile,
+  createProfile,
+  deleteProfile,
+} from "./profile-actions.js";
+
+export { getSettings, updateSettings } from "./settings-actions.js";
+
+export {
+  getWalletAddress,
+  getWalletBalance,
+  getWalletUtxos,
+} from "./wallet-actions.js";
+
+export {
+  signTransaction,
+  submitTransaction,
+  signAndSubmit,
+  decodeTransaction,
+} from "./transaction-actions.js";
+
+import {
+  listProfiles,
+  getProfile,
+  setProfile,
+  createProfile,
+  deleteProfile,
+} from "./profile-actions.js";
+
+import { getSettings, updateSettings } from "./settings-actions.js";
+
+import {
+  getWalletAddress,
+  getWalletBalance,
+  getWalletUtxos,
+} from "./wallet-actions.js";
+
+import {
+  signTransaction,
+  submitTransaction,
+  signAndSubmit,
+  decodeTransaction,
+} from "./transaction-actions.js";
+
+/**
+ * Returns an array of all 14 built-in Sprinkle actions.
+ * Register them on your ActionRegistry or pass them to `Sprinkle.run()`.
+ *
+ * @example
+ * ```ts
+ * const sprinkle = new Sprinkle(MySchema, storagePath);
+ * for (const action of getBuiltinActions()) {
+ *   sprinkle.registerAction(action);
+ * }
+ * ```
+ */
+export function getBuiltinActions<S extends TSchema>(): AnyAction<S>[] {
+  return [
+    listProfiles,
+    getProfile,
+    setProfile,
+    createProfile,
+    deleteProfile,
+    getSettings,
+    updateSettings,
+    getWalletAddress,
+    getWalletBalance,
+    getWalletUtxos,
+    signTransaction,
+    submitTransaction,
+    signAndSubmit,
+    decodeTransaction,
+  ] as unknown as AnyAction<S>[];
+}

package/src/Sprinkle/actions/builtin/profile-actions.ts

@@ -0,0 +1,229 @@
+/**
+ * Built-in profile management actions for the Sprinkle action system.
+ * These actions expose profile CRUD operations as non-interactive actions
+ * available in CLI and MCP modes.
+ *
+ * All actions use category "sprinkles".
+ */
+
+import { Type } from "@sinclair/typebox";
+import type { TSchema } from "@sinclair/typebox";
+import { ActionError } from "../types.js";
+import type { IAction } from "../types.js";
+
+/** Shape of a profile entry as returned by profile actions */
+const ProfileEntrySchema = Type.Object({
+  id: Type.String(),
+  name: Type.String(),
+  description: Type.Optional(Type.String()),
+  createdAt: Type.String(),
+  updatedAt: Type.String(),
+});
+
+/**
+ * `list-profiles` -- Returns all profiles and the active profile ID.
+ */
+export const listProfiles: IAction<
+  Record<string, never>,
+  { profiles: unknown[]; activeProfileId: string | undefined },
+  TSchema
+> = {
+  name: "list-profiles",
+  description: "List all profiles and indicate which one is currently active.",
+  category: "sprinkles",
+  inputSchema: Type.Object({}),
+  outputSchema: Type.Object({
+    profiles: Type.Array(ProfileEntrySchema),
+    activeProfileId: Type.Optional(Type.String()),
+  }),
+  execute: async (_input, context) => {
+    const entries = context.sprinkle.scanProfiles();
+    const profiles = entries.map((e) => ({
+      id: e.id,
+      name: e.meta.name,
+      description: e.meta.description,
+      createdAt: e.meta.createdAt,
+      updatedAt: e.meta.updatedAt,
+    }));
+    return {
+      profiles,
+      activeProfileId: context.sprinkle.currentProfile?.id,
+    };
+  },
+};
+
+/**
+ * `get-profile` -- Returns metadata and settings for a specific profile.
+ * Settings are masked by default; pass `includeSensitive: true` to get raw values.
+ */
+export const getProfile: IAction<
+  { id: string; includeSensitive?: boolean },
+  unknown,
+  TSchema
+> = {
+  name: "get-profile",
+  description:
+    "Get metadata and settings for a profile. Sensitive fields are masked by default.",
+  category: "sprinkles",
+  inputSchema: Type.Object({
+    id: Type.String(),
+    includeSensitive: Type.Optional(Type.Boolean({ default: false })),
+  }),
+  outputSchema: Type.Object({
+    id: Type.String(),
+    name: Type.String(),
+    description: Type.Optional(Type.String()),
+    createdAt: Type.String(),
+    updatedAt: Type.String(),
+    settings: Type.Any(),
+  }),
+  execute: async (input, context) => {
+    // Validate ID to prevent path traversal (defense in depth)
+    if (input.id.includes("/") || input.id.includes("\\") || input.id.includes("..")) {
+      throw new ActionError(
+        `Invalid profile ID "${input.id}".`,
+        "INVALID_PROFILE_ID",
+        { id: input.id },
+      );
+    }
+
+    const profile = context.sprinkle.getProfileById(input.id);
+    if (!profile) {
+      throw new ActionError(
+        `Profile "${input.id}" not found.`,
+        "PROFILE_NOT_FOUND",
+        { id: input.id },
+      );
+    }
+
+    // Read the profile file to get settings
+    const fs = await import("fs");
+    const path = await import("path");
+    const storagePath = context.sprinkle.storagePath;
+
+    const profilePath = path.join(storagePath, "profiles", `${input.id}.json`);
+    let settings: unknown = {};
+    try {
+      const content = fs.readFileSync(profilePath, "utf-8");
+      const parsed = JSON.parse(content);
+      settings = parsed.settings ?? {};
+    } catch (err) {
+      // Throw an error so the caller knows the profile file couldn't be read
+      throw new ActionError(
+        `Failed to read profile "${input.id}": ${err instanceof Error ? err.message : String(err)}`,
+        "PROFILE_READ_ERROR",
+        { id: input.id, error: err instanceof Error ? err.message : String(err) },
+      );
+    }
+
+    // Mask sensitive fields unless includeSensitive is true
+    if (!input.includeSensitive) {
+      const { maskSensitiveFields } = await import("../../encryption.js");
+      settings = maskSensitiveFields(settings, context.sprinkle.type);
+    }
+
+    return {
+      id: profile.id,
+      name: profile.meta.name,
+      description: profile.meta.description,
+      createdAt: profile.meta.createdAt,
+      updatedAt: profile.meta.updatedAt,
+      settings,
+    };
+  },
+};
+
+/**
+ * `set-profile` -- Switch the active profile.
+ */
+export const setProfile: IAction<
+  { id: string },
+  { id: string; name: string },
+  TSchema
+> = {
+  name: "set-profile",
+  description: "Switch the active profile.",
+  category: "sprinkles",
+  inputSchema: Type.Object({
+    id: Type.String(),
+  }),
+  outputSchema: Type.Object({
+    id: Type.String(),
+    name: Type.String(),
+  }),
+  execute: async (input, context) => {
+    const profile = context.sprinkle.getProfileById(input.id);
+    if (!profile) {
+      throw new ActionError(
+        `Profile "${input.id}" not found.`,
+        "PROFILE_NOT_FOUND",
+        { id: input.id },
+      );
+    }
+
+    await context.sprinkle.loadProfile(input.id);
+    return {
+      id: input.id,
+      name: profile.meta.name,
+    };
+  },
+};
+
+/**
+ * `create-profile` -- Create a new profile without prompts.
+ */
+export const createProfile: IAction<
+  { name: string; description?: string; settings?: unknown },
+  { id: string; name: string },
+  TSchema
+> = {
+  name: "create-profile",
+  description: "Create a new profile.",
+  category: "sprinkles",
+  inputSchema: Type.Object({
+    name: Type.String(),
+    description: Type.Optional(Type.String()),
+    settings: Type.Optional(Type.Any()),
+  }),
+  outputSchema: Type.Object({
+    id: Type.String(),
+    name: Type.String(),
+  }),
+  execute: async (input, context) => {
+    const entry = await context.sprinkle.createProfileNonInteractive(
+      input.name,
+      input.description,
+      input.settings as never,
+    );
+    return {
+      id: entry.id,
+      name: entry.meta.name,
+    };
+  },
+};
+
+/**
+ * `delete-profile` -- Delete a profile by ID.
+ * Cannot delete the only profile or the currently active profile.
+ */
+export const deleteProfile: IAction<
+  { id: string },
+  { deleted: boolean; id: string },
+  TSchema
+> = {
+  name: "delete-profile",
+  description:
+    "Delete a profile. Cannot delete the only profile or the active profile.",
+  category: "sprinkles",
+  inputSchema: Type.Object({
+    id: Type.String(),
+  }),
+  outputSchema: Type.Object({
+    deleted: Type.Boolean(),
+    id: Type.String(),
+  }),
+  execute: async (input, context) => {
+    context.sprinkle.deleteProfileById(input.id);
+    return { deleted: true, id: input.id };
+  },
+};

package/src/Sprinkle/actions/builtin/settings-actions.ts

@@ -0,0 +1,99 @@
+/**
+ * Built-in settings actions for the Sprinkle action system.
+ * These actions expose settings read and update operations as non-interactive
+ * actions available in CLI and MCP modes.
+ *
+ * All actions use category "sprinkles".
+ */
+
+import { Type } from "@sinclair/typebox";
+import { Value } from "@sinclair/typebox/value";
+import type { TSchema } from "@sinclair/typebox";
+import { ActionError } from "../types.js";
+import type { IAction } from "../types.js";
+
+/**
+ * `get-settings` -- Returns the current profile settings.
+ * Sensitive fields are masked by default; pass `includeSensitive: true` for raw values.
+ */
+export const getSettings: IAction<
+  { includeSensitive?: boolean },
+  { settings: unknown; profileId: string; profileName: string },
+  TSchema
+> = {
+  name: "get-settings",
+  description:
+    "Get the current profile settings. Sensitive fields are masked by default.",
+  category: "sprinkles",
+  inputSchema: Type.Object({
+    includeSensitive: Type.Optional(Type.Boolean({ default: false })),
+  }),
+  outputSchema: Type.Object({
+    settings: Type.Any(),
+    profileId: Type.String(),
+    profileName: Type.String(),
+  }),
+  execute: async (input, context) => {
+    const settings = input.includeSensitive
+      ? context.sprinkle.settings
+      : context.sprinkle.getDisplaySettings();
+
+    return {
+      settings,
+      profileId: context.sprinkle.profileId,
+      profileName: context.sprinkle.profileMeta.name,
+    };
+  },
+};
+
+/**
+ * `update-settings` -- Shallow-merges settings onto the current profile and persists.
+ * Validates the merged result against the Sprinkle schema before saving.
+ * Returns masked settings.
+ */
+export const updateSettings: IAction<
+  { settings: Record<string, unknown> },
+  { settings: unknown; profileId: string },
+  TSchema
+> = {
+  name: "update-settings",
+  description:
+    "Merge partial settings onto the current profile and save. Returns masked settings.",
+  category: "sprinkles",
+  inputSchema: Type.Object({
+    settings: Type.Record(Type.String(), Type.Any()),
+  }),
+  outputSchema: Type.Object({
+    settings: Type.Any(),
+    profileId: Type.String(),
+  }),
+  execute: async (input, context) => {
+    // Shallow merge the incoming settings onto the current settings
+    const merged = {
+      ...(context.sprinkle.settings as Record<string, unknown>),
+      ...input.settings,
+    };
+
+    // Validate the merged result against the Sprinkle schema
+    if (!Value.Check(context.sprinkle.type, merged)) {
+      const errors = [...Value.Errors(context.sprinkle.type, merged)];
+      const message = errors
+        .map((e) => `${e.path}: ${e.message}`)
+        .join("; ");
+      throw new ActionError(
+        `Settings validation failed: ${message}`,
+        "VALIDATION_ERROR",
+        { errors },
+      );
+    }
+
+    // Apply and persist
+    context.sprinkle.settings = merged as typeof context.sprinkle.settings;
+    context.sprinkle.saveSettings();
+
+    return {
+      settings: context.sprinkle.getDisplaySettings(),
+      profileId: context.sprinkle.profileId,
+    };
+  },
+};