@next-vibe/checker 1.0.11 → 1.0.13

package/src/app/api/[locale]/system/unified-interface/shared/types/enums.ts

@@ -0,0 +1,382 @@
+/**
+ * Core Enums for Endpoint Types System
+ *
+ * All fundamental enums used throughout the endpoint types system.
+ * These are the building blocks for type-safe endpoint definitions.
+ *
+ * This is the single source of truth for all enums - consolidated from multiple files.
+ */
+
+/**
+ * Interface contexts where endpoints are consumed
+ * These are the 5+ core interfaces that every endpoint must support
+ */
+export enum InterfaceContext {
+  /** Web UI forms and components */
+  WEB_UI = "web_ui",
+  /** Command line interface */
+  CLI = "cli",
+  /** AI tool function calls */
+  AI_TOOLS = "ai_tools",
+  /** Chat confirmation interface for AI tool calls with editable forms */
+  CHAT_CONFIRMATION = "chat_confirmation",
+  /** Composable pages using EndpointPage */
+  COMPOSABLE_PAGES = "composable_pages",
+  /** Email interface */
+  EMAIL = "email",
+  /** Export interface */
+  EXPORT = "export",
+}
+
+/**
+ * HTTP Methods
+ */
+export enum Methods {
+  GET = "GET",
+  POST = "POST",
+  PUT = "PUT",
+  PATCH = "PATCH",
+  DELETE = "DELETE",
+}
+
+/**
+ * All HTTP methods as array
+ */
+export const ALL_METHODS = [
+  Methods.GET,
+  Methods.POST,
+  Methods.PUT,
+  Methods.PATCH,
+  Methods.DELETE,
+] as const;
+
+/**
+ * Field usage enum for type inference
+ */
+export enum FieldUsage {
+  RequestData = "request-data",
+  RequestUrlParams = "request-url-params",
+  Response = "response",
+}
+
+/**
+ * Cache strategy options
+ */
+export enum CacheStrategy {
+  None = "none",
+  Local = "local",
+  Persistent = "persistent",
+}
+
+/**
+ * Widget types for definition-driven UI components
+ * Each widget type enforces specific props and behavior
+ */
+export enum WidgetType {
+  // Form widgets
+  FORM_FIELD = "form_field",
+  FORM_GROUP = "form_group",
+  FORM_SECTION = "form_section",
+
+  // Data display widgets
+  DATA_TABLE = "data_table",
+  DATA_CARD = "data_card",
+  DATA_CARDS = "data_cards",
+  DATA_LIST = "data_list",
+  DATA_GRID = "data_grid",
+  GROUPED_LIST = "grouped_list",
+  CODE_QUALITY_LIST = "code_quality_list",
+  CODE_QUALITY_SUMMARY = "code_quality_summary",
+  CODE_QUALITY_FILES = "code_quality_files",
+  METADATA_CARD = "metadata_card",
+
+  // Layout widgets
+  CONTAINER = "container",
+  SECTION = "section",
+  TABS = "tabs",
+  ACCORDION = "accordion",
+
+  // Content widgets
+  TITLE = "title",
+  TEXT = "text",
+  BADGE = "badge",
+  AVATAR = "avatar",
+  MARKDOWN = "markdown",
+  MARKDOWN_EDITOR = "markdown_editor",
+  LINK = "link",
+  LINK_CARD = "link_card",
+  LINK_LIST = "link_list",
+
+  // Specialized content widgets
+  FILE_PATH = "file_path",
+  LINE_NUMBER = "line_number",
+  COLUMN_NUMBER = "column_number",
+  CODE_RULE = "code_rule",
+  CODE_OUTPUT = "code_output",
+  SEVERITY_BADGE = "severity_badge",
+  MESSAGE_TEXT = "message_text",
+  ISSUE_CARD = "issue_card",
+  CREDIT_TRANSACTION_CARD = "credit_transaction_card",
+  CREDIT_TRANSACTION_LIST = "credit_transaction_list",
+  PAGINATION = "pagination",
+
+  // Interactive widgets
+  BUTTON = "button",
+  BUTTON_GROUP = "button_group",
+  ACTION_BAR = "action_bar",
+  PAGINATION_INFO = "pagination_info",
+  ACTION_LIST = "action_list",
+
+  // Stats widgets
+  STAT = "stat", // Simple stat display: number + label from field definition
+  METRIC_CARD = "metric_card",
+  STATS_GRID = "stats_grid",
+  CHART = "chart",
+  PROGRESS = "progress",
+
+  // Status widgets
+  LOADING = "loading",
+  ERROR = "error",
+  EMPTY_STATE = "empty_state",
+  STATUS_INDICATOR = "status_indicator",
+  ALERT = "alert",
+  FORM_ALERT = "form_alert",
+
+  // Interactive action widgets
+  SUBMIT_BUTTON = "submit_button",
+
+  // Form feedback widgets
+  PASSWORD_STRENGTH = "password_strength",
+
+  // Custom widgets
+  CUSTOM = "custom",
+}
+
+/**
+ * Field data types that map to appropriate UI components across all contexts
+ * These are inferred from Zod schemas and automatically generate context-specific UI
+ */
+export enum FieldDataType {
+  // Input field types
+  TEXT = "text",
+  EMAIL = "email",
+  PHONE = "phone",
+  URL = "url",
+  PASSWORD = "password",
+  NUMBER = "number",
+  INT = "int",
+  BOOLEAN = "boolean",
+  DATE = "date",
+  DATETIME = "datetime",
+  TIME = "time",
+  TEXTAREA = "textarea",
+  SELECT = "select",
+  MULTISELECT = "multiselect",
+  FILE = "file",
+  UUID = "uuid",
+  JSON = "json",
+
+  // Advanced input types for data-driven UI
+  DATE_RANGE = "date_range",
+  TIME_RANGE = "time_range",
+  TIMEZONE = "timezone",
+  CURRENCY_SELECT = "currency_select",
+  LANGUAGE_SELECT = "language_select",
+  COUNTRY_SELECT = "country_select",
+  COLOR = "color",
+  ICON = "icon",
+  SLIDER = "slider",
+  TAGS = "tags",
+  TEXT_ARRAY = "text_array",
+  FILTER_PILLS = "filter_pills",
+
+  // Complex data types
+  ARRAY = "array",
+  OBJECT = "object",
+
+  // Response display types
+  BADGE = "badge",
+  AVATAR = "avatar",
+  LINK = "link",
+  CURRENCY = "currency",
+  PERCENTAGE = "percentage",
+  STATUS = "status",
+  PROGRESS = "progress",
+  RATING = "rating",
+  IMAGE = "image",
+  CODE = "code",
+  MARKDOWN = "markdown",
+}
+
+/**
+ * Action types for interactive elements
+ */
+export enum ActionType {
+  // UI Actions
+  TOAST = "toast",
+  NOTIFICATION = "notification",
+  ALERT = "alert",
+  MODAL = "modal",
+  DRAWER = "drawer",
+
+  // Navigation Actions
+  ROUTER_PUSH = "router_push",
+  ROUTER_REPLACE = "router_replace",
+  ROUTER_BACK = "router_back",
+  REDIRECT = "redirect",
+
+  // Data Actions
+  REFETCH = "refetch",
+  INVALIDATE_CACHE = "invalidate_cache",
+  UPDATE_CACHE = "update_cache",
+  CLEAR_CACHE = "clear_cache",
+
+  // Form Actions
+  RESET_FORM = "reset_form",
+  CLEAR_FORM = "clear_form",
+  SET_FORM_VALUES = "set_form_values",
+  FOCUS_FIELD = "focus_field",
+
+  // State Actions
+  SET_STATE = "set_state",
+  TOGGLE_STATE = "toggle_state",
+  UPDATE_STATE = "update_state",
+
+  // External Actions
+  API_CALL = "api_call",
+  WEBHOOK = "webhook",
+  EMAIL = "email",
+  DOWNLOAD = "download",
+  COPY_TO_CLIPBOARD = "copy_to_clipboard",
+
+  // Custom Actions
+  CUSTOM = "custom",
+}
+
+/**
+ * Layout types for containers and forms
+ */
+export enum LayoutType {
+  VERTICAL = "vertical",
+  HORIZONTAL = "horizontal",
+  GRID = "grid",
+  FLEX = "flex",
+  STACKED = "stacked",
+  FULL_WIDTH = "full_width",
+  COLLAPSIBLE = "collapsible",
+  GRID_2_COLUMNS = "grid_2_columns",
+  GRID_ITEM = "grid_item",
+}
+
+/**
+ * Component variants for theming
+ */
+export enum ComponentVariant {
+  DEFAULT = "default",
+  PRIMARY = "primary",
+  SECONDARY = "secondary",
+  SUCCESS = "success",
+  WARNING = "warning",
+  ERROR = "error",
+  DESTRUCTIVE = "destructive",
+  GHOST = "ghost",
+  OUTLINE = "outline",
+  SEVERITY = "severity",
+  TYPE = "type",
+}
+
+/**
+ * Component sizes
+ */
+export enum ComponentSize {
+  SM = "sm",
+  MD = "md",
+  LG = "lg",
+  XL = "xl",
+}
+
+/**
+ * Spacing sizes for consistent design
+ */
+export enum SpacingSize {
+  COMPACT = "compact",
+  NORMAL = "normal",
+  RELAXED = "relaxed",
+}
+
+/**
+ * Text alignment options
+ */
+export enum TextAlign {
+  LEFT = "left",
+  CENTER = "center",
+  RIGHT = "right",
+  JUSTIFY = "justify",
+}
+
+/**
+ * Chart types for data visualization
+ */
+export enum ChartType {
+  LINE = "line",
+  BAR = "bar",
+  PIE = "pie",
+  AREA = "area",
+  SCATTER = "scatter",
+  DONUT = "donut",
+  HISTOGRAM = "histogram",
+}
+
+/**
+ * Action execution timing
+ */
+export enum ActionTiming {
+  IMMEDIATE = "immediate",
+  DEBOUNCED = "debounced",
+  THROTTLED = "throttled",
+  DELAYED = "delayed",
+}
+
+/**
+ * Validation modes for form fields
+ */
+export enum ValidationMode {
+  ON_CHANGE = "onChange",
+  ON_BLUR = "onBlur",
+  ON_SUBMIT = "onSubmit",
+  ON_TOUCHED = "onTouched",
+}
+
+/**
+ * Table density options
+ */
+export enum TableDensity {
+  COMPACT = "compact",
+  NORMAL = "normal",
+  COMFORTABLE = "comfortable",
+}
+
+/**
+ * Card layout types
+ */
+export enum CardLayout {
+  COMPACT = "compact",
+  DETAILED = "detailed",
+  MEDIA = "media",
+  CUSTOM = "custom",
+}
+
+/**
+ * Hook-specific error types for toast notifications
+ */
+export enum EndpointErrorTypes {
+  VALIDATION_FAILED = "validation_failed",
+  NETWORK_ERROR = "network_error",
+  UNAUTHORIZED = "unauthorized",
+  FORBIDDEN = "forbidden",
+  NOT_FOUND = "not_found",
+  SERVER_ERROR = "server_error",
+  UNKNOWN_ERROR = "unknown_error",
+  UNSAVED_CHANGES = "unsaved_changes",
+  CONFLICT = "conflict",
+}

package/src/app/api/[locale]/system/unified-interface/shared/types/platform.ts

@@ -0,0 +1,34 @@
+/**
+ * Platform identifier
+ * Used to distinguish between different clients accessing the API or directly calling the route
+ */
+export enum Platform {
+  /** Local CLI running from within a next-vibe project */
+  CLI = "cli",
+  /** CLI running from npm package (installed globally or as dependency) */
+  CLI_PACKAGE = "cli-package",
+  /** AI tool execution */
+  AI = "ai",
+  /** MCP (Model Context Protocol) execution */
+  MCP = "mcp",
+  /** tRPC API calls */
+  TRPC = "trpc",
+  /** Next.js page context */
+  NEXT_PAGE = "next-page",
+  /** Next.js API route context */
+  NEXT_API = "next-api",
+}
+
+/**
+ * Check if platform is a CLI variant (local or package)
+ */
+export function isCliPlatform(platform: Platform): boolean {
+  return platform === Platform.CLI || platform === Platform.CLI_PACKAGE;
+}
+
+/**
+ * Check if running from npm package (not local development)
+ */
+export function isPackagePlatform(platform: Platform): boolean {
+  return platform === Platform.CLI_PACKAGE;
+}

package/src/app/api/[locale]/system/unified-interface/shared/types/types.ts

@@ -0,0 +1,80 @@
+/**
+ * UI System Types
+ *
+ * Complete type definitions for the widget-based UI configuration system.
+ * Supports all interface contexts with type-safe widget configurations.
+ */
+
+import type { TranslationKey } from "@/i18n/core/static-types";
+
+import type { LayoutConfig, WidgetConfig } from "../widgets/configs";
+import type {
+  FieldActions,
+  InteractiveActions,
+  LifecycleActions,
+} from "./endpoint";
+import type { FieldDataType, InterfaceContext } from "./enums";
+
+// ============================================================================
+// UI CONFIGURATION SYSTEM
+// ============================================================================
+
+/**
+ * Context-specific UI configuration
+ */
+export interface ContextSpecificConfig<TKey extends string> {
+  // Widget configuration for this context
+  widget?: WidgetConfig<TKey>;
+
+  // Field-specific overrides
+  field?: {
+    type?: FieldDataType;
+    label?: TranslationKey;
+    placeholder?: TranslationKey;
+    description?: TranslationKey;
+    required?: boolean;
+    disabled?: boolean;
+    visible?: boolean;
+    readonly?: boolean;
+  };
+
+  // Layout configuration
+  layout?: LayoutConfig;
+
+  // Actions for this context
+  actions?: FieldActions & InteractiveActions;
+
+  // Validation rules specific to this context
+  validation?: {
+    rules?: Record<string, string | number | boolean>;
+    messages?: Record<string, TranslationKey>;
+  };
+
+  // Conditional rendering
+  conditions?: Array<{
+    field: string;
+    operator: "equals" | "not_equals" | "exists" | "not_exists";
+    value?: string | number | boolean;
+    action: "show" | "hide" | "disable" | "require";
+  }>;
+}
+
+/**
+ * Complete UI configuration that can be attached to any field
+ */
+export interface UIConfig<TKey extends string> {
+  // Context-specific configurations
+  contexts?: Partial<Record<InterfaceContext, ContextSpecificConfig<TKey>>>;
+
+  // Default configuration (applies to all contexts unless overridden)
+  default?: ContextSpecificConfig<TKey>;
+
+  // Global actions that apply across all contexts
+  globalActions?: LifecycleActions;
+
+  // Responsive behavior
+  responsive?: {
+    breakpoints?: Record<string, number>;
+    behavior?: "hide" | "collapse" | "stack" | "scroll";
+  };
+}

package/src/app/api/[locale]/system/unified-interface/shared/types/ui-config.ts

@@ -0,0 +1,76 @@
+/**
+ * Enhanced UI Configuration System
+ *
+ * This integrates the widget system and actions into our existing field architecture,
+ * providing a complete definition-driven UI solution that works across all interface contexts.
+ */
+
+import type { TranslationKey } from "@/i18n/core/static-types";
+
+import type { LayoutConfig, WidgetConfig } from "../widgets/configs";
+import type {
+  FieldActions,
+  InteractiveActions,
+  LifecycleActions,
+} from "./actions";
+import type { FieldDataType, InterfaceContext } from "./enums";
+
+/**
+ * UI configuration that can be attached to any field
+ */
+export interface UIConfig<TKey extends string> {
+  // Context-specific configurations
+  contexts?: Partial<Record<InterfaceContext, ContextSpecificConfig<TKey>>>;
+
+  // Default configuration (applies to all contexts unless overridden)
+  default?: ContextSpecificConfig<TKey>;
+
+  // Global actions that apply across all contexts
+  globalActions?: LifecycleActions;
+
+  // Responsive behavior
+  responsive?: {
+    breakpoints?: Record<string, number>;
+    behavior?: "hide" | "collapse" | "stack" | "scroll";
+  };
+}
+
+/**
+ * Context-specific UI configuration
+ */
+export interface ContextSpecificConfig<TKey extends string> {
+  // Widget configuration for this context
+  widget?: WidgetConfig<TKey>;
+
+  // Field-specific overrides
+  field?: {
+    type?: FieldDataType;
+    label?: TranslationKey;
+    placeholder?: TranslationKey;
+    description?: TranslationKey;
+    required?: boolean;
+    disabled?: boolean;
+    visible?: boolean;
+    readonly?: boolean;
+  };
+
+  // Layout configuration
+  layout?: LayoutConfig;
+
+  // Actions for this context
+  actions?: FieldActions & InteractiveActions;
+
+  // Validation rules specific to this context
+  validation?: {
+    rules?: Record<string, string | number | boolean>;
+    messages?: Record<string, TranslationKey>;
+  };
+
+  // Conditional rendering
+  conditions?: Array<{
+    field: string;
+    operator: "equals" | "not_equals" | "exists" | "not_exists";
+    value?: string | number | boolean;
+    action: "show" | "hide" | "disable" | "require";
+  }>;
+}

package/src/app/api/[locale]/system/unified-interface/shared/utils/error-types.ts

@@ -0,0 +1,27 @@
+/**
+ * Error Handling Types
+ * Shared types for error handling across all platforms
+ */
+
+/**
+ * Primitive JSON values
+ */
+type JsonPrimitive = string | number | boolean | null;
+
+/**
+ * JSON-compatible object (record with JSON values)
+ */
+interface JsonObject {
+  [key: string]: JsonValue;
+}
+
+/**
+ * JSON-compatible array
+ */
+// eslint-disable-next-line @typescript-eslint/no-empty-object-type
+interface JsonArray extends Array<JsonValue> {}
+
+/**
+ * Any valid JSON value
+ */
+export type JsonValue = JsonPrimitive | JsonObject | JsonArray;

package/src/app/api/[locale]/system/unified-interface/shared/utils/path.ts

@@ -0,0 +1,63 @@
+/**
+ * Path utilities
+ * Common path manipulation functions
+ */
+
+import type { CreateApiEndpointAny } from "../types/endpoint";
+
+/**
+ * Path separator - underscore used consistently across entire codebase
+ * AI providers require: ^[a-zA-Z0-9_-]{1,128}$
+ * We use underscore as the ONLY separator
+ */
+export const PATH_SEPARATOR = "_";
+
+/**
+ * Split path by separator and filter out empty segments
+ */
+export function splitPath(path: string): string[] {
+  return path.split(PATH_SEPARATOR).filter(Boolean);
+}
+
+/**
+ * Join path segments with separator
+ * Validates that segments don't contain underscores (would conflict with separator)
+ */
+function joinPath(path: readonly string[]): string {
+  // Validate no segments contain underscores
+  for (const segment of path) {
+    if (segment.includes("_")) {
+      // eslint-disable-next-line oxlint-plugin-restricted/restricted-syntax -- Build-time validation: This throw is intentional to catch developer configuration errors early during endpoint definition. Invalid paths would break AI tool calling, so we fail fast at build time rather than runtime.
+      throw new Error(
+        `Path segment contains underscore which conflicts with separator: "${segment}". ` +
+          `Full path: ${[...path].join(" / ")}. ` +
+          `Underscores are reserved as separators. Use hyphens in file/folder names instead.`,
+      );
+    }
+  }
+
+  return [...path].join(PATH_SEPARATOR);
+}
+
+/**
+ * Sanitize a path segment to meet AI provider requirements
+ * AI providers require tool names to match: ^[a-zA-Z0-9_-]{1,128}$
+ * This removes square brackets from dynamic routes like [id]
+ */
+function sanitizePathSegment(segment: string): string {
+  // Remove square brackets to handle dynamic routes like [id]
+  // Example: "[id]" becomes "id", "[threadId]" becomes "threadId"
+  return segment.replaceAll(/\[|\]/g, "");
+}
+
+/**
+ * Convert endpoint definition to full toolName path
+ * Format: "v1_core_agent_brave-search_GET"
+ * Note: Hyphens are allowed within segment names (e.g., "brave-search")
+ * Dynamic route segments have brackets removed (e.g., "[id]" becomes "id")
+ */
+export function endpointToToolName(endpoint: CreateApiEndpointAny): string {
+  // Sanitize each path segment to remove invalid characters
+  const sanitizedPath = endpoint.path.map(sanitizePathSegment);
+  return `${joinPath(sanitizedPath)}${PATH_SEPARATOR}${endpoint.method}`;
+}