@sundaeswap/sprinkles 0.6.1 → 0.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sundaeswap/sprinkles",
-  "version": "0.6.1",
+  "version": "0.7.0",
   "description": "A TypeScript library for building interactive CLI menus and TUI applications with TypeBox schema validation",
   "type": "module",
   "main": "./dist/cjs/index.js",
@@ -64,7 +64,13 @@
   "peerDependencies": {
     "typescript": "^5.8.3",
     "@blaze-cardano/sdk": "^0.2.33",
-    "@blaze-cardano/query": "^0.5.0"
+    "@blaze-cardano/query": "^0.5.0",
+    "@modelcontextprotocol/sdk": "^1.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@modelcontextprotocol/sdk": {
+      "optional": true
+    }
   },
   "devDependencies": {
     "@babel/cli": "^7.27.2",
@@ -73,6 +79,7 @@
     "@babel/preset-env": "^7.27.2",
     "@babel/preset-typescript": "^7.27.1",
     "@changesets/cli": "^2.27.1",
+    "@modelcontextprotocol/sdk": "^1.0.0",
     "@types/bun": "latest",
     "@types/node": "^20.0.0",
     "cross-env": "^7.0.3",

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

@@ -0,0 +1,558 @@
+import { describe, expect, test, beforeEach, afterEach, spyOn } from "bun:test";
+import * as fs from "fs";
+import * as path from "path";
+import * as os from "os";
+import { Type } from "@sinclair/typebox";
+import { Sprinkle, ActionRegistry, ActionError } from "../index.js";
+import { withProfile } from "./test-helpers.js";
+
+// Helper: write a minimal profile file into a tmp storage directory
+function writeTestProfile(
+  storagePath: string,
+  id: string,
+  name: string,
+  settings: Record<string, unknown>,
+): void {
+  const dir = path.join(storagePath, "profiles");
+  fs.mkdirSync(dir, { recursive: true });
+  const meta = {
+    name,
+    createdAt: new Date().toISOString(),
+    updatedAt: new Date().toISOString(),
+  };
+  fs.writeFileSync(
+    path.join(dir, `${id}.json`),
+    JSON.stringify({ meta, settings, defaults: {} }, null, 2),
+    "utf-8",
+  );
+}
+
+// Simple settings schema used for integration tests
+const TestSchema = Type.Object({ name: Type.String() });
+
+// A reusable valid action
+const greetAction = {
+  name: "greet",
+  description: "Greets someone",
+  inputSchema: Type.Object({ who: Type.String() }),
+  outputSchema: Type.Object({ greeting: Type.String() }),
+  execute: async (input: { who: string }) => ({
+    greeting: `Hello, ${input.who}!`,
+  }),
+};
+
+describe("Sprinkle action integration", () => {
+  let tmpDir: string;
+
+  beforeEach(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "sprinkles-action-test-"));
+  });
+
+  afterEach(() => {
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  // -------------------------------------------------------------------------
+  // actionRegistry field
+  // -------------------------------------------------------------------------
+
+  test("Sprinkle constructor initialises actionRegistry", () => {
+    const sprinkle = new Sprinkle(TestSchema, tmpDir);
+    expect(sprinkle.actionRegistry).toBeInstanceOf(ActionRegistry);
+  });
+
+  // -------------------------------------------------------------------------
+  // registerAction / getAction / listActions
+  // -------------------------------------------------------------------------
+
+  test("registerAction stores an action retrievable via getAction", () => {
+    const sprinkle = new Sprinkle(TestSchema, tmpDir);
+    sprinkle.registerAction(greetAction);
+    expect(sprinkle.getAction("greet")).toBe(greetAction);
+  });
+
+  test("listActions returns all registered actions", () => {
+    const sprinkle = new Sprinkle(TestSchema, tmpDir);
+    const actionB = { ...greetAction, name: "farewell" };
+    sprinkle.registerAction(greetAction);
+    sprinkle.registerAction(actionB);
+    expect(sprinkle.listActions()).toHaveLength(2);
+  });
+
+  test("listActions returns empty array when no actions registered", () => {
+    const sprinkle = new Sprinkle(TestSchema, tmpDir);
+    expect(sprinkle.listActions()).toEqual([]);
+  });
+
+  test("getAction returns undefined for unknown action", () => {
+    const sprinkle = new Sprinkle(TestSchema, tmpDir);
+    expect(sprinkle.getAction("does-not-exist")).toBeUndefined();
+  });
+
+  test("registerAction throws for duplicate name", () => {
+    const sprinkle = new Sprinkle(TestSchema, tmpDir);
+    sprinkle.registerAction(greetAction);
+    expect(() => sprinkle.registerAction(greetAction)).toThrow(
+      /already registered/,
+    );
+  });
+
+  test("registerAction throws for non-kebab-case name", () => {
+    const sprinkle = new Sprinkle(TestSchema, tmpDir);
+    expect(() =>
+      sprinkle.registerAction({ ...greetAction, name: "BadName" }),
+    ).toThrow(/Invalid action name/);
+  });
+
+  // -------------------------------------------------------------------------
+  // runAction
+  // -------------------------------------------------------------------------
+
+  test("runAction executes action and returns success result", async () => {
+    const sprinkle = withProfile(new Sprinkle(TestSchema, tmpDir));
+    sprinkle.settings = { name: "tester" } as any;
+    sprinkle.registerAction(greetAction);
+
+    const result = await sprinkle.runAction("greet", { who: "World" });
+    expect(result.success).toBe(true);
+    if (result.success) {
+      expect(result.data).toEqual({ greeting: "Hello, World!" });
+    }
+  });
+
+  test("runAction returns failure result on invalid input", async () => {
+    const sprinkle = withProfile(new Sprinkle(TestSchema, tmpDir));
+    sprinkle.settings = { name: "tester" } as any;
+    sprinkle.registerAction(greetAction);
+
+    // 'who' field is missing
+    const result = await sprinkle.runAction("greet", { wrongField: "oops" });
+    expect(result.success).toBe(false);
+    if (!result.success) {
+      expect(result.error.code).toBe("VALIDATION_ERROR");
+    }
+  });
+
+  test("runAction throws when action name is not registered", async () => {
+    const sprinkle = new Sprinkle(TestSchema, tmpDir);
+    await expect(
+      sprinkle.runAction("not-registered", {}),
+    ).rejects.toThrow(/not registered/);
+  });
+
+  test("runAction error message lists available actions when none registered", async () => {
+    const sprinkle = new Sprinkle(TestSchema, tmpDir);
+    await expect(
+      sprinkle.runAction("nope", {}),
+    ).rejects.toThrow(/\(none\)/);
+  });
+
+  test("runAction error message lists registered action names", async () => {
+    const sprinkle = new Sprinkle(TestSchema, tmpDir);
+    sprinkle.registerAction(greetAction);
+    await expect(
+      sprinkle.runAction("nope", {}),
+    ).rejects.toThrow(/greet/);
+  });
+
+  test("runAction provides sprinkle and settings via context", async () => {
+    let capturedContext: any;
+    const ctxAction = {
+      name: "ctx-test",
+      description: "Captures context",
+      inputSchema: Type.Object({}),
+      outputSchema: Type.Object({}),
+      execute: async (_input: any, ctx: any) => {
+        capturedContext = ctx;
+        return {};
+      },
+    };
+
+    const sprinkle = withProfile(new Sprinkle(TestSchema, tmpDir));
+    sprinkle.settings = { name: "ctx-user" } as any;
+    sprinkle.registerAction(ctxAction);
+
+    await sprinkle.runAction("ctx-test", {});
+    expect(capturedContext.sprinkle).toBe(sprinkle);
+    expect(capturedContext.settings).toEqual({ name: "ctx-user" });
+  });
+
+  test("runAction propagates ActionError from execute without re-wrapping", async () => {
+    const myError = new ActionError("deliberate failure", "DELIBERATE", {
+      detail: 42,
+    });
+    const failAction = {
+      name: "fail-action",
+      description: "Always fails",
+      inputSchema: Type.Object({}),
+      outputSchema: Type.Object({}),
+      execute: async () => {
+        throw myError;
+      },
+    };
+
+    const sprinkle = withProfile(new Sprinkle(TestSchema, tmpDir));
+    sprinkle.settings = { name: "x" } as any;
+    sprinkle.registerAction(failAction);
+
+    const result = await sprinkle.runAction("fail-action", {});
+    expect(result.success).toBe(false);
+    if (!result.success) {
+      expect(result.error).toBe(myError);
+    }
+  });
+
+  // -------------------------------------------------------------------------
+  // Re-exports from index
+  // -------------------------------------------------------------------------
+
+  test("ActionRegistry is re-exported from Sprinkle index", () => {
+    expect(ActionRegistry).toBeDefined();
+  });
+
+  test("ActionError is re-exported from Sprinkle index", () => {
+    expect(ActionError).toBeDefined();
+  });
+
+  // -------------------------------------------------------------------------
+  // listActionsByCategory
+  // -------------------------------------------------------------------------
+
+  test("listActionsByCategory returns empty map when no actions registered", () => {
+    const sprinkle = new Sprinkle(TestSchema, tmpDir);
+    const map = sprinkle.listActionsByCategory();
+    expect(map.size).toBe(0);
+  });
+
+  test("listActionsByCategory places uncategorised actions under 'default'", () => {
+    const sprinkle = new Sprinkle(TestSchema, tmpDir);
+    sprinkle.registerAction(greetAction); // no category field
+    const map = sprinkle.listActionsByCategory();
+    expect(map.has("default")).toBe(true);
+    expect(map.get("default")).toHaveLength(1);
+    expect(map.get("default")![0]!.name).toBe("greet");
+  });
+
+  test("listActionsByCategory groups categorised actions correctly", () => {
+    const sprinkle = new Sprinkle(TestSchema, tmpDir);
+    const alpha1 = { ...greetAction, name: "alpha-one", category: "alpha" };
+    const alpha2 = { ...greetAction, name: "alpha-two", category: "alpha" };
+    const beta1 = { ...greetAction, name: "beta-one", category: "beta" };
+    sprinkle.registerAction(alpha1);
+    sprinkle.registerAction(alpha2);
+    sprinkle.registerAction(beta1);
+    const map = sprinkle.listActionsByCategory();
+    expect(map.get("alpha")).toHaveLength(2);
+    expect(map.get("beta")).toHaveLength(1);
+    expect(map.has("default")).toBe(false);
+  });
+
+  test("listActionsByCategory mixes categorised and uncategorised actions", () => {
+    const sprinkle = new Sprinkle(TestSchema, tmpDir);
+    const categorised = { ...greetAction, name: "cat-action", category: "tools" };
+    sprinkle.registerAction(greetAction); // uncategorised
+    sprinkle.registerAction(categorised);
+    const map = sprinkle.listActionsByCategory();
+    expect(map.get("default")).toHaveLength(1);
+    expect(map.get("tools")).toHaveLength(1);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Sprinkle.run() static entry point
+// ---------------------------------------------------------------------------
+
+describe("Sprinkle.run() static entry point", () => {
+  let tmpDir: string;
+  let logSpy: ReturnType<typeof spyOn>;
+  let errorSpy: ReturnType<typeof spyOn>;
+  let exitSpy: ReturnType<typeof spyOn>;
+
+  beforeEach(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "sprinkles-run-test-"));
+    logSpy = spyOn(console, "log").mockImplementation(() => {});
+    errorSpy = spyOn(console, "error").mockImplementation(() => {});
+    exitSpy = spyOn(process, "exit").mockImplementation(() => {
+      throw new Error("process.exit called");
+    });
+  });
+
+  afterEach(() => {
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+    logSpy.mockRestore();
+    errorSpy.mockRestore();
+    exitSpy.mockRestore();
+  });
+
+  // -------------------------------------------------------------------------
+  // help mode
+  // -------------------------------------------------------------------------
+
+  test("help mode prints 'No actions registered.' when no actions provided", async () => {
+    await Sprinkle.run({
+      type: TestSchema,
+      storagePath: tmpDir,
+      argv: ["--help"],
+    });
+    const output = logSpy.mock.calls.map((c) => String(c[0])).join("\n");
+    expect(output).toContain("No actions registered.");
+  });
+
+  test("help mode prints 'Available actions:' header when actions are registered", async () => {
+    await Sprinkle.run({
+      type: TestSchema,
+      storagePath: tmpDir,
+      actions: [greetAction],
+      argv: ["--help"],
+    });
+    const output = logSpy.mock.calls.map((c) => String(c[0])).join("\n");
+    expect(output).toContain("Available actions:");
+  });
+
+  test("help mode lists registered action name and description", async () => {
+    await Sprinkle.run({
+      type: TestSchema,
+      storagePath: tmpDir,
+      actions: [greetAction],
+      argv: ["--help"],
+    });
+    const output = logSpy.mock.calls.map((c) => String(c[0])).join("\n");
+    expect(output).toContain("greet");
+    expect(output).toContain("Greets someone");
+  });
+
+  test("help mode prints category header for categorised actions", async () => {
+    const catAction = { ...greetAction, name: "do-thing", category: "tools" };
+    await Sprinkle.run({
+      type: TestSchema,
+      storagePath: tmpDir,
+      actions: [catAction],
+      argv: ["--help"],
+    });
+    const output = logSpy.mock.calls.map((c) => String(c[0])).join("\n");
+    expect(output).toContain("tools:");
+  });
+
+  test("help mode does not print 'default:' header for uncategorised actions", async () => {
+    await Sprinkle.run({
+      type: TestSchema,
+      storagePath: tmpDir,
+      actions: [greetAction],
+      argv: ["--help"],
+    });
+    const output = logSpy.mock.calls.map((c) => String(c[0])).join("\n");
+    expect(output).not.toContain("default:");
+  });
+
+  test("help mode also triggers with -h flag", async () => {
+    await Sprinkle.run({
+      type: TestSchema,
+      storagePath: tmpDir,
+      argv: ["-h"],
+    });
+    const output = logSpy.mock.calls.map((c) => String(c[0])).join("\n");
+    expect(output).toContain("No actions registered.");
+  });
+
+  // -------------------------------------------------------------------------
+  // CLI mode
+  // -------------------------------------------------------------------------
+
+  test("CLI mode executes action and writes JSON result to stdout", async () => {
+    writeTestProfile(tmpDir, "default", "Default", { name: "tester" });
+    await Sprinkle.run({
+      type: TestSchema,
+      storagePath: tmpDir,
+      actions: [greetAction],
+      argv: ["greet", "--who", "World"],
+    });
+    const calls = logSpy.mock.calls.map((c) => String(c[0]));
+    const jsonLine = calls.find((l) => {
+      try {
+        JSON.parse(l);
+        return true;
+      } catch {
+        return false;
+      }
+    });
+    expect(jsonLine).toBeDefined();
+    const parsed = JSON.parse(jsonLine!);
+    expect(parsed.success).toBe(true);
+    expect(parsed.data).toEqual({ greeting: "Hello, World!" });
+  });
+
+  test("CLI mode result contains success:false for invalid input", async () => {
+    writeTestProfile(tmpDir, "default", "Default", { name: "tester" });
+    await expect(
+      Sprinkle.run({
+        type: TestSchema,
+        storagePath: tmpDir,
+        actions: [greetAction],
+        argv: ["greet"],
+      }),
+    ).rejects.toThrow("process.exit called");
+    const calls = errorSpy.mock.calls.map((c) => String(c[0]));
+    const jsonLine = calls.find((l) => {
+      try { JSON.parse(l); return true; } catch { return false; }
+    });
+    expect(jsonLine).toBeDefined();
+    const parsed = JSON.parse(jsonLine!);
+    expect(parsed.success).toBe(false);
+    expect(parsed.error.code).toBe("VALIDATION_ERROR");
+    expect(exitSpy).toHaveBeenCalledWith(1);
+  });
+
+  test("CLI mode --profile flag selects the named profile", async () => {
+    writeTestProfile(tmpDir, "alice", "Alice", { name: "alice" });
+    writeTestProfile(tmpDir, "bob", "Bob", { name: "bob" });
+
+    let capturedSettings: any;
+    const captureAction = {
+      name: "capture",
+      description: "Captures settings",
+      inputSchema: Type.Object({}),
+      outputSchema: Type.Object({ name: Type.String() }),
+      execute: async (_input: any, ctx: any) => {
+        capturedSettings = ctx.settings;
+        return { name: ctx.settings.name };
+      },
+    };
+
+    await Sprinkle.run({
+      type: TestSchema,
+      storagePath: tmpDir,
+      actions: [captureAction],
+      argv: ["capture", "--profile", "alice"],
+    });
+
+    expect(capturedSettings).toBeDefined();
+    expect(capturedSettings.name).toBe("alice");
+  });
+
+  test("CLI mode --profile flag selects the correct profile when multiple exist", async () => {
+    writeTestProfile(tmpDir, "alice", "Alice", { name: "alice" });
+    writeTestProfile(tmpDir, "bob", "Bob", { name: "bob" });
+
+    const captureAction = {
+      name: "capture-two",
+      description: "Captures settings",
+      inputSchema: Type.Object({}),
+      outputSchema: Type.Object({ name: Type.String() }),
+      execute: async (_input: any, ctx: any) => ({ name: ctx.settings.name }),
+    };
+
+    await Sprinkle.run({
+      type: TestSchema,
+      storagePath: tmpDir,
+      actions: [captureAction],
+      argv: ["capture-two", "--profile", "bob"],
+    });
+
+    const calls = logSpy.mock.calls.map((c) => String(c[0]));
+    const jsonLine = calls.find((l) => {
+      try { JSON.parse(l); return true; } catch { return false; }
+    });
+    const parsed = JSON.parse(jsonLine!);
+    expect(parsed.success).toBe(true);
+    expect(parsed.data.name).toBe("bob");
+  });
+
+  test("CLI mode auto-selects the only profile when no --profile flag given", async () => {
+    writeTestProfile(tmpDir, "solo", "Solo", { name: "solo-user" });
+
+    const captureAction = {
+      name: "capture-auto",
+      description: "Captures settings",
+      inputSchema: Type.Object({}),
+      outputSchema: Type.Object({ name: Type.String() }),
+      execute: async (_input: any, ctx: any) => ({ name: ctx.settings.name }),
+    };
+
+    await Sprinkle.run({
+      type: TestSchema,
+      storagePath: tmpDir,
+      actions: [captureAction],
+      argv: ["capture-auto"],
+    });
+
+    const calls = logSpy.mock.calls.map((c) => String(c[0]));
+    const jsonLine = calls.find((l) => {
+      try { JSON.parse(l); return true; } catch { return false; }
+    });
+    const parsed = JSON.parse(jsonLine!);
+    expect(parsed.success).toBe(true);
+    expect(parsed.data.name).toBe("solo-user");
+  });
+
+  test("CLI mode throws when multiple profiles exist and no --profile flag given", async () => {
+    writeTestProfile(tmpDir, "alice", "Alice", { name: "alice" });
+    writeTestProfile(tmpDir, "bob", "Bob", { name: "bob" });
+
+    await expect(
+      Sprinkle.run({
+        type: TestSchema,
+        storagePath: tmpDir,
+        actions: [greetAction],
+        argv: ["greet", "--who", "World"],
+      }),
+    ).rejects.toThrow(/--profile/);
+  });
+
+  test("CLI mode throws when no profiles exist", async () => {
+    await expect(
+      Sprinkle.run({
+        type: TestSchema,
+        storagePath: tmpDir,
+        actions: [greetAction],
+        argv: ["greet", "--who", "World"],
+      }),
+    ).rejects.toThrow(/No profiles found/);
+  });
+
+  // -------------------------------------------------------------------------
+  // TUI mode
+  // -------------------------------------------------------------------------
+
+  test("TUI mode throws when no menu option is provided", async () => {
+    await expect(
+      Sprinkle.run({
+        type: TestSchema,
+        storagePath: tmpDir,
+        argv: [],
+      }),
+    ).rejects.toThrow(/TUI mode requires a menu/);
+  });
+
+  test("TUI mode throws when --interactive flag is passed without a menu", async () => {
+    await expect(
+      Sprinkle.run({
+        type: TestSchema,
+        storagePath: tmpDir,
+        argv: ["--interactive"],
+      }),
+    ).rejects.toThrow(/TUI mode requires a menu/);
+  });
+
+  // -------------------------------------------------------------------------
+  // MCP mode
+  // -------------------------------------------------------------------------
+
+  test("MCP mode throws when SDK is not installed", async () => {
+    // MCP mode is implemented but requires the optional @modelcontextprotocol/sdk
+    // peer dependency. When the SDK is available (as in this dev environment),
+    // MCP mode will attempt to start a server. When the SDK is not installed,
+    // it should throw a clear error message with install instructions.
+    //
+    // In CI/dev with the SDK installed, MCP mode will attempt to connect to
+    // stdio transport. We test the error path by verifying the mode no longer
+    // throws "not yet implemented" -- specific MCP behavior is tested in
+    // mcp-adapter.test.ts.
+    await expect(
+      Sprinkle.run({
+        type: TestSchema,
+        storagePath: tmpDir,
+        argv: ["--mcp"],
+      }),
+    ).rejects.not.toThrow(/not yet implemented/i);
+  });
+});