@sundaeswap/sprinkles 0.6.1 → 0.8.0

package/src/Sprinkle/actions/cli-adapter.ts

@@ -0,0 +1,446 @@
+/**
+ * CLI adapter for Sprinkles actions.
+ *
+ * Provides:
+ * - Case-conversion helpers (camelToKebab / kebabToCamel)
+ * - Schema-driven type coercion (coerceValue / parseArgvWithSchema)
+ * - Help text generation (generateActionHelp / generateAppHelp)
+ * - CLI orchestrator (runCli)
+ */
+
+import type { TSchema } from "@sinclair/typebox";
+import { bigIntReplacer } from "../encryption.js";
+import {
+  isArray,
+  isBigInt,
+  isBoolean,
+  isInteger,
+  isNumber,
+  isObject,
+  isString,
+  isUnion,
+  hasDefault,
+  getDefault,
+} from "../type-guards.js";
+import type { AnyAction, IActionContext } from "./types.js";
+import { executeAction } from "./runner.js";
+
+// Re-import Sprinkle as a type only to avoid circular deps
+import type { Sprinkle } from "../index.js";
+
+// ---------------------------------------------------------------------------
+// Case conversion helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Convert a camelCase string to kebab-case.
+ * Examples:
+ *   "myFlagName" -> "my-flag-name"
+ *   "getBalance" -> "get-balance"
+ *   "URL"        -> "u-r-l"  (each uppercase letter gets a dash)
+ */
+export function camelToKebab(str: string): string {
+  if (!str) return str;
+  return str
+    .replace(/([A-Z])/g, (match) => `-${match.toLowerCase()}`)
+    .replace(/^-/, "");
+}
+
+/**
+ * Convert a kebab-case string to camelCase.
+ * Examples:
+ *   "my-flag-name" -> "myFlagName"
+ *   "get-balance"  -> "getBalance"
+ */
+export function kebabToCamel(str: string): string {
+  if (!str) return str;
+  return str.replace(/-([a-z0-9])/g, (_, char: string) => char.toUpperCase());
+}
+
+// ---------------------------------------------------------------------------
+// Schema-driven type coercion
+// ---------------------------------------------------------------------------
+
+/**
+ * Coerce a raw CLI string value to the type expected by a TypeBox schema.
+ *
+ * Handles:
+ * - Number / Integer: parseFloat / parseInt
+ * - Boolean: "true"/"false" strings, or passthrough if already boolean
+ * - BigInt: BigInt() constructor
+ * - Array: already-array passthrough; single value wrapped in array
+ * - Object: JSON string parse
+ * - String: passthrough
+ * - Optional: unwrap and recurse on inner schema
+ * - Union: passthrough (caller should supply JSON; no schema-level heuristics)
+ */
+export function coerceValue(raw: unknown, schema: TSchema): unknown {
+  // Note: TypeBox Optional<T> adds an [OptionalKind] marker but does not
+  // change the schema Kind. The guards below work correctly on Optional types.
+
+  // If the raw value is null or undefined, return as-is
+  if (raw === null || raw === undefined) return raw;
+
+  if (isNumber(schema)) {
+    if (typeof raw === "number") return raw;
+    if (typeof raw === "string") {
+      const n = parseFloat(raw);
+      return isNaN(n) ? raw : n;
+    }
+    return raw;
+  }
+
+  if (isInteger(schema)) {
+    if (typeof raw === "number") return Math.trunc(raw);
+    if (typeof raw === "string") {
+      const n = parseInt(raw, 10);
+      return isNaN(n) ? raw : n;
+    }
+    return raw;
+  }
+
+  if (isBoolean(schema)) {
+    if (typeof raw === "boolean") return raw;
+    if (raw === "true") return true;
+    if (raw === "false") return false;
+    return raw;
+  }
+
+  if (isBigInt(schema)) {
+    if (typeof raw === "bigint") return raw;
+    if (typeof raw === "string" || typeof raw === "number") {
+      try {
+        return BigInt(raw);
+      } catch {
+        return raw;
+      }
+    }
+    return raw;
+  }
+
+  if (isArray(schema)) {
+    const itemSchema = (schema as { items?: TSchema }).items;
+    if (Array.isArray(raw)) {
+      if (itemSchema) {
+        return raw.map((item) => coerceValue(item, itemSchema));
+      }
+      return raw;
+    }
+    // Single value: wrap in array
+    const singleValue = itemSchema ? coerceValue(raw, itemSchema) : raw;
+    return [singleValue];
+  }
+
+  if (isObject(schema)) {
+    let obj = raw;
+    // If it's a JSON string, parse it
+    if (typeof raw === "string") {
+      const trimmed = raw.trim();
+      if (trimmed.startsWith("{")) {
+        try {
+          obj = JSON.parse(trimmed);
+        } catch {
+          return raw;
+        }
+      } else {
+        return raw;
+      }
+    }
+    // Recurse into properties to coerce nested values
+    if (typeof obj === "object" && obj !== null && !Array.isArray(obj)) {
+      const props = schema.properties as Record<string, TSchema> | undefined;
+      if (props) {
+        const result: Record<string, unknown> = { ...(obj as Record<string, unknown>) };
+        for (const [key, propSchema] of Object.entries(props)) {
+          if (key in result) {
+            result[key] = coerceValue(result[key], propSchema);
+          }
+        }
+        return result;
+      }
+    }
+    return obj;
+  }
+
+  if (isString(schema)) {
+    if (typeof raw === "string") return raw;
+    return String(raw);
+  }
+
+  // Union / unknown / other: return as-is (caller provides JSON)
+  return raw;
+}
+
+/**
+ * Walk a TypeBox object schema and coerce each property value from raw CLI args.
+ *
+ * - Handles kebab-case -> camelCase property name mapping
+ * - Applies coerceValue for each property
+ * - Applies TypeBox defaults for omitted optional fields
+ *
+ * @param rawArgs  - Key/value record from parseCliArgs (keys may be kebab-case)
+ * @param schema   - A TypeBox TObject schema
+ * @returns        A new record with coerced values
+ */
+export function parseArgvWithSchema(
+  rawArgs: Record<string, unknown>,
+  schema: TSchema,
+): Record<string, unknown> {
+  if (!isObject(schema)) {
+    // Non-object schema: return args as-is (best-effort)
+    return rawArgs;
+  }
+
+  const result: Record<string, unknown> = {};
+  const properties = schema.properties as Record<string, TSchema>;
+
+  for (const [propName, propSchema] of Object.entries(properties)) {
+    // Look up both camelCase and kebab-case versions in rawArgs
+    const kebabName = camelToKebab(propName);
+
+    let rawValue: unknown = undefined;
+    if (propName in rawArgs) {
+      rawValue = rawArgs[propName];
+    } else if (kebabName !== propName && kebabName in rawArgs) {
+      rawValue = rawArgs[kebabName];
+    }
+
+    if (rawValue === undefined) {
+      // Apply default if defined on schema
+      if (hasDefault(propSchema)) {
+        result[propName] = getDefault(propSchema);
+      }
+      // Else omit: Value.Check will handle required/optional enforcement
+      continue;
+    }
+
+    result[propName] = coerceValue(rawValue, propSchema);
+  }
+
+  return result;
+}
+
+// ---------------------------------------------------------------------------
+// Help text generation
+// ---------------------------------------------------------------------------
+
+/**
+ * Describe a single TypeBox schema in a human-readable CLI type label.
+ */
+function describeType(schema: TSchema): string {
+  // Note: isOptional() only checks the OptionalKind marker; the other guards
+  // still work correctly on Optional-wrapped schemas.
+  if (isString(schema)) return "<string>";
+  if (isNumber(schema)) return "<number>";
+  if (isInteger(schema)) return "<integer>";
+  if (isBoolean(schema)) return "<boolean>";
+  if (isBigInt(schema)) return "<bigint>";
+  if (isArray(schema)) {
+    const itemSchema = (schema as { items?: TSchema }).items;
+    const itemType = itemSchema ? describeType(itemSchema) : "<value>";
+    return `${itemType}... (repeatable)`;
+  }
+  if (isObject(schema)) return "<json>";
+  if (isUnion(schema)) return "<json>";
+  return "<value>";
+}
+
+/**
+ * Generate action-specific help text.
+ *
+ * Format:
+ * ```
+ * Usage: <appName> <action-name> [options]
+ *
+ * Description
+ *
+ * Options:
+ *   --flag-name <type>  Description  [default: x]  (required/optional)
+ *   ...
+ * ```
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function generateActionHelp(
+  action: AnyAction<any>,
+  appName?: string,
+): string {
+  const app = appName ?? "app";
+  const lines: string[] = [
+    `Usage: ${app} ${action.name} [options]`,
+    "",
+    action.description,
+    "",
+    "Options:",
+  ];
+
+  const schema = action.inputSchema;
+  if (isObject(schema)) {
+    const properties = schema.properties as Record<string, TSchema>;
+    const required = (schema.required as string[] | undefined) ?? [];
+
+    for (const [propName, propSchema] of Object.entries(properties)) {
+      const flagName = camelToKebab(propName);
+      const typeLabel = describeType(propSchema);
+      const isReq = required.includes(propName);
+      const defaultVal = hasDefault(propSchema) ? getDefault(propSchema) : undefined;
+      const description = (propSchema as { description?: string }).description ?? "";
+
+      const requiredLabel = isReq ? "(required)" : "(optional)";
+      const defaultLabel =
+        defaultVal !== undefined ? `  [default: ${String(defaultVal)}]` : "";
+
+      const descPart = description ? `  ${description}` : "";
+      lines.push(
+        `  --${flagName} ${typeLabel}${descPart}${defaultLabel}  ${requiredLabel}`,
+      );
+    }
+  }
+
+  lines.push("");
+  lines.push("  --help  Show this help message");
+
+  return lines.join("\n");
+}
+
+/**
+ * Generate application-level help listing all registered actions.
+ *
+ * Format:
+ * ```
+ * Usage: <appName> <action> [options]
+ *
+ * Available actions:
+ *
+ *   category:
+ *     action-name  Description
+ *
+ * Global options:
+ *   --help          Show this help message
+ *   --profile <n>   Use profile by name
+ * ```
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function generateAppHelp(
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  actions: AnyAction<any>[],
+  appName?: string,
+): string {
+  const app = appName ?? "app";
+  const lines: string[] = [`Usage: ${app} <action> [options]`, ""];
+
+  if (actions.length === 0) {
+    lines.push("No actions registered.");
+  } else {
+    lines.push("Available actions:");
+
+    // Group by category
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const byCategory = new Map<string, AnyAction<any>[]>();
+    for (const action of actions) {
+      const cat = action.category ?? "default";
+      const bucket = byCategory.get(cat);
+      if (bucket) {
+        bucket.push(action);
+      } else {
+        byCategory.set(cat, [action]);
+      }
+    }
+
+    for (const [category, categoryActions] of byCategory) {
+      if (category !== "default") {
+        lines.push("");
+        lines.push(`  ${category}:`);
+      }
+      for (const action of categoryActions) {
+        lines.push(`  ${action.name.padEnd(30)} ${action.description}`);
+      }
+    }
+  }
+
+  lines.push("");
+  lines.push("Global options:");
+  lines.push("  --help         Show this help message");
+  lines.push("  --profile <n>  Use profile by name");
+
+  return lines.join("\n");
+}
+
+// ---------------------------------------------------------------------------
+// CLI orchestrator
+// ---------------------------------------------------------------------------
+
+/**
+ * Run an action from CLI arguments, writing JSON output to stdout/stderr.
+ *
+ * Handles:
+ * - Action not found: JSON error to stderr, process.exit(1)
+ * - Action help (`--help` in rawArgs): prints action help to stdout
+ * - Schema-driven argument coercion via parseArgvWithSchema
+ * - Success: `{"success":true,"data":...}` JSON to stdout
+ * - Failure: `{"success":false,"error":...}` JSON to stderr, process.exit(1)
+ *
+ * @param sprinkle   - Fully-initialized Sprinkle instance
+ * @param actionName - The action to invoke
+ * @param rawArgs    - Pre-parsed key/value args from parseCliArgs (profile already removed)
+ * @param context    - The action execution context
+ * @param appName    - Optional app name for help text
+ */
+export async function runCli<S extends TSchema>(
+  sprinkle: Sprinkle<S>,
+  actionName: string,
+  rawArgs: Record<string, unknown>,
+  context: IActionContext<S>,
+  appName?: string,
+): Promise<void> {
+  const action = sprinkle.getAction(actionName);
+
+  if (!action) {
+    const available = sprinkle
+      .listActions()
+      .map((a) => a.name)
+      .join(", ");
+    const errorOutput = JSON.stringify(
+      {
+        success: false,
+        error: {
+          code: "ACTION_NOT_FOUND",
+          message: `Action "${actionName}" not found. Available actions: ${available || "(none)"}`,
+        },
+      },
+      bigIntReplacer,
+    );
+    console.error(errorOutput);
+    process.exit(1);
+  }
+
+  // Handle --help flag for action-specific help
+  if (rawArgs["help"] === true) {
+    console.log(generateActionHelp(action, appName));
+    return;
+  }
+
+  // Coerce raw string args using the action's input schema
+  const coercedInput = parseArgvWithSchema(rawArgs, action.inputSchema);
+
+  // Execute and output result
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const result = await executeAction(action as any, coercedInput, context as any);
+
+  if (result.success) {
+    console.log(JSON.stringify({ success: true, data: result.data }, bigIntReplacer));
+  } else {
+    const errorOutput = JSON.stringify(
+      {
+        success: false,
+        error: {
+          code: result.error.code,
+          message: result.error.message,
+          details: result.error.details,
+        },
+      },
+      bigIntReplacer,
+    );
+    console.error(errorOutput);
+    process.exit(1);
+  }
+}

package/src/Sprinkle/actions/index.ts

@@ -0,0 +1,33 @@
+/**
+ * Barrel export for the actions subsystem.
+ */
+
+export type { IAction, IActionContext, IActionResult, IActionSuccess, IActionFailure, AnyAction } from "./types.js";
+export { ActionError } from "./types.js";
+
+export { ActionRegistry } from "./registry.js";
+
+export { executeAction, detectMode, parseCliArgs } from "./runner.js";
+
+export {
+  camelToKebab,
+  kebabToCamel,
+  coerceValue,
+  parseArgvWithSchema,
+  generateActionHelp,
+  generateAppHelp,
+  runCli,
+} from "./cli-adapter.js";
+
+export {
+  typeboxToJsonSchema,
+  coerceMcpInput,
+  getMcpSdk,
+  createMcpServer,
+  runMcp,
+} from "./mcp-adapter.js";
+
+export { getBuiltinActions, toNativeScript, completeWithScripts } from "./builtin/index.js";
+export type { NativeScriptInput } from "./builtin/index.js";
+
+export { promptAndExecute } from "./tui-helpers.js";