@sundaeswap/sprinkles 0.6.1 → 0.8.0

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

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

@@ -0,0 +1,381 @@
+/**
+ * Built-in transaction actions for the Sprinkle action system.
+ * These actions expose transaction signing, submission, and decoding
+ * as non-interactive actions available in CLI and MCP modes.
+ *
+ * Sign/submit actions use category "wallet".
+ * The decode action uses category "transaction" (no wallet required).
+ */
+
+import { Type } from "@sinclair/typebox";
+import type { TSchema } from "@sinclair/typebox";
+import { Core } from "@blaze-cardano/sdk";
+import { ActionError } from "../types.js";
+import type { IAction } from "../types.js";
+import { getBlazeFromContext, isHotWallet } from "./blaze-helper.js";
+import { countSignatures, getRequiredSigners } from "../../tx-dialog.js";
+
+/** Shared token entry schema (also used in wallet-actions) */
+const TokenEntrySchema = Type.Object({
+  policyId: Type.String({ description: "Policy ID of the token" }),
+  assetName: Type.String({ description: "Asset name of the token (hex)" }),
+  quantity: Type.String({ description: "Token quantity as string (BigInt-safe)" }),
+});
+
+/**
+ * Parses a hex CBOR string into a `Core.Transaction`.
+ * Throws `ActionError("INVALID_CBOR")` if the string is not valid transaction CBOR.
+ */
+function parseTxCbor(txCbor: string): Core.Transaction {
+  try {
+    return Core.Transaction.fromCbor(Core.TxCBOR(txCbor));
+  } catch (err) {
+    throw new ActionError(
+      `Invalid transaction CBOR: ${err instanceof Error ? err.message : String(err)}`,
+      "INVALID_CBOR",
+      { error: err instanceof Error ? err.message : String(err) },
+    );
+  }
+}
+
+/**
+ * `sign-transaction` -- Signs a transaction with the configured hot wallet.
+ * Cold wallets cannot sign; use an external signing tool and submit the result.
+ */
+export const signTransaction: IAction<
+  { txCbor: string },
+  { signedTxCbor: string; txHash: string; signatureCount: number },
+  TSchema
+> = {
+  name: "sign-transaction",
+  description:
+    "Sign a transaction with the configured hot wallet. Requires a hot wallet; cold wallets cannot sign.",
+  category: "wallet",
+  inputSchema: Type.Object({
+    txCbor: Type.String({ description: "Transaction CBOR hex string to sign" }),
+  }),
+  outputSchema: Type.Object({
+    signedTxCbor: Type.String({ description: "Signed transaction CBOR hex" }),
+    txHash: Type.String({ description: "Transaction hash" }),
+    signatureCount: Type.Number({ description: "Number of VKey witnesses after signing" }),
+  }),
+  execute: async (input, context) => {
+    const blaze = await getBlazeFromContext(context);
+
+    if (!isHotWallet(blaze)) {
+      throw new ActionError(
+        "Cold wallets cannot sign transactions. Export the CBOR and sign externally, then use submit-transaction.",
+        "COLD_WALLET",
+      );
+    }
+
+    const tx = parseTxCbor(input.txCbor);
+
+    let signedTx: Core.Transaction;
+    try {
+      signedTx = await blaze.signTransaction(tx);
+    } catch (err) {
+      throw new ActionError(
+        `Failed to sign transaction: ${err instanceof Error ? err.message : String(err)}`,
+        "SIGN_ERROR",
+        { error: err instanceof Error ? err.message : String(err) },
+      );
+    }
+
+    return {
+      signedTxCbor: signedTx.toCbor(),
+      txHash: signedTx.body().hash().toString(),
+      signatureCount: countSignatures(signedTx),
+    };
+  },
+};
+
+/**
+ * `submit-transaction` -- Submits a signed transaction to the blockchain.
+ */
+export const submitTransaction: IAction<
+  { txCbor: string },
+  { txHash: string; submitted: boolean },
+  TSchema
+> = {
+  name: "submit-transaction",
+  description: "Submit a signed transaction to the blockchain.",
+  category: "wallet",
+  inputSchema: Type.Object({
+    txCbor: Type.String({ description: "Signed transaction CBOR hex string to submit" }),
+  }),
+  outputSchema: Type.Object({
+    txHash: Type.String({ description: "Submitted transaction hash" }),
+    submitted: Type.Boolean(),
+  }),
+  execute: async (input, context) => {
+    const blaze = await getBlazeFromContext(context);
+    const tx = parseTxCbor(input.txCbor);
+
+    let txHash: Core.TransactionId;
+    try {
+      txHash = await blaze.submitTransaction(tx);
+    } catch (err) {
+      throw new ActionError(
+        `Transaction submission failed: ${err instanceof Error ? err.message : String(err)}`,
+        "SUBMISSION_ERROR",
+        { error: err instanceof Error ? err.message : String(err) },
+      );
+    }
+
+    return {
+      txHash: txHash.toString(),
+      submitted: true,
+    };
+  },
+};
+
+/**
+ * `sign-and-submit` -- Signs a transaction and immediately submits it.
+ * Optionally waits for on-chain confirmation with a configurable timeout.
+ */
+export const signAndSubmit: IAction<
+  {
+    txCbor: string;
+    waitForConfirmation?: boolean;
+    confirmationTimeout?: number;
+  },
+  {
+    txHash: string;
+    submitted: boolean;
+    confirmed?: boolean;
+    signedTxCbor: string;
+  },
+  TSchema
+> = {
+  name: "sign-and-submit",
+  description:
+    "Sign and submit a transaction. Optionally wait for on-chain confirmation.",
+  category: "wallet",
+  inputSchema: Type.Object({
+    txCbor: Type.String({ description: "Transaction CBOR hex string to sign and submit" }),
+    waitForConfirmation: Type.Optional(
+      Type.Boolean({
+        default: false,
+        description: "Whether to wait for on-chain confirmation before returning",
+      }),
+    ),
+    confirmationTimeout: Type.Optional(
+      Type.Number({
+        default: 60,
+        description: "Timeout in seconds to wait for confirmation",
+      }),
+    ),
+  }),
+  outputSchema: Type.Object({
+    txHash: Type.String({ description: "Transaction hash" }),
+    submitted: Type.Boolean(),
+    confirmed: Type.Optional(Type.Boolean({ description: "Whether tx was confirmed on-chain" })),
+    signedTxCbor: Type.String({ description: "Signed transaction CBOR hex" }),
+  }),
+  execute: async (input, context) => {
+    const blaze = await getBlazeFromContext(context);
+
+    if (!isHotWallet(blaze)) {
+      throw new ActionError(
+        "Cold wallets cannot sign transactions. Export the CBOR and sign externally, then use submit-transaction.",
+        "COLD_WALLET",
+      );
+    }
+
+    const tx = parseTxCbor(input.txCbor);
+
+    // Sign
+    let signedTx: Core.Transaction;
+    try {
+      signedTx = await blaze.signTransaction(tx);
+    } catch (err) {
+      throw new ActionError(
+        `Failed to sign transaction: ${err instanceof Error ? err.message : String(err)}`,
+        "SIGN_ERROR",
+        { error: err instanceof Error ? err.message : String(err) },
+      );
+    }
+
+    const signedTxCbor = signedTx.toCbor();
+
+    // Submit
+    let txHash: Core.TransactionId;
+    try {
+      txHash = await blaze.submitTransaction(signedTx);
+    } catch (err) {
+      throw new ActionError(
+        `Transaction submission failed: ${err instanceof Error ? err.message : String(err)}`,
+        "SUBMISSION_ERROR",
+        { error: err instanceof Error ? err.message : String(err), signedTxCbor },
+      );
+    }
+
+    const txHashStr = txHash.toString();
+
+    // If confirmation not requested, return immediately
+    if (!input.waitForConfirmation) {
+      return {
+        txHash: txHashStr,
+        submitted: true,
+        signedTxCbor,
+      };
+    }
+
+    // Poll for confirmation
+    const timeoutSeconds = input.confirmationTimeout ?? 60;
+    const deadline = Date.now() + timeoutSeconds * 1000;
+    const pollIntervalMs = 5000; // 5 seconds between polls
+
+    let confirmed = false;
+    while (Date.now() < deadline) {
+      await new Promise((resolve) => setTimeout(resolve, pollIntervalMs));
+      try {
+        // Query UTxOs and check if any reference this tx hash
+        // This is a lightweight confirmation check using the provider
+        const utxos = await blaze.provider.getUnspentOutputs(
+          await blaze.wallet.getChangeAddress(),
+        );
+        // If provider returns without error and tx hash appears in a UTxO input or
+        // the query succeeds after submission, assume confirmed.
+        // A more precise check would be to look up the tx directly.
+        // Use resolveUnspentOutputs if available, otherwise accept the provider response.
+        const anyMatch = utxos.some(
+          (u) => u.input().transactionId().toString() === txHashStr,
+        );
+        // If we get a fresh UTxO referencing our tx, confirmed
+        if (anyMatch) {
+          confirmed = true;
+          break;
+        }
+        // Check if we got back any UTxOs at all - for a send transaction the
+        // change output should be visible once confirmed
+        // Fall through and keep polling
+      } catch {
+        // Provider error during poll -- keep trying until timeout
+      }
+    }
+
+    if (!confirmed && input.waitForConfirmation) {
+      // Return partial success rather than throwing -- tx was submitted successfully
+      // but we couldn't confirm within the timeout
+      return {
+        txHash: txHashStr,
+        submitted: true,
+        confirmed: false,
+        signedTxCbor,
+      };
+    }
+
+    return {
+      txHash: txHashStr,
+      submitted: true,
+      confirmed,
+      signedTxCbor,
+    };
+  },
+};
+
+/**
+ * `decode-transaction` -- Decodes a transaction CBOR hex without requiring a wallet.
+ * Extracts inputs, outputs, fee, witness count, and required signers from the tx body.
+ */
+export const decodeTransaction: IAction<
+  { txCbor: string },
+  {
+    txHash: string;
+    inputs: Array<{ txHash: string; outputIndex: number }>;
+    outputs: Array<{
+      address: string;
+      lovelace: string;
+      tokens: Array<{ policyId: string; assetName: string; quantity: string }>;
+    }>;
+    fee: string;
+    signatureCount: number;
+    requiredSigners: string[];
+  },
+  TSchema
+> = {
+  name: "decode-transaction",
+  description:
+    "Decode a transaction CBOR hex and return its inputs, outputs, fee, and signers. Does not require a wallet.",
+  category: "transaction",
+  inputSchema: Type.Object({
+    txCbor: Type.String({ description: "Transaction CBOR hex string to decode" }),
+  }),
+  outputSchema: Type.Object({
+    txHash: Type.String({ description: "Transaction body hash" }),
+    inputs: Type.Array(
+      Type.Object({
+        txHash: Type.String({ description: "Input transaction hash" }),
+        outputIndex: Type.Number({ description: "Input output index" }),
+      }),
+    ),
+    outputs: Type.Array(
+      Type.Object({
+        address: Type.String({ description: "Output address (bech32 or hex)" }),
+        lovelace: Type.String({ description: "Output lovelace amount as string" }),
+        tokens: Type.Array(TokenEntrySchema),
+      }),
+    ),
+    fee: Type.String({ description: "Transaction fee in lovelace as string" }),
+    signatureCount: Type.Number({ description: "Number of VKey witnesses" }),
+    requiredSigners: Type.Array(
+      Type.String({ description: "Required signer key hashes" }),
+    ),
+  }),
+  execute: async (input, _context) => {
+    // No Blaze instance needed -- pure CBOR parsing
+    const tx = parseTxCbor(input.txCbor);
+
+    const body = tx.body();
+    const txHash = body.hash().toString();
+
+    // Extract inputs
+    const inputSet = body.inputs();
+    const inputs = Array.from(inputSet.values()).map((txInput) => ({
+      txHash: txInput.transactionId().toString(),
+      outputIndex: Number(txInput.index()),
+    }));
+
+    // Extract outputs
+    const outputs = body.outputs().map((txOutput) => {
+      const value = txOutput.amount();
+      const tokens: Array<{ policyId: string; assetName: string; quantity: string }> = [];
+
+      const multiasset = value.multiasset();
+      if (multiasset) {
+        for (const [assetId, quantity] of multiasset.entries()) {
+          tokens.push({
+            policyId: Core.AssetId.getPolicyId(assetId),
+            assetName: Core.AssetId.getAssetName(assetId),
+            quantity: quantity.toString(),
+          });
+        }
+      }
+
+      // Attempt bech32 address, fall back to hex if conversion fails
+      let address: string;
+      try {
+        address = txOutput.address().toBech32();
+      } catch {
+        address = txOutput.address().toBytes();
+      }
+
+      return {
+        address,
+        lovelace: value.coin().toString(),
+        tokens,
+      };
+    });
+
+    return {
+      txHash,
+      inputs,
+      outputs,
+      fee: body.fee().toString(),
+      signatureCount: countSignatures(tx),
+      requiredSigners: getRequiredSigners(tx),
+    };
+  },
+};