@sundaeswap/sprinkles 0.6.0 → 0.7.0

package/src/Sprinkle/__tests__/action-registry.test.ts

@@ -0,0 +1,187 @@
+import { describe, expect, test } from "bun:test";
+import { Type } from "@sinclair/typebox";
+import { ActionRegistry, ActionError } from "../actions/index.js";
+
+// Minimal valid action factory for test convenience
+function makeAction(overrides: Record<string, unknown> = {}) {
+  return {
+    name: "my-action",
+    description: "A test action",
+    inputSchema: Type.Object({ value: Type.String() }),
+    outputSchema: Type.Object({ result: Type.String() }),
+    execute: async (input: { value: string }) => ({ result: input.value }),
+    ...overrides,
+  };
+}
+
+describe("ActionRegistry", () => {
+  describe("register()", () => {
+    test("registers a valid action", () => {
+      const registry = new ActionRegistry();
+      const action = makeAction();
+      registry.register(action as any);
+      expect(registry.has("my-action")).toBe(true);
+    });
+
+    test("accepts single-word kebab-case names", () => {
+      const registry = new ActionRegistry();
+      registry.register(makeAction({ name: "transfer" }) as any);
+      expect(registry.has("transfer")).toBe(true);
+    });
+
+    test("accepts multi-segment kebab-case names", () => {
+      const registry = new ActionRegistry();
+      registry.register(makeAction({ name: "get-wallet-balance" }) as any);
+      expect(registry.has("get-wallet-balance")).toBe(true);
+    });
+
+    test("accepts names with digits", () => {
+      const registry = new ActionRegistry();
+      registry.register(makeAction({ name: "action2-v3" }) as any);
+      expect(registry.has("action2-v3")).toBe(true);
+    });
+
+    test("throws for UpperCase names", () => {
+      const registry = new ActionRegistry();
+      expect(() =>
+        registry.register(makeAction({ name: "MyAction" }) as any),
+      ).toThrow(/Invalid action name/);
+    });
+
+    test("throws for names with spaces", () => {
+      const registry = new ActionRegistry();
+      expect(() =>
+        registry.register(makeAction({ name: "my action" }) as any),
+      ).toThrow(/Invalid action name/);
+    });
+
+    test("throws for names with leading hyphens", () => {
+      const registry = new ActionRegistry();
+      expect(() =>
+        registry.register(makeAction({ name: "-my-action" }) as any),
+      ).toThrow(/Invalid action name/);
+    });
+
+    test("throws for names with trailing hyphens", () => {
+      const registry = new ActionRegistry();
+      expect(() =>
+        registry.register(makeAction({ name: "my-action-" }) as any),
+      ).toThrow(/Invalid action name/);
+    });
+
+    test("throws for names with consecutive hyphens", () => {
+      const registry = new ActionRegistry();
+      expect(() =>
+        registry.register(makeAction({ name: "my--action" }) as any),
+      ).toThrow(/Invalid action name/);
+    });
+
+    test("throws for duplicate action names", () => {
+      const registry = new ActionRegistry();
+      registry.register(makeAction() as any);
+      expect(() => registry.register(makeAction() as any)).toThrow(
+        /already registered/,
+      );
+    });
+
+    test("throws when inputSchema is missing", () => {
+      const registry = new ActionRegistry();
+      const action = makeAction({ inputSchema: undefined });
+      expect(() => registry.register(action as any)).toThrow(/inputSchema/);
+    });
+
+    test("throws when outputSchema is missing", () => {
+      const registry = new ActionRegistry();
+      const action = makeAction({ outputSchema: undefined });
+      expect(() => registry.register(action as any)).toThrow(/outputSchema/);
+    });
+  });
+
+  describe("get()", () => {
+    test("returns the registered action by name", () => {
+      const registry = new ActionRegistry();
+      const action = makeAction();
+      registry.register(action as any);
+      expect(registry.get("my-action")).toBe(action);
+    });
+
+    test("returns undefined for an unknown name", () => {
+      const registry = new ActionRegistry();
+      expect(registry.get("unknown")).toBeUndefined();
+    });
+  });
+
+  describe("has()", () => {
+    test("returns true for a registered action", () => {
+      const registry = new ActionRegistry();
+      registry.register(makeAction() as any);
+      expect(registry.has("my-action")).toBe(true);
+    });
+
+    test("returns false for an unregistered name", () => {
+      const registry = new ActionRegistry();
+      expect(registry.has("missing")).toBe(false);
+    });
+  });
+
+  describe("list()", () => {
+    test("returns empty array when no actions registered", () => {
+      const registry = new ActionRegistry();
+      expect(registry.list()).toEqual([]);
+    });
+
+    test("returns all registered actions", () => {
+      const registry = new ActionRegistry();
+      const a1 = makeAction({ name: "action-one" });
+      const a2 = makeAction({ name: "action-two" });
+      registry.register(a1 as any);
+      registry.register(a2 as any);
+      const list = registry.list();
+      expect(list).toHaveLength(2);
+      expect(list).toContain(a1);
+      expect(list).toContain(a2);
+    });
+  });
+
+  describe("listByCategory()", () => {
+    test("groups uncategorized actions under 'default'", () => {
+      const registry = new ActionRegistry();
+      registry.register(makeAction({ name: "action-a" }) as any);
+      const map = registry.listByCategory();
+      expect(map.has("default")).toBe(true);
+      expect(map.get("default")).toHaveLength(1);
+    });
+
+    test("groups actions by category string", () => {
+      const registry = new ActionRegistry();
+      registry.register(
+        makeAction({ name: "send-tx", category: "wallet" }) as any,
+      );
+      registry.register(
+        makeAction({ name: "get-balance", category: "wallet" }) as any,
+      );
+      registry.register(
+        makeAction({ name: "list-pools", category: "pool" }) as any,
+      );
+      const map = registry.listByCategory();
+      expect(map.get("wallet")).toHaveLength(2);
+      expect(map.get("pool")).toHaveLength(1);
+    });
+
+    test("mixes categorized and uncategorized actions", () => {
+      const registry = new ActionRegistry();
+      registry.register(
+        makeAction({ name: "action-cat", category: "info" }) as any,
+      );
+      registry.register(makeAction({ name: "action-nocat" }) as any);
+      const map = registry.listByCategory();
+      expect(map.get("info")).toHaveLength(1);
+      expect(map.get("default")).toHaveLength(1);
+    });
+
+    test("returns an empty map when no actions registered", () => {
+      const registry = new ActionRegistry();
+      expect(registry.listByCategory().size).toBe(0);
+    });
+  });
+});

package/src/Sprinkle/__tests__/action-runner.test.ts

@@ -0,0 +1,324 @@
+import { describe, expect, test } from "bun:test";
+import { Type } from "@sinclair/typebox";
+import {
+  executeAction,
+  detectMode,
+  parseCliArgs,
+  ActionError,
+} from "../actions/index.js";
+import type { IActionContext } from "../actions/index.js";
+
+// Lightweight stub context – the runner only forwards it to action.execute
+const fakeContext = {} as IActionContext<any>;
+
+// ---------------------------------------------------------------------------
+// executeAction
+// ---------------------------------------------------------------------------
+
+describe("executeAction", () => {
+  const echoAction = {
+    name: "echo",
+    description: "Returns its input as output",
+    inputSchema: Type.Object({ message: Type.String() }),
+    outputSchema: Type.Object({ message: Type.String() }),
+    execute: async (input: { message: string }) => ({ message: input.message }),
+  };
+
+  test("returns success result with data on valid input", async () => {
+    const result = await executeAction(
+      echoAction,
+      { message: "hello" },
+      fakeContext,
+    );
+    expect(result.success).toBe(true);
+    if (result.success) {
+      expect(result.data).toEqual({ message: "hello" });
+    }
+  });
+
+  test("returns failure result on invalid input", async () => {
+    const result = await executeAction(echoAction, { message: 42 }, fakeContext);
+    expect(result.success).toBe(false);
+    if (!result.success) {
+      expect(result.error.code).toBe("VALIDATION_ERROR");
+      expect(result.error.details).toBeDefined();
+    }
+  });
+
+  test("returns failure result when required field is missing", async () => {
+    const result = await executeAction(echoAction, {}, fakeContext);
+    expect(result.success).toBe(false);
+    if (!result.success) {
+      expect(result.error.code).toBe("VALIDATION_ERROR");
+    }
+  });
+
+  test("returns failure result when input is not an object", async () => {
+    const result = await executeAction(echoAction, "not-an-object", fakeContext);
+    expect(result.success).toBe(false);
+    if (!result.success) {
+      expect(result.error.code).toBe("VALIDATION_ERROR");
+    }
+  });
+
+  test("validation error includes per-field details", async () => {
+    const result = await executeAction(
+      echoAction,
+      { message: 99 },
+      fakeContext,
+    );
+    if (!result.success) {
+      const details = result.error.details as Array<{
+        path: string;
+        message: string;
+      }>;
+      expect(Array.isArray(details)).toBe(true);
+      expect(details.length).toBeGreaterThan(0);
+      expect(details[0]).toHaveProperty("path");
+      expect(details[0]).toHaveProperty("message");
+    }
+  });
+
+  test("wraps plain Error thrown by execute into EXECUTION_ERROR", async () => {
+    const failAction = {
+      ...echoAction,
+      execute: async () => {
+        throw new Error("something went wrong");
+      },
+    };
+    const result = await executeAction(
+      failAction,
+      { message: "x" },
+      fakeContext,
+    );
+    expect(result.success).toBe(false);
+    if (!result.success) {
+      expect(result.error.code).toBe("EXECUTION_ERROR");
+      expect(result.error.message).toBe("something went wrong");
+    }
+  });
+
+  test("re-uses ActionError thrown by execute without re-wrapping", async () => {
+    const myError = new ActionError("custom error", "CUSTOM_CODE", {
+      hint: "test",
+    });
+    const failAction = {
+      ...echoAction,
+      execute: async () => {
+        throw myError;
+      },
+    };
+    const result = await executeAction(
+      failAction,
+      { message: "x" },
+      fakeContext,
+    );
+    expect(result.success).toBe(false);
+    if (!result.success) {
+      expect(result.error).toBe(myError);
+      expect(result.error.code).toBe("CUSTOM_CODE");
+    }
+  });
+
+  test("decodes valid input and passes it to execute", async () => {
+    let receivedInput: any;
+    const actionWithOptional = {
+      name: "optional-test",
+      description: "Tests optional fields",
+      inputSchema: Type.Object({
+        name: Type.String(),
+        count: Type.Optional(Type.Number()),
+      }),
+      outputSchema: Type.Object({}),
+      execute: async (input: any) => {
+        receivedInput = input;
+        return {};
+      },
+    };
+    const result = await executeAction(
+      actionWithOptional,
+      { name: "alice", count: 5 },
+      fakeContext,
+    );
+    expect(result.success).toBe(true);
+    expect(receivedInput.name).toBe("alice");
+    expect(receivedInput.count).toBe(5);
+  });
+
+  test("passes context to execute function", async () => {
+    let receivedContext: any;
+    const ctxAction = {
+      ...echoAction,
+      execute: async (input: any, ctx: any) => {
+        receivedContext = ctx;
+        return { message: "ok" };
+      },
+    };
+    const ctx = { sprinkle: "stub", settings: {} } as any;
+    await executeAction(ctxAction, { message: "test" }, ctx);
+    expect(receivedContext).toBe(ctx);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// detectMode
+// ---------------------------------------------------------------------------
+
+describe("detectMode", () => {
+  test("returns 'tui' for empty argv", () => {
+    expect(detectMode([])).toBe("tui");
+  });
+
+  test("returns 'tui' for --interactive flag", () => {
+    expect(detectMode(["--interactive"])).toBe("tui");
+  });
+
+  test("returns 'tui' for --interactive alongside other flags", () => {
+    expect(detectMode(["--verbose", "--interactive"])).toBe("tui");
+  });
+
+  test("returns 'mcp' for --mcp flag", () => {
+    expect(detectMode(["--mcp"])).toBe("mcp");
+  });
+
+  test("returns 'mcp' when --mcp appears with other flags", () => {
+    expect(detectMode(["--verbose", "--mcp"])).toBe("mcp");
+  });
+
+  test("returns 'help' for --help flag only", () => {
+    expect(detectMode(["--help"])).toBe("help");
+  });
+
+  test("returns 'help' for -h shorthand only", () => {
+    expect(detectMode(["-h"])).toBe("help");
+  });
+
+  test("returns 'cli' when a positional arg is present", () => {
+    expect(detectMode(["get-balance"])).toBe("cli");
+  });
+
+  test("returns 'cli' when positional arg is mixed with flags", () => {
+    expect(detectMode(["--verbose", "send-tx", "--amount", "100"])).toBe("cli");
+  });
+
+  test("returns 'tui' for flag-only invocation that is not mcp/help/interactive", () => {
+    expect(detectMode(["--verbose", "--debug"])).toBe("tui");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// parseCliArgs
+// ---------------------------------------------------------------------------
+
+describe("parseCliArgs", () => {
+  test("extracts action name from first positional arg", () => {
+    const { actionName } = parseCliArgs(["get-balance"]);
+    expect(actionName).toBe("get-balance");
+  });
+
+  test("returns empty args when no flags follow the action name", () => {
+    const { args } = parseCliArgs(["get-balance"]);
+    expect(args).toEqual({});
+  });
+
+  test("parses --flag value pairs", () => {
+    const { args } = parseCliArgs(["send", "--amount", "100"]);
+    expect(args["amount"]).toBe("100");
+  });
+
+  test("parses --flag=value syntax", () => {
+    const { args } = parseCliArgs(["send", "--amount=100"]);
+    expect(args["amount"]).toBe("100");
+  });
+
+  test("parses --no-flag as boolean false", () => {
+    const { args } = parseCliArgs(["send", "--no-confirm"]);
+    expect(args["confirm"]).toBe(false);
+  });
+
+  test("treats lone --flag with no value as boolean true", () => {
+    const { args } = parseCliArgs(["send", "--dry-run"]);
+    expect(args["dry-run"]).toBe(true);
+  });
+
+  test("parses JSON object value", () => {
+    const { args } = parseCliArgs([
+      "send",
+      "--input",
+      '{"key":"value","count":3}',
+    ]);
+    expect(args["input"]).toEqual({ key: "value", count: 3 });
+  });
+
+  test("parses JSON array value", () => {
+    const { args } = parseCliArgs(["send", "--ids", '["a","b","c"]']);
+    expect(args["ids"]).toEqual(["a", "b", "c"]);
+  });
+
+  test("falls back to string when JSON parse fails", () => {
+    const { args } = parseCliArgs(["send", "--data", "{bad json"]);
+    expect(args["data"]).toBe("{bad json");
+  });
+
+  test("parses multiple flags", () => {
+    const { args } = parseCliArgs([
+      "transfer",
+      "--from",
+      "addr1",
+      "--to",
+      "addr2",
+      "--amount",
+      "50",
+    ]);
+    expect(args["from"]).toBe("addr1");
+    expect(args["to"]).toBe("addr2");
+    expect(args["amount"]).toBe("50");
+  });
+
+  test("throws when all args start with dashes (no positional)", () => {
+    expect(() => parseCliArgs(["--verbose", "--debug"])).toThrow(
+      /No action name provided/,
+    );
+  });
+
+  test("throws when argv is empty", () => {
+    expect(() => parseCliArgs([])).toThrow(/No action name provided/);
+  });
+
+  test("action name is not included in args", () => {
+    const { args } = parseCliArgs(["my-action", "--key", "val"]);
+    expect(args).not.toHaveProperty("my-action");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// ActionError
+// ---------------------------------------------------------------------------
+
+describe("ActionError", () => {
+  test("sets name to 'ActionError'", () => {
+    const err = new ActionError("oops", "CODE");
+    expect(err.name).toBe("ActionError");
+  });
+
+  test("extends Error", () => {
+    const err = new ActionError("oops", "CODE");
+    expect(err instanceof Error).toBe(true);
+  });
+
+  test("stores code", () => {
+    const err = new ActionError("oops", "MY_CODE");
+    expect(err.code).toBe("MY_CODE");
+  });
+
+  test("stores optional details", () => {
+    const details = { field: "amount" };
+    const err = new ActionError("oops", "CODE", details);
+    expect(err.details).toBe(details);
+  });
+
+  test("details is undefined when not provided", () => {
+    const err = new ActionError("oops", "CODE");
+    expect(err.details).toBeUndefined();
+  });
+});