@sundaeswap/sprinkles 0.6.1 → 0.8.0

package/src/Sprinkle/actions/registry.ts

@@ -0,0 +1,97 @@
+/**
+ * Action registry for storing and retrieving registered actions.
+ */
+
+import type { TSchema } from "@sinclair/typebox";
+import type { AnyAction } from "./types.js";
+
+/** Regex for valid kebab-case action names */
+const KEBAB_CASE_REGEX = /^[a-z][a-z0-9]*(-[a-z0-9]+)*$/;
+
+/**
+ * Registry for managing actions registered on a Sprinkle app.
+ * Enforces name uniqueness and schema validation at registration time.
+ */
+export class ActionRegistry<S extends TSchema> {
+  private actions: Map<string, AnyAction<S>> = new Map();
+
+  /**
+   * Register an action with the registry.
+   *
+   * Validates:
+   * - Name is kebab-case (lowercase letters, digits, hyphens)
+   * - Name is unique within this registry
+   * - inputSchema and outputSchema are present
+   *
+   * @throws Error if validation fails
+   */
+  register(action: AnyAction<S>): void {
+    if (!KEBAB_CASE_REGEX.test(action.name)) {
+      throw new Error(
+        `Invalid action name "${action.name}": must be kebab-case (e.g. "my-action", "get-balance")`,
+      );
+    }
+
+    if (this.actions.has(action.name)) {
+      throw new Error(
+        `Action "${action.name}" is already registered. Action names must be unique.`,
+      );
+    }
+
+    if (!action.inputSchema) {
+      throw new Error(
+        `Action "${action.name}" is missing inputSchema. All actions must define an inputSchema.`,
+      );
+    }
+
+    if (!action.outputSchema) {
+      throw new Error(
+        `Action "${action.name}" is missing outputSchema. All actions must define an outputSchema.`,
+      );
+    }
+
+    this.actions.set(action.name, action);
+  }
+
+  /**
+   * Retrieve an action by name.
+   * @returns The action, or undefined if not registered
+   */
+  get(name: string): AnyAction<S> | undefined {
+    return this.actions.get(name);
+  }
+
+  /**
+   * Check if an action with the given name is registered.
+   */
+  has(name: string): boolean {
+    return this.actions.has(name);
+  }
+
+  /**
+   * List all registered actions.
+   */
+  list(): AnyAction<S>[] {
+    return Array.from(this.actions.values());
+  }
+
+  /**
+   * Group all registered actions by their category.
+   * Actions without a category are placed under "default".
+   */
+  listByCategory(): Map<string, AnyAction<S>[]> {
+    const result = new Map<string, AnyAction<S>[]>();
+
+    for (const action of this.actions.values()) {
+      const category = action.category ?? "default";
+      const bucket = result.get(category);
+      if (bucket) {
+        bucket.push(action);
+      } else {
+        result.set(category, [action]);
+      }
+    }
+
+    return result;
+  }
+}

package/src/Sprinkle/actions/runner.ts

@@ -0,0 +1,200 @@
+/**
+ * Action runner utilities: input validation, execution, mode detection, and CLI arg parsing.
+ */
+
+import { Value } from "@sinclair/typebox/value";
+import type { TSchema } from "@sinclair/typebox";
+import { ActionError } from "./types.js";
+import type { IAction, IActionContext, IActionResult } from "./types.js";
+
+/**
+ * Execute an action with raw (unvalidated) input.
+ *
+ * - Validates rawInput against action.inputSchema using Value.Check
+ * - Applies defaults and transforms via Value.Decode
+ * - Calls action.execute with decoded input
+ * - Wraps all errors in ActionError for consistent error handling
+ *
+ * @returns A discriminated IActionResult -- never throws
+ */
+export async function executeAction<TInput, TOutput, S extends TSchema>(
+  action: IAction<TInput, TOutput, S>,
+  rawInput: unknown,
+  context: IActionContext<S>,
+): Promise<IActionResult<TOutput>> {
+  // First check validity so we can collect all errors at once
+  if (!Value.Check(action.inputSchema, rawInput)) {
+    const errors = Array.from(Value.Errors(action.inputSchema, rawInput)).map(
+      (e) => ({ path: e.path, message: e.message, value: e.value }),
+    );
+    return {
+      success: false,
+      error: new ActionError(
+        `Invalid input for action "${action.name}"`,
+        "VALIDATION_ERROR",
+        errors,
+      ),
+    };
+  }
+
+  // Apply defaults and transforms
+  let decodedInput: TInput;
+  try {
+    decodedInput = Value.Decode(action.inputSchema, rawInput) as TInput;
+  } catch (err) {
+    return {
+      success: false,
+      error: new ActionError(
+        `Failed to decode input for action "${action.name}": ${err instanceof Error ? err.message : String(err)}`,
+        "DECODE_ERROR",
+        err,
+      ),
+    };
+  }
+
+  try {
+    const output = await action.execute(decodedInput, context);
+    return { success: true, data: output };
+  } catch (err) {
+    if (err instanceof ActionError) {
+      return { success: false, error: err };
+    }
+    return {
+      success: false,
+      error: new ActionError(
+        err instanceof Error ? err.message : String(err),
+        "EXECUTION_ERROR",
+        err,
+      ),
+    };
+  }
+}
+
+/**
+ * Detect the intended run mode from process argv.
+ *
+ * - No args or --interactive: "tui"
+ * - --mcp: "mcp"
+ * - --help or -h (with no positional arg): "help"
+ * - First positional arg (not starting with --): "cli"
+ * - Default fallback: "tui"
+ */
+export function detectMode(
+  argv: string[],
+): "tui" | "cli" | "mcp" | "help" {
+  if (argv.length === 0) return "tui";
+
+  // Check for explicit flags first
+  if (argv.includes("--interactive")) return "tui";
+  if (argv.includes("--mcp")) return "mcp";
+
+  // Find first positional arg (not starting with -)
+  const firstPositional = argv.find((arg) => !arg.startsWith("-"));
+  if (firstPositional !== undefined) return "cli";
+
+  // Flag-only invocations
+  if (argv.includes("--help") || argv.includes("-h")) return "help";
+
+  return "tui";
+}
+
+/**
+ * Parse CLI argv into an action name and key-value argument record.
+ *
+ * Expects:
+ * - First positional arg as the action name
+ * - Subsequent --flag value or --flag=value pairs as arguments
+ * - --no-flag for boolean negation
+ * - Values starting with { or [ are parsed as JSON
+ *
+ * Note: This is a preliminary implementation. Complex nested inputs
+ * should be provided as JSON strings (e.g. --input '{"key":"value"}').
+ *
+ * @throws Error if no action name is found in argv
+ */
+export function parseCliArgs(
+  argv: string[],
+): { actionName: string; args: Record<string, unknown> } {
+  const args: Record<string, unknown> = {};
+
+  // Extract action name: first arg that is not a flag
+  const actionName = argv.find((arg) => !arg.startsWith("-"));
+  if (!actionName) {
+    throw new Error(
+      "No action name provided. Usage: <action-name> [--flag value ...]",
+    );
+  }
+
+  // Helper to append a value, supporting repeated flags as arrays
+  const appendValue = (key: string, value: unknown): void => {
+    const existing = args[key];
+    if (existing === undefined) {
+      args[key] = value;
+    } else if (Array.isArray(existing)) {
+      existing.push(value);
+    } else {
+      // Second occurrence of the same flag -- promote to array
+      args[key] = [existing, value];
+    }
+  };
+
+  // Parse flags after the action name
+  const flagArgs = argv.slice(argv.indexOf(actionName) + 1);
+  let i = 0;
+  while (i < flagArgs.length) {
+    const arg = flagArgs[i]!;
+
+    if (arg.startsWith("--no-")) {
+      // Boolean negation: --no-flag => flag: false
+      const key = arg.slice(5);
+      appendValue(key, false);
+      i++;
+      continue;
+    }
+
+    if (arg.startsWith("--")) {
+      const eqIdx = arg.indexOf("=");
+      if (eqIdx !== -1) {
+        // --flag=value syntax
+        const key = arg.slice(2, eqIdx);
+        const rawValue = arg.slice(eqIdx + 1);
+        appendValue(key, parseArgValue(rawValue));
+        i++;
+      } else {
+        // --flag value syntax
+        const key = arg.slice(2);
+        const nextArg = flagArgs[i + 1];
+        if (nextArg !== undefined && !nextArg.startsWith("-")) {
+          appendValue(key, parseArgValue(nextArg));
+          i += 2;
+        } else {
+          // Flag with no value: treat as boolean true
+          appendValue(key, true);
+          i++;
+        }
+      }
+      continue;
+    }
+
+    // Skip non-flag positional args (there should only be the action name)
+    i++;
+  }
+
+  return { actionName, args };
+}
+
+/**
+ * Parse a single CLI argument value.
+ * Detects JSON objects/arrays; otherwise returns the string as-is.
+ */
+function parseArgValue(raw: string): unknown {
+  const trimmed = raw.trim();
+  if (trimmed.startsWith("{") || trimmed.startsWith("[")) {
+    try {
+      return JSON.parse(trimmed);
+    } catch {
+      // Fall through: return as string if JSON parse fails
+    }
+  }
+  return raw;
+}

package/src/Sprinkle/actions/tui-helpers.ts

@@ -0,0 +1,114 @@
+/**
+ * TUI helper utilities for integrating the action system with interactive prompts.
+ *
+ * Provides:
+ * - promptAndExecute: gather input via FillInStruct then run executeAction
+ *
+ * @remarks
+ * Functions in this module require a fully initialized Sprinkle instance with
+ * terminal access. They are intended for TUI mode only; in CLI or MCP mode use
+ * executeAction directly.
+ */
+
+import type { TSchema } from "@sinclair/typebox";
+import { ActionError } from "./types.js";
+import type { IAction, IActionContext, IActionResult } from "./types.js";
+import { executeAction } from "./runner.js";
+
+// Import Sprinkle as a type only to avoid circular dependency
+import type { Sprinkle } from "../index.js";
+
+// Import UserCancelledError to detect user cancellations from FillInStruct
+import { UserCancelledError } from "../types.js";
+
+/**
+ * Interactively gather input for an action using FillInStruct, then execute
+ * the action and return the result.
+ *
+ * The function:
+ * 1. Calls `sprinkle.FillInStruct(action.inputSchema, defaults)` to collect
+ *    input from the user via TUI prompts.
+ * 2. Builds an `IActionContext` from the sprinkle instance.
+ * 3. Calls `executeAction(action, input, context)` and returns the result.
+ *
+ * If the user cancels the prompt (`UserCancelledError` is thrown), the function
+ * returns an `IActionFailure` with code `USER_CANCELLED` rather than throwing.
+ *
+ * Two separate schema type parameters are used:
+ * - `S`  is the concrete settings schema of the `Sprinkle` instance.
+ * - `SA` is the settings schema the action was typed against (often `TSchema`).
+ *
+ * This allows a `Sprinkle<TObject<...>>` to be passed alongside an action
+ * typed with the base `TSchema` constraint (the same pattern used by all
+ * built-in actions), while still preserving full type safety for TInput/TOutput.
+ *
+ * @param sprinkle - An initialized Sprinkle instance (TUI mode).
+ * @param action   - The action to prompt for and execute.
+ * @param defaults - Optional partial defaults pre-filled in the prompt.
+ * @returns An `IActionResult` discriminated union (never throws).
+ *
+ * @example
+ * ```ts
+ * const result = await promptAndExecute(sprinkle, greetAction);
+ * if (result.success) {
+ *   console.log(result.data.greeting);
+ * } else {
+ *   if (result.error.code === "USER_CANCELLED") return; // user backed out
+ *   console.error(result.error.message);
+ * }
+ * ```
+ */
+export async function promptAndExecute<
+  TInput,
+  TOutput,
+  S extends TSchema,
+  SA extends TSchema,
+>(
+  sprinkle: Sprinkle<S>,
+  action: IAction<TInput, TOutput, SA>,
+  // defaults is typed as Partial<TInput> -- the static input shape.
+  // Internally it is cast to `never` because FillInStruct expects TExact<U>
+  // which is derived from the inputSchema's TSchema generic, not TInput.
+  defaults?: Partial<TInput>,
+): Promise<IActionResult<TOutput>> {
+  let rawInput: unknown;
+
+  try {
+    // FillInStruct<U> is generic over TSchema; we pass the action's inputSchema
+    // and cast defaults to satisfy the generic bound.
+    rawInput = await sprinkle.FillInStruct(
+      action.inputSchema,
+      defaults as never,
+    );
+  } catch (err) {
+    if (err instanceof UserCancelledError) {
+      return {
+        success: false,
+        error: new ActionError(
+          "User cancelled the input prompt.",
+          "USER_CANCELLED",
+          err,
+        ),
+      };
+    }
+    // Any other error from FillInStruct is unexpected -- wrap it
+    return {
+      success: false,
+      error: new ActionError(
+        `Prompt failed: ${err instanceof Error ? err.message : String(err)}`,
+        "PROMPT_ERROR",
+        err,
+      ),
+    };
+  }
+
+  // Build the context. The action's SA context is satisfied by the concrete
+  // Sprinkle<S> instance via a cast -- the action only accesses sprinkle via
+  // the IActionContext interface which it should treat as opaque when SA = TSchema.
+  const context = {
+    sprinkle: sprinkle as unknown as Sprinkle<SA>,
+    settings: sprinkle.settings as unknown,
+  } as IActionContext<SA>;
+
+  return executeAction(action, rawInput, context);
+}

package/src/Sprinkle/actions/types.ts

@@ -0,0 +1,91 @@
+/**
+ * Core action types for the action-centric architecture.
+ * Actions are pure functions that receive validated typed input
+ * and return typed output, with no interactive prompts.
+ */
+
+import type { TSchema, Static } from "@sinclair/typebox";
+// Import Sprinkle only as a type to avoid circular dependency
+import type { Sprinkle } from "../index.js";
+
+/**
+ * Utility type to extract the static type from a TypeBox schema.
+ */
+type TExact<T> = T extends TSchema ? Static<T> : T;
+
+/**
+ * Context passed to action execute functions.
+ * Provides access to the Sprinkle instance and typed settings shorthand.
+ */
+export interface IActionContext<S extends TSchema> {
+  /** The full Sprinkle instance (settings, wallet, provider helpers) */
+  sprinkle: Sprinkle<S>;
+  /** Typed shorthand for sprinkle.settings */
+  settings: TExact<S>;
+}
+
+/**
+ * Successful action result.
+ */
+export interface IActionSuccess<T> {
+  success: true;
+  data: T;
+}
+
+/**
+ * Failed action result.
+ */
+export interface IActionFailure {
+  success: false;
+  error: ActionError;
+}
+
+/**
+ * Discriminated union result type for actions.
+ */
+export type IActionResult<T> = IActionSuccess<T> | IActionFailure;
+
+/**
+ * Structured error type for action failures.
+ * Carries a machine-readable code and optional details.
+ */
+export class ActionError extends Error {
+  code: string;
+  details: unknown;
+
+  constructor(message: string, code: string, details?: unknown) {
+    super(message);
+    this.name = "ActionError";
+    this.code = code;
+    this.details = details;
+  }
+}
+
+/**
+ * A typed action with input/output schemas and an execute function.
+ *
+ * @template TInput - The static input type (derived from inputSchema)
+ * @template TOutput - The static output type (derived from outputSchema)
+ * @template S - The Sprinkle settings schema type
+ */
+export interface IAction<TInput, TOutput, S extends TSchema> {
+  /** Unique kebab-case identifier for this action */
+  name: string;
+  /** Human-readable description of what this action does */
+  description: string;
+  /** Optional grouping category for display/help */
+  category?: string;
+  /** TypeBox schema for validating and decoding input */
+  inputSchema: TSchema;
+  /** TypeBox schema describing the output shape */
+  outputSchema: TSchema;
+  /** Pure execution function -- no interactive prompts allowed */
+  execute: (input: TInput, context: IActionContext<S>) => Promise<TOutput>;
+}
+
+/**
+ * Convenience alias for an action with any input/output types.
+ * Used for registry storage where exact types are not required.
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type AnyAction<S extends TSchema> = IAction<any, any, S>;