@sundaeswap/sprinkles 0.6.0 → 0.7.0

package/dist/esm/Sprinkle/actions/runner.js

@@ -0,0 +1,182 @@
+/**
+ * Action runner utilities: input validation, execution, mode detection, and CLI arg parsing.
+ */
+
+import { Value } from "@sinclair/typebox/value";
+import { ActionError } 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(action, rawInput, context) {
+  // 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;
+  try {
+    decodedInput = Value.Decode(action.inputSchema, rawInput);
+  } 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) {
+  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) {
+  const args = {};
+
+  // 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, value) => {
+    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) {
+  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;
+}
+//# sourceMappingURL=runner.js.map

package/dist/esm/Sprinkle/actions/runner.js.map

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

package/dist/esm/Sprinkle/actions/tui-helpers.js

@@ -0,0 +1,91 @@
+/**
+ * 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 { ActionError } from "./types.js";
+import { executeAction } from "./runner.js";
+
+// Import Sprinkle as a type only to avoid circular dependency
+
+// 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(sprinkle, action,
+// 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) {
+  let rawInput;
+  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);
+  } 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,
+    settings: sprinkle.settings
+  };
+  return executeAction(action, rawInput, context);
+}
+//# sourceMappingURL=tui-helpers.js.map

package/dist/esm/Sprinkle/actions/tui-helpers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tui-helpers.js","names":["ActionError","executeAction","UserCancelledError","promptAndExecute","sprinkle","action","defaults","rawInput","FillInStruct","inputSchema","err","success","error","Error","message","String","context","settings"],"sources":["../../../../src/Sprinkle/actions/tui-helpers.ts"],"sourcesContent":["/**\n * TUI helper utilities for integrating the action system with interactive prompts.\n *\n * Provides:\n * - promptAndExecute: gather input via FillInStruct then run executeAction\n *\n * @remarks\n * Functions in this module require a fully initialized Sprinkle instance with\n * terminal access. They are intended for TUI mode only; in CLI or MCP mode use\n * executeAction directly.\n */\n\nimport type { TSchema } from \"@sinclair/typebox\";\nimport { ActionError } from \"./types.js\";\nimport type { IAction, IActionContext, IActionResult } from \"./types.js\";\nimport { executeAction } from \"./runner.js\";\n\n// Import Sprinkle as a type only to avoid circular dependency\nimport type { Sprinkle } from \"../index.js\";\n\n// Import UserCancelledError to detect user cancellations from FillInStruct\nimport { UserCancelledError } from \"../types.js\";\n\n/**\n * Interactively gather input for an action using FillInStruct, then execute\n * the action and return the result.\n *\n * The function:\n * 1. Calls `sprinkle.FillInStruct(action.inputSchema, defaults)` to collect\n *    input from the user via TUI prompts.\n * 2. Builds an `IActionContext` from the sprinkle instance.\n * 3. Calls `executeAction(action, input, context)` and returns the result.\n *\n * If the user cancels the prompt (`UserCancelledError` is thrown), the function\n * returns an `IActionFailure` with code `USER_CANCELLED` rather than throwing.\n *\n * Two separate schema type parameters are used:\n * - `S`  is the concrete settings schema of the `Sprinkle` instance.\n * - `SA` is the settings schema the action was typed against (often `TSchema`).\n *\n * This allows a `Sprinkle<TObject<...>>` to be passed alongside an action\n * typed with the base `TSchema` constraint (the same pattern used by all\n * built-in actions), while still preserving full type safety for TInput/TOutput.\n *\n * @param sprinkle - An initialized Sprinkle instance (TUI mode).\n * @param action   - The action to prompt for and execute.\n * @param defaults - Optional partial defaults pre-filled in the prompt.\n * @returns An `IActionResult` discriminated union (never throws).\n *\n * @example\n * ```ts\n * const result = await promptAndExecute(sprinkle, greetAction);\n * if (result.success) {\n *   console.log(result.data.greeting);\n * } else {\n *   if (result.error.code === \"USER_CANCELLED\") return; // user backed out\n *   console.error(result.error.message);\n * }\n * ```\n */\nexport async function promptAndExecute<\n  TInput,\n  TOutput,\n  S extends TSchema,\n  SA extends TSchema,\n>(\n  sprinkle: Sprinkle<S>,\n  action: IAction<TInput, TOutput, SA>,\n  // defaults is typed as Partial<TInput> -- the static input shape.\n  // Internally it is cast to `never` because FillInStruct expects TExact<U>\n  // which is derived from the inputSchema's TSchema generic, not TInput.\n  defaults?: Partial<TInput>,\n): Promise<IActionResult<TOutput>> {\n  let rawInput: unknown;\n\n  try {\n    // FillInStruct<U> is generic over TSchema; we pass the action's inputSchema\n    // and cast defaults to satisfy the generic bound.\n    rawInput = await sprinkle.FillInStruct(\n      action.inputSchema,\n      defaults as never,\n    );\n  } catch (err) {\n    if (err instanceof UserCancelledError) {\n      return {\n        success: false,\n        error: new ActionError(\n          \"User cancelled the input prompt.\",\n          \"USER_CANCELLED\",\n          err,\n        ),\n      };\n    }\n    // Any other error from FillInStruct is unexpected -- wrap it\n    return {\n      success: false,\n      error: new ActionError(\n        `Prompt failed: ${err instanceof Error ? err.message : String(err)}`,\n        \"PROMPT_ERROR\",\n        err,\n      ),\n    };\n  }\n\n  // Build the context. The action's SA context is satisfied by the concrete\n  // Sprinkle<S> instance via a cast -- the action only accesses sprinkle via\n  // the IActionContext interface which it should treat as opaque when SA = TSchema.\n  const context = {\n    sprinkle: sprinkle as unknown as Sprinkle<SA>,\n    settings: sprinkle.settings as unknown,\n  } as IActionContext<SA>;\n\n  return executeAction(action, rawInput, context);\n}\n"],"mappings":"AAAA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAGA,SAASA,WAAW,QAAQ,YAAY;AAExC,SAASC,aAAa,QAAQ,aAAa;;AAE3C;;AAGA;AACA,SAASC,kBAAkB,QAAQ,aAAa;;AAEhD;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,OAAO,eAAeC,gBAAgBA,CAMpCC,QAAqB,EACrBC,MAAoC;AACpC;AACA;AACA;AACAC,QAA0B,EACO;EACjC,IAAIC,QAAiB;EAErB,IAAI;IACF;IACA;IACAA,QAAQ,GAAG,MAAMH,QAAQ,CAACI,YAAY,CACpCH,MAAM,CAACI,WAAW,EAClBH,QACF,CAAC;EACH,CAAC,CAAC,OAAOI,GAAG,EAAE;IACZ,IAAIA,GAAG,YAAYR,kBAAkB,EAAE;MACrC,OAAO;QACLS,OAAO,EAAE,KAAK;QACdC,KAAK,EAAE,IAAIZ,WAAW,CACpB,kCAAkC,EAClC,gBAAgB,EAChBU,GACF;MACF,CAAC;IACH;IACA;IACA,OAAO;MACLC,OAAO,EAAE,KAAK;MACdC,KAAK,EAAE,IAAIZ,WAAW,CACpB,kBAAkBU,GAAG,YAAYG,KAAK,GAAGH,GAAG,CAACI,OAAO,GAAGC,MAAM,CAACL,GAAG,CAAC,EAAE,EACpE,cAAc,EACdA,GACF;IACF,CAAC;EACH;;EAEA;EACA;EACA;EACA,MAAMM,OAAO,GAAG;IACdZ,QAAQ,EAAEA,QAAmC;IAC7Ca,QAAQ,EAAEb,QAAQ,CAACa;EACrB,CAAuB;EAEvB,OAAOhB,aAAa,CAACI,MAAM,EAAEE,QAAQ,EAAES,OAAO,CAAC;AACjD","ignoreList":[]}

package/dist/esm/Sprinkle/actions/types.js

@@ -0,0 +1,61 @@
+function _defineProperty(e, r, t) { return (r = _toPropertyKey(r)) in e ? Object.defineProperty(e, r, { value: t, enumerable: !0, configurable: !0, writable: !0 }) : e[r] = t, e; }
+function _toPropertyKey(t) { var i = _toPrimitive(t, "string"); return "symbol" == typeof i ? i : i + ""; }
+function _toPrimitive(t, r) { if ("object" != typeof t || !t) return t; var e = t[Symbol.toPrimitive]; if (void 0 !== e) { var i = e.call(t, r || "default"); if ("object" != typeof i) return i; throw new TypeError("@@toPrimitive must return a primitive value."); } return ("string" === r ? String : Number)(t); }
+/**
+ * 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 Sprinkle only as a type to avoid circular dependency
+
+/**
+ * Utility type to extract the static type from a TypeBox schema.
+ */
+
+/**
+ * Context passed to action execute functions.
+ * Provides access to the Sprinkle instance and typed settings shorthand.
+ */
+
+/**
+ * Successful action result.
+ */
+
+/**
+ * Failed action result.
+ */
+
+/**
+ * Discriminated union result type for actions.
+ */
+
+/**
+ * Structured error type for action failures.
+ * Carries a machine-readable code and optional details.
+ */
+export class ActionError extends Error {
+  constructor(message, code, details) {
+    super(message);
+    _defineProperty(this, "code", void 0);
+    _defineProperty(this, "details", void 0);
+    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
+ */
+
+/**
+ * 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
+//# sourceMappingURL=types.js.map

package/dist/esm/Sprinkle/actions/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","names":["ActionError","Error","constructor","message","code","details","_defineProperty","name"],"sources":["../../../../src/Sprinkle/actions/types.ts"],"sourcesContent":["/**\n * Core action types for the action-centric architecture.\n * Actions are pure functions that receive validated typed input\n * and return typed output, with no interactive prompts.\n */\n\nimport type { TSchema, Static } from \"@sinclair/typebox\";\n// Import Sprinkle only as a type to avoid circular dependency\nimport type { Sprinkle } from \"../index.js\";\n\n/**\n * Utility type to extract the static type from a TypeBox schema.\n */\ntype TExact<T> = T extends TSchema ? Static<T> : T;\n\n/**\n * Context passed to action execute functions.\n * Provides access to the Sprinkle instance and typed settings shorthand.\n */\nexport interface IActionContext<S extends TSchema> {\n  /** The full Sprinkle instance (settings, wallet, provider helpers) */\n  sprinkle: Sprinkle<S>;\n  /** Typed shorthand for sprinkle.settings */\n  settings: TExact<S>;\n}\n\n/**\n * Successful action result.\n */\nexport interface IActionSuccess<T> {\n  success: true;\n  data: T;\n}\n\n/**\n * Failed action result.\n */\nexport interface IActionFailure {\n  success: false;\n  error: ActionError;\n}\n\n/**\n * Discriminated union result type for actions.\n */\nexport type IActionResult<T> = IActionSuccess<T> | IActionFailure;\n\n/**\n * Structured error type for action failures.\n * Carries a machine-readable code and optional details.\n */\nexport class ActionError extends Error {\n  code: string;\n  details: unknown;\n\n  constructor(message: string, code: string, details?: unknown) {\n    super(message);\n    this.name = \"ActionError\";\n    this.code = code;\n    this.details = details;\n  }\n}\n\n/**\n * A typed action with input/output schemas and an execute function.\n *\n * @template TInput - The static input type (derived from inputSchema)\n * @template TOutput - The static output type (derived from outputSchema)\n * @template S - The Sprinkle settings schema type\n */\nexport interface IAction<TInput, TOutput, S extends TSchema> {\n  /** Unique kebab-case identifier for this action */\n  name: string;\n  /** Human-readable description of what this action does */\n  description: string;\n  /** Optional grouping category for display/help */\n  category?: string;\n  /** TypeBox schema for validating and decoding input */\n  inputSchema: TSchema;\n  /** TypeBox schema describing the output shape */\n  outputSchema: TSchema;\n  /** Pure execution function -- no interactive prompts allowed */\n  execute: (input: TInput, context: IActionContext<S>) => Promise<TOutput>;\n}\n\n/**\n * Convenience alias for an action with any input/output types.\n * Used for registry storage where exact types are not required.\n */\n// eslint-disable-next-line @typescript-eslint/no-explicit-any\nexport type AnyAction<S extends TSchema> = IAction<any, any, S>;\n"],"mappings":";;;AAAA;AACA;AACA;AACA;AACA;;AAGA;;AAGA;AACA;AACA;;AAGA;AACA;AACA;AACA;;AAQA;AACA;AACA;;AAMA;AACA;AACA;;AAMA;AACA;AACA;;AAGA;AACA;AACA;AACA;AACA,OAAO,MAAMA,WAAW,SAASC,KAAK,CAAC;EAIrCC,WAAWA,CAACC,OAAe,EAAEC,IAAY,EAAEC,OAAiB,EAAE;IAC5D,KAAK,CAACF,OAAO,CAAC;IAACG,eAAA;IAAAA,eAAA;IACf,IAAI,CAACC,IAAI,GAAG,aAAa;IACzB,IAAI,CAACH,IAAI,GAAGA,IAAI;IAChB,IAAI,CAACC,OAAO,GAAGA,OAAO;EACxB;AACF;;AAEA;AACA;AACA;AACA;AACA;AACA;AACA;;AAgBA;AACA;AACA;AACA;AACA","ignoreList":[]}