@sundaeswap/sprinkles 0.1.1

package/package.json

@@ -0,0 +1,85 @@
+{
+  "name": "@sundaeswap/sprinkles",
+  "version": "0.1.1",
+  "description": "A TypeScript library for building interactive CLI menus and TUI applications with TypeBox schema validation",
+  "type": "module",
+  "main": "./dist/cjs/index.js",
+  "module": "./dist/esm/index.js",
+  "types": "./dist/types/index.d.ts",
+  "exports": {
+    ".": {
+      "require": "./dist/cjs/index.js",
+      "import": "./dist/esm/index.js",
+      "types": "./dist/types/index.d.ts"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "engineStrict": true,
+  "engines": {
+    "node": "^22"
+  },
+  "scripts": {
+    "clean": "rm -rf ./dist",
+    "build:esm": "cross-env BABEL_ENV=esmUnbundled babel src --extensions '.ts,.tsx' --out-dir './dist/esm' --source-maps",
+    "build:cjs": "cross-env BABEL_ENV=cjs babel src --extensions '.ts,.tsx' --out-dir 'dist/cjs' --source-maps",
+    "types": "tsc --project ./tsconfig.build.json",
+    "build": "bun clean && bun types && bun build:esm && bun build:cjs && bun set-cjs",
+    "watch": "bun clean && bun run build && bun build:esm --watch",
+    "set-cjs": "echo '{ \"type\": \"commonjs\" }' > ./dist/cjs/package.json",
+    "test": "bun test src/",
+    "prepublishOnly": "bun run build",
+    "changeset": "changeset",
+    "version": "changeset version",
+    "release": "bun run build && changeset publish"
+  },
+  "keywords": [
+    "cli",
+    "tui",
+    "terminal",
+    "interactive",
+    "menu",
+    "typebox",
+    "inquirer",
+    "cardano"
+  ],
+  "author": "SundaeSwap Labs",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/SundaeSwap-finance/sprinkles.git"
+  },
+  "homepage": "https://github.com/SundaeSwap-finance/sprinkles#readme",
+  "bugs": {
+    "url": "https://github.com/SundaeSwap-finance/sprinkles/issues"
+  },
+  "peerDependencies": {
+    "typescript": "^5.8.3",
+    "@blaze-cardano/sdk": "^0.2.33",
+    "@blaze-cardano/query": "^0.5.0"
+  },
+  "devDependencies": {
+    "@changesets/cli": "^2.27.1",
+    "@babel/cli": "^7.27.2",
+    "@babel/core": "^7.27.4",
+    "@babel/plugin-proposal-class-properties": "^7.18.6",
+    "@babel/preset-env": "^7.27.2",
+    "@babel/preset-typescript": "^7.27.1",
+    "@types/bun": "latest",
+    "@types/node": "^20.0.0",
+    "cross-env": "^7.0.3",
+    "typescript": "^5.8.3"
+  },
+  "dependencies": {
+    "@inquirer/prompts": "^7.5.3",
+    "@sinclair/typebox": "^0.34.41",
+    "clipboardy": "^5.2.1"
+  }
+}

package/src/Sprinkle/__tests__/bigint-reviver.test.ts

@@ -0,0 +1,49 @@
+import { describe, expect, test } from "bun:test";
+import { Sprinkle } from "../index.js";
+
+describe("bigIntReviver", () => {
+  test("converts string ending with n to BigInt", () => {
+    expect(Sprinkle.bigIntReviver("key", "42n")).toBe(42n);
+  });
+
+  test("converts zero bigint string", () => {
+    expect(Sprinkle.bigIntReviver("key", "0n")).toBe(0n);
+  });
+
+  test("converts large bigint string", () => {
+    expect(Sprinkle.bigIntReviver("key", "99999999999999999999n")).toBe(
+      99999999999999999999n,
+    );
+  });
+
+  test("does not convert regular strings", () => {
+    expect(Sprinkle.bigIntReviver("key", "hello")).toBe("hello");
+  });
+
+  test("does not convert strings with n in the middle", () => {
+    expect(Sprinkle.bigIntReviver("key", "12n34")).toBe("12n34");
+  });
+
+  test("does not convert non-numeric n-suffixed strings", () => {
+    expect(Sprinkle.bigIntReviver("key", "abcn")).toBe("abcn");
+  });
+
+  test("passes through numbers unchanged", () => {
+    expect(Sprinkle.bigIntReviver("key", 42)).toBe(42);
+  });
+
+  test("passes through booleans unchanged", () => {
+    expect(Sprinkle.bigIntReviver("key", true)).toBe(true);
+  });
+
+  test("passes through null unchanged", () => {
+    expect(Sprinkle.bigIntReviver("key", null)).toBe(null);
+  });
+
+  test("works with JSON.parse", () => {
+    const json = '{"amount": "100n", "name": "test"}';
+    const parsed = JSON.parse(json, Sprinkle.bigIntReviver);
+    expect(parsed.amount).toBe(100n);
+    expect(parsed.name).toBe("test");
+  });
+});

package/src/Sprinkle/__tests__/encryption.test.ts

@@ -0,0 +1,266 @@
+import { describe, expect, test, mock, beforeEach, afterEach } from "bun:test";
+import { Sprinkle, Type } from "../index.js";
+import * as fs from "fs";
+import * as path from "path";
+import * as os from "os";
+import { withProfile } from "./test-helpers.js";
+
+const mockSelect = mock();
+const mockInput = mock();
+const mockPassword = mock();
+
+mock.module("@inquirer/prompts", () => ({
+  select: mockSelect,
+  input: mockInput,
+  password: mockPassword,
+}));
+
+describe("Encryption & Sensitive Fields", () => {
+  let tmpDir: string;
+
+  beforeEach(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "sprinkles-enc-test-"));
+    mockSelect.mockClear();
+    mockInput.mockClear();
+    mockPassword.mockClear();
+  });
+
+  afterEach(() => {
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  describe("sensitive field prompts", () => {
+    test("uses password() for sensitive string fields", async () => {
+      const schema = Type.Object({
+        secret: Type.String({ sensitive: true, title: "Enter secret" }),
+      });
+      const sprinkle = new Sprinkle(schema, tmpDir);
+
+      mockPassword.mockResolvedValueOnce("my-secret");
+
+      const result = await sprinkle.FillInStruct(schema);
+      expect(result).toEqual({ secret: "my-secret" });
+      expect(mockPassword).toHaveBeenCalledTimes(1);
+      expect(mockPassword.mock.calls[0][0].message).toBe("Enter secret");
+      expect(mockInput).not.toHaveBeenCalled();
+    });
+
+    test("uses input() for non-sensitive string fields", async () => {
+      const schema = Type.Object({
+        name: Type.String({ title: "Enter name" }),
+      });
+      const sprinkle = new Sprinkle(schema, tmpDir);
+
+      mockInput.mockResolvedValueOnce("visible");
+
+      const result = await sprinkle.FillInStruct(schema);
+      expect(result).toEqual({ name: "visible" });
+      expect(mockInput).toHaveBeenCalledTimes(1);
+      expect(mockPassword).not.toHaveBeenCalled();
+    });
+
+    test("does not remember sensitive field as default", async () => {
+      const schema = Type.String({ sensitive: true });
+      const sprinkle = new Sprinkle(Type.Object({ p: Type.String() }), tmpDir);
+
+      mockPassword.mockResolvedValueOnce("secret-val");
+
+      await sprinkle.FillInStruct(schema);
+      expect(sprinkle.defaults["string"]).toBeUndefined();
+    });
+  });
+
+  describe("encryption on save/load", () => {
+    test("encrypts sensitive fields when saving with encryption configured", () => {
+      const schema = Type.Object({
+        name: Type.String(),
+        secret: Type.String({ sensitive: true }),
+      });
+      const sprinkle = withProfile(
+        new Sprinkle(schema, tmpDir, {
+          encryption: {
+            encrypt: (plain) => `ENC:${plain}`,
+            decrypt: async (cipher) => cipher.replace("ENC:", ""),
+          },
+        }),
+      );
+      sprinkle.settings = { name: "visible", secret: "hidden" } as any;
+
+      sprinkle.saveSettings();
+
+      const content = fs.readFileSync(
+        path.join(tmpDir, "profiles", "test.json"),
+        "utf-8",
+      );
+      const parsed = JSON.parse(content);
+      expect(parsed.settings.name).toBe("visible");
+      expect(parsed.settings.secret).toBe("ENC:hidden");
+    });
+
+    test("decrypts sensitive fields when loading with encryption configured", async () => {
+      const schema = Type.Object({
+        name: Type.String(),
+        secret: Type.String({ sensitive: true }),
+      });
+
+      // First save with encryption
+      const sprinkle1 = withProfile(
+        new Sprinkle(schema, tmpDir, {
+          encryption: {
+            encrypt: (plain) => `ENC:${plain}`,
+            decrypt: async (cipher) => cipher.replace("ENC:", ""),
+          },
+        }),
+      );
+      sprinkle1.settings = { name: "visible", secret: "hidden" } as any;
+      sprinkle1.saveSettings();
+
+      // Then load with same encryption
+      const sprinkle2 = new Sprinkle(schema, tmpDir, {
+        encryption: {
+          encrypt: (plain) => `ENC:${plain}`,
+          decrypt: async (cipher) => cipher.replace("ENC:", ""),
+        },
+      });
+      await sprinkle2.loadProfile("test");
+
+      expect(sprinkle2.settings).toEqual({ name: "visible", secret: "hidden" });
+    });
+
+    test("does not encrypt when no encryption configured", () => {
+      const schema = Type.Object({
+        secret: Type.String({ sensitive: true }),
+      });
+      const sprinkle = withProfile(new Sprinkle(schema, tmpDir));
+      sprinkle.settings = { secret: "plain-value" } as any;
+
+      sprinkle.saveSettings();
+
+      const content = fs.readFileSync(
+        path.join(tmpDir, "profiles", "test.json"),
+        "utf-8",
+      );
+      const parsed = JSON.parse(content);
+      expect(parsed.settings.secret).toBe("plain-value");
+    });
+
+    test("encrypts nested sensitive fields", () => {
+      const schema = Type.Object({
+        wallet: Type.Object({
+          key: Type.String({ sensitive: true }),
+          address: Type.String(),
+        }),
+      });
+      const sprinkle = withProfile(
+        new Sprinkle(schema, tmpDir, {
+          encryption: {
+            encrypt: (plain) => `ENC:${plain}`,
+            decrypt: async (cipher) => cipher.replace("ENC:", ""),
+          },
+        }),
+      );
+      sprinkle.settings = {
+        wallet: { key: "secret-key", address: "addr1..." },
+      } as any;
+
+      sprinkle.saveSettings();
+
+      const content = fs.readFileSync(
+        path.join(tmpDir, "profiles", "test.json"),
+        "utf-8",
+      );
+      const parsed = JSON.parse(content);
+      expect(parsed.settings.wallet.key).toBe("ENC:secret-key");
+      expect(parsed.settings.wallet.address).toBe("addr1...");
+    });
+
+    test("handles sensitive fields in union variants", () => {
+      const schema = Type.Union([
+        Type.Object({
+          type: Type.Literal("hot"),
+          privateKey: Type.String({ sensitive: true }),
+        }),
+        Type.Object({
+          type: Type.Literal("cold"),
+          address: Type.String(),
+        }),
+      ]);
+      const outerSchema = Type.Object({ wallet: schema });
+      const sprinkle = withProfile(
+        new Sprinkle(outerSchema, tmpDir, {
+          encryption: {
+            encrypt: (plain) => `ENC:${plain}`,
+            decrypt: async (cipher) => cipher.replace("ENC:", ""),
+          },
+        }),
+      );
+      sprinkle.settings = {
+        wallet: { type: "hot", privateKey: "my-key" },
+      } as any;
+
+      sprinkle.saveSettings();
+
+      const content = fs.readFileSync(
+        path.join(tmpDir, "profiles", "test.json"),
+        "utf-8",
+      );
+      const parsed = JSON.parse(content);
+      expect(parsed.settings.wallet.privateKey).toBe("ENC:my-key");
+    });
+
+    test("round-trip with encryption preserves all data", async () => {
+      const schema = Type.Object({
+        network: Type.String(),
+        secret: Type.String({ sensitive: true }),
+        count: Type.BigInt(),
+      });
+      const opts = {
+        encryption: {
+          encrypt: (plain: string) => Buffer.from(plain).toString("base64"),
+          decrypt: async (cipher: string) =>
+            Buffer.from(cipher, "base64").toString(),
+        },
+      };
+      const s1 = withProfile(new Sprinkle(schema, tmpDir, opts));
+      s1.settings = {
+        network: "mainnet",
+        secret: "top-secret",
+        count: 42n,
+      } as any;
+      s1.saveSettings();
+
+      const s2 = new Sprinkle(schema, tmpDir, opts);
+      await s2.loadProfile("test");
+
+      expect(s2.settings).toEqual({
+        network: "mainnet",
+        secret: "top-secret",
+        count: 42n,
+      });
+    });
+  });
+
+  describe("Sprinkle.New with options", () => {
+    test("passes options through to instance and migrates legacy", async () => {
+      const schema = Type.Object({ name: Type.String() });
+
+      // Write legacy settings file so New triggers migration
+      fs.mkdirSync(tmpDir, { recursive: true });
+      fs.writeFileSync(
+        path.join(tmpDir, "settings.json"),
+        JSON.stringify({ settings: { name: "test" }, defaults: {} }),
+      );
+
+      const sprinkle = await Sprinkle.New(schema, tmpDir, {
+        encryption: {
+          encrypt: (p) => p,
+          decrypt: async (c) => c,
+        },
+      });
+
+      expect(sprinkle.options.encryption).toBeDefined();
+      expect(sprinkle.profileId).toBe("default");
+      expect(sprinkle.settings).toEqual({ name: "test" });
+    });
+  });
+});

package/src/Sprinkle/__tests__/enhancements.test.ts

@@ -0,0 +1,154 @@
+import { describe, expect, test, mock, beforeEach } from "bun:test";
+import { Sprinkle, Type, type IMenu } from "../index.js";
+
+const mockSelect = mock();
+const mockInput = mock();
+const mockPassword = mock();
+const mockSearch = mock();
+
+mock.module("@inquirer/prompts", () => ({
+  select: mockSelect,
+  input: mockInput,
+  password: mockPassword,
+  search: mockSearch,
+}));
+
+describe("beforeShow hook (2.2)", () => {
+  let sprinkle: Sprinkle<any>;
+
+  beforeEach(() => {
+    const schema = Type.Object({ name: Type.String() });
+    sprinkle = new Sprinkle(schema, "/tmp/test");
+    sprinkle.settings = { name: "test" } as any;
+    mockSelect.mockClear();
+  });
+
+  test("calls beforeShow before rendering menu", async () => {
+    const callOrder: string[] = [];
+
+    const beforeShowFn = mock(async () => {
+      callOrder.push("beforeShow");
+    });
+
+    mockSelect.mockImplementation(async () => {
+      callOrder.push("select");
+      return -1; // exit
+    });
+
+    const menu: IMenu<any> = {
+      title: "Test",
+      beforeShow: beforeShowFn,
+      items: [{ title: "Action", action: async () => {} }],
+    };
+
+    await sprinkle.showMenu(menu);
+
+    expect(beforeShowFn).toHaveBeenCalledTimes(1);
+    expect(callOrder[0]).toBe("beforeShow");
+    expect(callOrder[1]).toBe("select");
+  });
+
+  test("passes sprinkle instance to beforeShow", async () => {
+    let receivedSprinkle: any;
+
+    mockSelect.mockResolvedValueOnce(-1);
+
+    const menu: IMenu<any> = {
+      title: "Test",
+      beforeShow: async (s) => {
+        receivedSprinkle = s;
+      },
+      items: [{ title: "Action", action: async () => {} }],
+    };
+
+    await sprinkle.showMenu(menu);
+    expect(receivedSprinkle).toBe(sprinkle);
+  });
+
+  test("menu works without beforeShow", async () => {
+    mockSelect.mockResolvedValueOnce(-1);
+
+    const menu: IMenu<any> = {
+      title: "Test",
+      items: [{ title: "Action", action: async () => {} }],
+    };
+
+    await sprinkle.showMenu(menu);
+    // Should complete without error
+  });
+});
+
+describe("SearchSelect (2.3)", () => {
+  beforeEach(() => {
+    mockSearch.mockClear();
+  });
+
+  test("delegates to search prompt", async () => {
+    mockSearch.mockResolvedValueOnce("selected-value");
+
+    const result = await Sprinkle.SearchSelect({
+      message: "Pick one",
+      source: () => [
+        { name: "Option A", value: "a" },
+        { name: "Option B", value: "b" },
+      ],
+    });
+
+    expect(result).toBe("selected-value");
+    expect(mockSearch).toHaveBeenCalledTimes(1);
+    expect(mockSearch.mock.calls[0][0].message).toBe("Pick one");
+  });
+
+  test("passes source function through", async () => {
+    const sourceFn = mock(() => [{ name: "X", value: "x" }]);
+    mockSearch.mockResolvedValueOnce("x");
+
+    await Sprinkle.SearchSelect({
+      message: "Search",
+      source: sourceFn,
+    });
+
+    expect(mockSearch.mock.calls[0][0].source).toBe(sourceFn);
+  });
+});
+
+describe("Optional type support (2.4)", () => {
+  let sprinkle: Sprinkle<any>;
+
+  beforeEach(() => {
+    const schema = Type.Object({ placeholder: Type.String() });
+    sprinkle = new Sprinkle(schema, "/tmp/test");
+    mockSelect.mockClear();
+    mockInput.mockClear();
+  });
+
+  test("skips optional field when user selects Skip", async () => {
+    const schema = Type.Object({
+      name: Type.String(),
+      nickname: Type.Optional(Type.String()),
+    });
+
+    mockInput.mockResolvedValueOnce("Alice"); // name
+    mockSelect.mockResolvedValueOnce(false); // skip nickname
+
+    const result = await sprinkle.FillInStruct(schema);
+    expect(result.name).toBe("Alice");
+    expect(result.nickname).toBeUndefined();
+  });
+
+  test("fills optional field when user selects Yes", async () => {
+    const schema = Type.Object({
+      name: Type.String(),
+      nickname: Type.Optional(Type.String()),
+    });
+
+    mockInput
+      .mockResolvedValueOnce("Alice") // name
+      .mockResolvedValueOnce("Ali"); // nickname
+    mockSelect.mockResolvedValueOnce(true); // fill nickname
+
+    const result = await sprinkle.FillInStruct(schema);
+    expect(result.name).toBe("Alice");
+    expect(result.nickname).toBe("Ali");
+  });
+});

package/src/Sprinkle/__tests__/extract-message.test.ts

@@ -0,0 +1,60 @@
+import { describe, expect, test } from "bun:test";
+import { Sprinkle, Type } from "../index.js";
+
+describe("ExtractMessage", () => {
+  test("returns title when present", () => {
+    const schema = Type.String({ title: "My Title" });
+    expect(Sprinkle.ExtractMessage(schema, "fallback")).toBe("My Title");
+  });
+
+  test("returns description when title is absent", () => {
+    const schema = Type.String({ description: "My Description" });
+    expect(Sprinkle.ExtractMessage(schema, "fallback")).toBe("My Description");
+  });
+
+  test("prefers title over description", () => {
+    const schema = Type.String({
+      title: "My Title",
+      description: "My Description",
+    });
+    expect(Sprinkle.ExtractMessage(schema, "fallback")).toBe("My Title");
+  });
+
+  test("returns literal const value as string", () => {
+    const schema = Type.Literal("hello");
+    expect(Sprinkle.ExtractMessage(schema, "fallback")).toBe("hello");
+  });
+
+  test("returns literal number const as string", () => {
+    const schema = Type.Literal(42);
+    expect(Sprinkle.ExtractMessage(schema, "fallback")).toBe("42");
+  });
+
+  test("returns type field message for objects with a type field", () => {
+    const schema = Type.Object({
+      type: Type.Literal("blockfrost"),
+      projectId: Type.String(),
+    });
+    expect(Sprinkle.ExtractMessage(schema, "fallback")).toBe("blockfrost");
+  });
+
+  test("returns single field name for single-field objects", () => {
+    const schema = Type.Object({
+      Signature: Type.Object({ key_hash: Type.String() }),
+    });
+    expect(Sprinkle.ExtractMessage(schema, "fallback")).toBe("Signature");
+  });
+
+  test("returns default for multi-field objects without type field", () => {
+    const schema = Type.Object({
+      name: Type.String(),
+      age: Type.BigInt(),
+    });
+    expect(Sprinkle.ExtractMessage(schema, "fallback")).toBe("fallback");
+  });
+
+  test("returns default for plain string without title/description", () => {
+    const schema = Type.String();
+    expect(Sprinkle.ExtractMessage(schema, "fallback")).toBe("fallback");
+  });
+});