@sundaeswap/sprinkles 0.7.0 → 0.8.0

package/README.md

@@ -2,16 +2,41 @@
 
 > **Note:** This is an early release (v0.x). The API may change between minor versions as we refine the library based on community feedback.
 
-A TypeScript library for building interactive CLI menus and TUI applications with TypeBox schema validation. Sprinkles provides a declarative way to create nested menus, handle user input, and manage persistent settings with type safety.
+A TypeScript library for building action-centric CLI applications with TypeBox schema validation. Define your actions once, and Sprinkles exposes them through three facades: an interactive **TUI**, a **CLI** with auto-generated flags and help, and an **MCP** server for AI agent integration.
+
+## Architecture
+
+Sprinkles follows an **action-centric** design. The core building block is an `IAction` — a typed, self-describing unit of work with input/output schemas:
+
+```
+                ┌──────────────┐
+                │   Actions    │  ← define once
+                │  (IAction)   │
+                └──────┬───────┘
+                       │
+          ┌────────────┼────────────┐
+          ▼            ▼            ▼
+     ┌─────────┐ ┌─────────┐ ┌─────────┐
+     │   TUI   │ │   CLI   │ │   MCP   │  ← three facades
+     │ (menu)  │ │ (flags) │ │ (tools) │
+     └─────────┘ └─────────┘ └─────────┘
+```
+
+- **TUI** — Interactive menu-driven interface. Users select actions from a menu, and Sprinkles auto-generates prompts from input schemas.
+- **CLI** — Non-interactive command execution. Actions become subcommands with auto-generated `--flags` from input schemas and structured JSON output.
+- **MCP** — Model Context Protocol server. Actions are exposed as tools that AI agents can discover and call with typed JSON input/output.
+
+`Sprinkle.run()` detects the mode from `process.argv` and dispatches automatically.
 
 ## Features
 
-- **Schema-driven UI**: Define your data structures using TypeBox schemas, and Sprinkles automatically generates interactive prompts
-- **Nested menu support**: Create hierarchical menu structures with submenus
-- **Persistent settings**: Automatic JSON-based settings storage with BigInt support
-- **Type-safe**: Full TypeScript support with type inference from schemas
+- **Action-centric**: Define actions with TypeBox input/output schemas; get TUI, CLI, and MCP for free
+- **Schema-driven UI**: Automatic prompt generation from TypeBox schemas
+- **Multi-profile support**: Multiple named profiles with independent settings
+- **Persistent settings**: JSON-based storage with BigInt support and optional encryption
+- **14 built-in actions**: Profile management, settings, wallet operations, and transaction handling
 - **Cardano integration**: Built-in helpers for Blaze SDK wallet and provider management
-- **Transaction dialogs**: Ready-to-use transaction signing and submission flows
+- **Type-safe**: Full TypeScript support with type inference from schemas
 
 ## Installation
 
@@ -19,241 +44,213 @@ A TypeScript library for building interactive CLI menus and TUI applications wit
 npm install @sundaeswap/sprinkles
 ```
 
+Optional peer dependencies:
+- `@blaze-cardano/sdk` + `@blaze-cardano/query` — for wallet and transaction actions
+- `@modelcontextprotocol/sdk` — for MCP mode
+
 ## Quick Start
 
 ```typescript
-import { Sprinkle, Type } from "sprinkles";
-
-// Define your settings schema
-const AppSettingsSchema = Type.Object({
-  username: Type.String({ title: "Username" }),
-  theme: Type.Union([
-    Type.Literal("dark"),
-    Type.Literal("light")
-  ])
+import { Type } from "@sinclair/typebox";
+import type { TSchema } from "@sinclair/typebox";
+import {
+  Sprinkle,
+  promptAndExecute,
+  getBuiltinActions,
+  NetworkSchema,
+  ProviderSettingsSchema,
+  WalletSettingsSchema,
+} from "@sundaeswap/sprinkles";
+import type { AnyAction, IAction, IMenu } from "@sundaeswap/sprinkles";
+
+// 1. Define your settings schema
+const AppSettings = Type.Object({
+  network: NetworkSchema,
+  provider: ProviderSettingsSchema,
+  wallet: WalletSettingsSchema,
 });
 
-// Create a Sprinkle instance
-const app = await Sprinkle.New(AppSettingsSchema, "./config");
+// 2. Define a custom action
+const greetAction: IAction<
+  { name: string },
+  { greeting: string },
+  TSchema
+> = {
+  name: "greet",
+  description: "Say hello to someone.",
+  category: "app",
+  inputSchema: Type.Object({
+    name: Type.String({ description: "Person to greet" }),
+  }),
+  outputSchema: Type.Object({
+    greeting: Type.String(),
+  }),
+  execute: async (input) => ({
+    greeting: `Hello, ${input.name}!`,
+  }),
+};
 
-// Define your menu
-const mainMenu = {
-  title: "Main Menu",
+// 3. Define a TUI menu
+const menu: IMenu<typeof AppSettings> = {
+  title: "My App",
   items: [
     {
-      title: "Say Hello",
+      title: "Greet someone",
       action: async (sprinkle) => {
-        console.log(`Hello, ${sprinkle.settings.username}!`);
-      }
-    }
-  ]
+        const result = await promptAndExecute(sprinkle, greetAction);
+        if (result.success) {
+          console.log(result.data.greeting);
+        } else if (result.error.code !== "USER_CANCELLED") {
+          console.error("Error:", result.error.message);
+        }
+      },
+    },
+  ],
 };
 
-// Show the menu
-await app.showMenu(mainMenu);
+// 4. Run — mode is detected automatically
+await Sprinkle.run({
+  type: AppSettings,
+  storagePath: `${process.env["HOME"]}/.config/my-app`,
+  menu,
+  actions: [
+    greetAction as unknown as AnyAction<typeof AppSettings>,
+    ...getBuiltinActions<typeof AppSettings>(),
+  ],
+});
 ```
 
-## API Reference
-
-### Core Classes
+This single entry point gives you:
 
-#### `Sprinkle<S extends TSchema>`
+```bash
+# TUI mode (interactive)
+my-app
 
-The main class for managing your CLI application.
+# CLI mode
+my-app greet --name Alice
+my-app list-profiles
+my-app get-settings
 
-##### Constructor
+# MCP mode (AI agent)
+my-app --mcp
 
-```typescript
-constructor(type: S, storagePath: string)
+# Help
+my-app --help
+my-app greet --help
 ```
 
-##### Static Methods
-
-- `Sprinkle.New<S>(type: S, storagePath: string): Promise<Sprinkle<S>>` - Create and initialize a new Sprinkle instance
-- `Sprinkle.GetProvider(network, settings): Provider` - Create a Cardano provider instance
-- `Sprinkle.GetWallet(settings, provider): Promise<Wallet>` - Create a Cardano wallet instance
-- `Sprinkle.GetBlaze(network, providerSettings, walletSettings): Promise<Blaze>` - Create a Blaze SDK instance
-- `Sprinkle.SettingsPath(storagePath: string): string` - Get the settings file path
-
-##### Instance Methods
+## Actions
 
-- `showMenu(menu: IMenu<S>): Promise<void>` - Display a menu and handle user interactions
-- `EditStruct<U>(type: U, current: TExact<U>): Promise<TExact<U>>` - Interactive editor for schema-based structures
-- `FillInStruct<U>(type: U, def?: TExact<U>): Promise<TExact<U>>` - Interactive form to fill in a structure
-- `TxDialog(blaze, tx): Promise<void>` - Display transaction dialog with sign/submit options
-- `saveSettings(): void` - Persist current settings to disk
-- `LoadSettings(type, storagePath): Promise<void>` - Load settings from disk
+### Defining Actions
 
-### Types
-
-#### `IMenu<S>`
-
-Defines a menu structure:
+An action is an object implementing `IAction<TInput, TOutput, TSettings>`:
 
 ```typescript
-interface IMenu<S extends TSchema> {
-  title: string;
-  items: TMenuItem<S>[];
-}
+const myAction: IAction<
+  { url: string; timeout?: number },
+  { status: number },
+  TSchema
+> = {
+  name: "check-health",
+  description: "Check if a service is healthy.",
+  category: "ops",
+  inputSchema: Type.Object({
+    url: Type.String({ description: "Service URL" }),
+    timeout: Type.Optional(Type.Number({ description: "Timeout in ms", default: 5000 })),
+  }),
+  outputSchema: Type.Object({
+    status: Type.Number(),
+  }),
+  execute: async (input, context) => {
+    // context.settings gives you the current profile's settings
+    // context.sprinkle gives you the Sprinkle instance
+    const res = await fetch(input.url, { signal: AbortSignal.timeout(input.timeout ?? 5000) });
+    return { status: res.status };
+  },
+};
 ```
 
-#### `IMenuAction<S>`
-
-Defines a menu action:
+### Built-in Actions
+
+Sprinkles includes 14 built-in actions available via `getBuiltinActions()`:
+
+| Category | Action | Description |
+|----------|--------|-------------|
+| sprinkles | `list-profiles` | List all profiles |
+| sprinkles | `get-profile` | Get profile metadata and settings |
+| sprinkles | `set-profile` | Switch active profile |
+| sprinkles | `create-profile` | Create a new profile |
+| sprinkles | `delete-profile` | Delete a profile |
+| sprinkles | `get-settings` | Get current settings |
+| sprinkles | `update-settings` | Update settings |
+| wallet | `get-wallet-address` | Get wallet address |
+| wallet | `get-wallet-balance` | Get ADA and token balances |
+| wallet | `get-wallet-utxos` | Get UTxO set |
+| wallet | `sign-transaction` | Sign a transaction (hot wallet only) |
+| wallet | `submit-transaction` | Submit a signed transaction |
+| wallet | `sign-and-submit` | Sign and submit in one step |
+| transaction | `decode-transaction` | Decode transaction CBOR |
+
+### Running Actions Programmatically
 
 ```typescript
-interface IMenuAction<S extends TSchema> {
-  title: string;
-  action: (sprinkle: Sprinkle<S>) => Promise<Sprinkle<S> | void>;
-}
-```
-
-#### `TMenuItem<S>`
-
-A menu item can be either an action or a submenu:
+import { executeAction } from "@sundaeswap/sprinkles";
 
-```typescript
-type TMenuItem<S extends TSchema> = IMenuAction<S> | IMenu<S>;
+const result = await executeAction(myAction, { url: "https://example.com" }, context);
+if (result.success) {
+  console.log(result.data.status);
+} else {
+  console.error(result.error.code, result.error.message);
+}
 ```
 
-### Built-in Schemas
+## Built-in Schemas
 
-#### `NetworkSchema`
+Sprinkles exports common Cardano schemas for use in your settings:
 
-Cardano network selection:
+### `NetworkSchema`
 
 ```typescript
-Type.Union([
-  Type.Literal("mainnet"),
-  Type.Literal("preview"),
-  Type.Literal("preprod")
-])
+Type.Union([Type.Literal("mainnet"), Type.Literal("preview"), Type.Literal("preprod")])
 ```
 
-#### `ProviderSettingsSchema`
-
-Cardano provider configuration:
+### `ProviderSettingsSchema`
 
 ```typescript
 Type.Union([
   Type.Object({
     type: Type.Literal("blockfrost"),
-    projectId: Type.String({ minLength: 1, title: "Blockfrost Project ID" })
+    projectId: Type.String({ minLength: 1, title: "Blockfrost Project ID" }),
   }),
   Type.Object({
     type: Type.Literal("maestro"),
-    apiKey: Type.String({ minLength: 1, title: "Maestro API Key" })
-  })
+    apiKey: Type.String({ minLength: 1, title: "Maestro API Key" }),
+  }),
 ])
 ```
 
-#### `WalletSettingsSchema`
-
-Cardano wallet configuration:
+### `WalletSettingsSchema`
 
 ```typescript
 Type.Union([
   Type.Object({
     type: Type.Literal("hot"),
-    privateKey: Type.String({ minLength: 1, title: "Hot Wallet Private Key" })
+    privateKey: Type.String({ minLength: 1, title: "Hot Wallet Private Key", sensitive: true }),
   }),
   Type.Object({
     type: Type.Literal("cold"),
-    address: Type.String({ minLength: 1, title: "Cold Wallet Address" })
-  })
+    address: Type.String({ minLength: 1, title: "Cold Wallet Address" }),
+  }),
 ])
 ```
 
-#### `MultisigScript`
-
-Cardano multisig script schema with support for:
-- Signature verification
-- AllOf (all signatures required)
-- AnyOf (any signature works)
-- AtLeast (m-of-n threshold)
-- Before/After (time-based conditions)
-- Script hash references
-
-## Advanced Usage
-
-### Creating Nested Menus
-
-```typescript
-const menu = {
-  title: "Main Menu",
-  items: [
-    {
-      title: "User Management",
-      items: [
-        {
-          title: "Add User",
-          action: async (sprinkle) => {
-            // Add user logic
-          }
-        },
-        {
-          title: "Remove User",
-          action: async (sprinkle) => {
-            // Remove user logic
-          }
-        }
-      ]
-    }
-  ]
-};
-```
-
-### Modifying Settings from Actions
-
-```typescript
-{
-  title: "Change Username",
-  action: async (sprinkle) => {
-    const newSettings = await sprinkle.EditStruct(
-      Type.Object({ username: Type.String() }),
-      { username: sprinkle.settings.username }
-    );
-    return new Sprinkle(sprinkle.type, sprinkle.storagePath);
-  }
-}
-```
-
-### Working with Cardano Transactions
+## Examples
 
-```typescript
-const blaze = await Sprinkle.GetBlaze(
-  "preprod",
-  providerSettings,
-  walletSettings
-);
-
-// Build your transaction
-const tx = await blaze
-  .newTransaction()
-  .payLovelace(recipientAddress, 5_000_000n)
-  .complete();
-
-// Show transaction dialog
-await app.TxDialog(blaze, tx);
-```
-
-## Settings Persistence
-
-Settings are automatically saved to `{storagePath}/settings.json`. The file format includes:
-
-```json
-{
-  "settings": {
-    "username": "alice",
-    "count": "42n"
-  },
-  "defaults": {
-    "string": "last_entered_value"
-  }
-}
-```
+See [`examples/`](./examples/) for runnable examples:
 
-Note: BigInt values are serialized with an 'n' suffix and automatically parsed on load.
+- **[`demo-app/`](./examples/demo-app/)** — Full-featured testing harness exercising all built-in actions across TUI, CLI, and MCP modes
+- **[`action-example.ts`](./examples/action-example.ts)** — Multi-mode example with a custom action
+- **[`action-in-menu.ts`](./examples/action-in-menu.ts)** — TUI menu integration patterns
 
 ## License
 

package/dist/cjs/Sprinkle/__tests__/builtin-actions.test.js

@@ -49,13 +49,13 @@ async function makeSprinkle(storagePath, profileId = "default", settings = {
   return sprinkle;
 }
 (0, _bunTest.describe)("getBuiltinActions", () => {
-  (0, _bunTest.test)("returns an array of 14 actions", () => {
+  (0, _bunTest.test)("returns an array of 21 actions", () => {
     const actions = (0, _index.getBuiltinActions)();
-    (0, _bunTest.expect)(actions).toHaveLength(14);
+    (0, _bunTest.expect)(actions).toHaveLength(21);
   });
   (0, _bunTest.test)("all actions have a category", () => {
     const actions = (0, _index.getBuiltinActions)();
-    const validCategories = ["sprinkles", "wallet", "transaction"];
+    const validCategories = ["sprinkles", "wallet", "transaction", "utility", "addressbook"];
     for (const action of actions) {
       (0, _bunTest.expect)(validCategories).toContain(action.category);
     }
@@ -83,7 +83,7 @@ async function makeSprinkle(storagePath, profileId = "default", settings = {
     for (const action of actions) {
       sprinkle.registerAction(action);
     }
-    (0, _bunTest.expect)(sprinkle.listActions()).toHaveLength(14);
+    (0, _bunTest.expect)(sprinkle.listActions()).toHaveLength(21);
   });
 });