@motiadev/workbench 0.14.0-beta.165-285707 → 0.15.0-beta.165

package/dist/motia-plugin/index.ts

@@ -0,0 +1,183 @@
+import { Printer } from '@motiadev/core'
+import path from 'path'
+import type { Plugin, ViteDevServer } from 'vite'
+import { generateCssImports, generatePluginCode, isValidCode } from './generator'
+import { handlePluginHotUpdate } from './hmr'
+import { createAliasConfig, resolvePluginPackage } from './resolver'
+import type { WorkbenchPlugin } from './types'
+import { CONSTANTS } from './types'
+import { isLocalPlugin, normalizePath } from './utils'
+import { validatePlugins } from './validator'
+
+/**
+ * Vite plugin for loading and managing Motia workbench plugins.
+ *
+ * Features:
+ * - Hot Module Replacement (HMR) support
+ * - Runtime validation with detailed error messages
+ * - Verbose logging for debugging
+ * - CSS injection for plugin styles
+ *
+ * @param plugins - Array of plugin configurations
+ * @param options - Optional loader configuration
+ * @returns Vite plugin instance
+ *
+ * @example
+ * ```ts
+ * export default defineConfig({
+ *   plugins: [
+ *     motiaPluginsPlugin([
+ *       { packageName: '@my-org/plugin', label: 'My Plugin' }
+ *     ])
+ *   ]
+ * })
+ * ```
+ */
+const printer = new Printer(process.cwd())
+
+export default function motiaPluginsPlugin(plugins: WorkbenchPlugin[]): Plugin {
+  let devServer: ViteDevServer | null = null
+
+  try {
+    const validationResult = validatePlugins(plugins, {
+      failFast: false,
+    })
+
+    if (!validationResult.valid) {
+      printer.printPluginError('Plugin configuration validation failed:')
+      for (const err of validationResult.errors) {
+        printer.printPluginError(`  ${err}`)
+      }
+      throw new Error('Invalid plugin configuration. See errors above.')
+    }
+
+    if (validationResult.warnings.length > 0) {
+      for (const warning of validationResult.warnings) {
+        printer.printPluginWarn(warning)
+      }
+    }
+  } catch (error) {
+    printer.printPluginError(`Failed to validate plugins: ${error}`)
+    throw error
+  }
+
+  const alias = createAliasConfig(plugins)
+
+  printer.printPluginLog(`Initialized with ${plugins.length} plugin(s)`)
+
+  return {
+    name: 'vite-plugin-motia-plugins',
+    enforce: 'pre',
+
+    buildStart() {
+      printer.printPluginLog('Build started')
+    },
+
+    config: () => ({
+      resolve: {
+        alias,
+      },
+    }),
+
+    configureServer(server) {
+      devServer = server
+      printer.printPluginLog('Dev server configured, HMR enabled')
+
+      const configPaths = [path.join(process.cwd(), 'motia.config.ts'), path.join(process.cwd(), 'motia.config.js')]
+
+      for (const configPath of configPaths) {
+        server.watcher.add(configPath)
+      }
+      printer.printPluginLog('Watching for config file changes')
+
+      const localPlugins = plugins.filter((p) => isLocalPlugin(p.packageName))
+      if (localPlugins.length > 0) {
+        printer.printPluginLog(`Watching ${localPlugins.length} local plugin(s)`)
+
+        for (const plugin of localPlugins) {
+          const resolved = resolvePluginPackage(plugin)
+          const watchPath = resolved.resolvedPath
+
+          server.watcher.add(watchPath)
+          printer.printPluginLog(`Watching: ${watchPath}`)
+        }
+
+        server.watcher.on('change', (file) => {
+          const normalizedFile = normalizePath(file)
+          printer.printPluginLog(`File watcher detected change: ${normalizedFile}`)
+        })
+
+        server.watcher.on('add', (file) => {
+          const normalizedFile = normalizePath(file)
+          printer.printPluginLog(`File watcher detected new file: ${normalizedFile}`)
+        })
+      }
+    },
+
+    resolveId(id) {
+      if (id === CONSTANTS.VIRTUAL_MODULE_ID) {
+        return CONSTANTS.RESOLVED_VIRTUAL_MODULE_ID
+      }
+    },
+
+    load(id) {
+      if (id !== CONSTANTS.RESOLVED_VIRTUAL_MODULE_ID) {
+        return null
+      }
+
+      printer.printPluginLog('Loading plugins virtual module')
+      printer.printPluginLog('Generating plugin code...')
+
+      const code = generatePluginCode(plugins)
+
+      if (!isValidCode(code)) {
+        printer.printPluginError('Generated code is invalid or empty')
+        return 'export const plugins = []'
+      }
+
+      printer.printPluginLog('Plugin code generated successfully')
+
+      return code
+    },
+
+    async transform(code, id) {
+      const normalizedId = normalizePath(id)
+
+      if (!normalizedId.endsWith('src/index.css')) {
+        return null
+      }
+
+      printer.printPluginLog('Injecting plugin CSS imports')
+
+      const cssImports = generateCssImports(plugins)
+
+      if (!cssImports) {
+        return null
+      }
+
+      return {
+        code: `${cssImports}\n${code}`,
+        map: null,
+      }
+    },
+
+    handleHotUpdate(ctx) {
+      if (!devServer) {
+        printer.printPluginWarn('HMR: Dev server not available')
+        return
+      }
+
+      const modulesToUpdate = handlePluginHotUpdate(ctx, plugins, printer)
+
+      if (modulesToUpdate && modulesToUpdate.length > 0) {
+        const merged = Array.from(new Set([...(ctx.modules || []), ...modulesToUpdate]))
+        printer.printPluginLog(`HMR: Successfully updated ${merged.length} module(s)`)
+        return merged
+      }
+    },
+
+    buildEnd() {
+      printer.printPluginLog('Build ended')
+    },
+  }
+}

package/dist/motia-plugin/{resolver.d.ts → resolver.ts}

@@ -1,4 +1,6 @@
-import type { ResolvedPackage, WorkbenchPlugin } from './types';
+import type { ResolvedPackage, WorkbenchPlugin } from './types'
+import { isLocalPlugin, normalizePath, resolveLocalPath, resolveNpmPath } from './utils'
+
 /**
  * Resolves a plugin package to its absolute path and creates an alias.
  *
@@ -26,7 +28,20 @@ import type { ResolvedPackage, WorkbenchPlugin } from './types';
  * // }
  * ```
  */
-export declare function resolvePluginPackage(plugin: WorkbenchPlugin): ResolvedPackage;
+export function resolvePluginPackage(plugin: WorkbenchPlugin): ResolvedPackage {
+  const { packageName } = plugin
+  const local = isLocalPlugin(packageName)
+
+  const resolvedPath = local ? resolveLocalPath(packageName) : resolveNpmPath(packageName)
+
+  return {
+    packageName,
+    resolvedPath: normalizePath(resolvedPath),
+    isLocal: local,
+    alias: packageName,
+  }
+}
+
 /**
  * Resolves all plugin packages and creates a Vite alias configuration.
  *
@@ -46,18 +61,36 @@ export declare function resolvePluginPackage(plugin: WorkbenchPlugin): ResolvedP
  * // }
  * ```
  */
-export declare function createAliasConfig(plugins: WorkbenchPlugin[]): Record<string, string>;
+export function createAliasConfig(plugins: WorkbenchPlugin[]): Record<string, string> {
+  // Get unique package names to avoid duplicate aliases
+  const uniquePackages = Array.from(new Set(plugins.map((p) => p.packageName)))
+
+  const aliases: Record<string, string> = {}
+
+  for (const packageName of uniquePackages) {
+    const resolved = resolvePluginPackage({ packageName } as WorkbenchPlugin)
+    aliases[packageName] = resolved.resolvedPath
+  }
+
+  return aliases
+}
+
 /**
  * Resolves all plugins and returns their resolved package information.
  *
  * @param plugins - Array of plugin configurations
  * @returns Array of resolved package information
  */
-export declare function resolveAllPlugins(plugins: WorkbenchPlugin[]): ResolvedPackage[];
+export function resolveAllPlugins(plugins: WorkbenchPlugin[]): ResolvedPackage[] {
+  return plugins.map((plugin) => resolvePluginPackage(plugin))
+}
+
 /**
  * Gets the unique set of package names from plugins.
  *
  * @param plugins - Array of plugin configurations
  * @returns Array of unique package names
  */
-export declare function getUniquePackageNames(plugins: WorkbenchPlugin[]): string[];
+export function getUniquePackageNames(plugins: WorkbenchPlugin[]): string[] {
+  return Array.from(new Set(plugins.map((p) => p.packageName)))
+}

package/dist/motia-plugin/types.ts

@@ -0,0 +1,198 @@
+/**
+ * Configuration for a single workbench plugin.
+ * This interface defines how plugins are registered and configured in the Motia workbench.
+ */
+export interface WorkbenchPlugin {
+  /**
+   * The package name or local path to the plugin.
+   * - For npm packages: use the package name (e.g., '@my-org/my-plugin')
+   * - For local plugins: use the tilde prefix (e.g., '~/plugins/my-plugin')
+   */
+  packageName: string
+
+  /**
+   * Optional named export to use from the plugin package.
+   * If not specified, the default export will be used.
+   * Can be overridden by the plugin's own config.
+   */
+  componentName?: string
+
+  /**
+   * Position where the plugin tab should appear in the workbench.
+   * - 'top': Display in the top tab bar
+   * - 'bottom': Display in the bottom tab bar
+   * @default 'top'
+   */
+  position?: 'top' | 'bottom'
+
+  /**
+   * Display label for the plugin tab.
+   * Can be overridden by the plugin's own config.
+   */
+  label?: string
+
+  /**
+   * Icon name from lucide-react to display next to the label.
+   * Can be overridden by the plugin's own config.
+   * @default 'toy-brick'
+   */
+  labelIcon?: string
+
+  /**
+   * Array of CSS package imports to inject into the workbench.
+   * These will be added to the main index.css file.
+   * Example: ['@my-org/my-plugin/styles.css']
+   */
+  cssImports?: string[]
+
+  /**
+   * Props to pass to the plugin component when it's rendered.
+   * Can be overridden by the plugin's own config.
+   */
+  props?: Record<string, any>
+}
+
+/**
+ * Result of validating a plugin configuration.
+ */
+export interface ValidationResult {
+  /**
+   * Whether the validation passed
+   */
+  valid: boolean
+
+  /**
+   * Array of error messages if validation failed
+   */
+  errors: string[]
+
+  /**
+   * Array of warning messages for non-critical issues
+   */
+  warnings: string[]
+
+  /**
+   * The validated and normalized plugin configuration (if valid)
+   */
+  plugin?: WorkbenchPlugin
+}
+
+/**
+ * Context object passed to various plugin internals functions.
+ * Contains shared state and configuration.
+ */
+export interface PluginContext {
+  /**
+   * Array of plugin configurations
+   */
+  plugins: WorkbenchPlugin[]
+
+  /**
+   * Vite dev server instance (only available in dev mode)
+   */
+  server?: any
+}
+
+/**
+ * Package resolution result.
+ */
+export interface ResolvedPackage {
+  /**
+   * The original package name from the configuration
+   */
+  packageName: string
+
+  /**
+   * Resolved absolute path to the package
+   */
+  resolvedPath: string
+
+  /**
+   * Whether this is a local plugin (starts with ~/)
+   */
+  isLocal: boolean
+
+  /**
+   * Alias to use for imports
+   */
+  alias: string
+}
+
+/**
+ * Generated virtual module exports interface.
+ * This is what consumers will import from 'virtual:motia-plugins'.
+ */
+export interface VirtualModuleExports {
+  /**
+   * Array of processed plugin configurations ready to be registered
+   */
+  plugins: ProcessedPlugin[]
+}
+
+/**
+ * A plugin configuration after processing and normalization.
+ * This is the format used by the workbench to register tabs.
+ */
+export interface ProcessedPlugin {
+  /**
+   * Display label for the plugin tab
+   */
+  label: string
+
+  /**
+   * Icon name from lucide-react
+   */
+  labelIcon: string
+
+  /**
+   * Position in the workbench ('top' or 'bottom')
+   */
+  position: 'top' | 'bottom'
+
+  /**
+   * Props to pass to the component
+   */
+  props: Record<string, any>
+
+  /**
+   * The React component to render
+   */
+  component: any
+}
+
+/**
+ * Type guard to check if position is valid.
+ */
+export function isValidPosition(position: any): position is 'top' | 'bottom' {
+  return position === 'top' || position === 'bottom'
+}
+
+/**
+ * Constants used throughout the plugin system.
+ */
+export const CONSTANTS = {
+  /**
+   * Virtual module ID for importing plugins
+   */
+  VIRTUAL_MODULE_ID: 'virtual:motia-plugins',
+
+  /**
+   * Resolved virtual module ID (with null byte prefix for Vite)
+   */
+  RESOLVED_VIRTUAL_MODULE_ID: '\0virtual:motia-plugins',
+
+  /**
+   * Log prefix for all plugin messages
+   */
+  LOG_PREFIX: '[motia-plugins]',
+
+  /**
+   * Default values for optional plugin fields
+   */
+  DEFAULTS: {
+    POSITION: 'top' as const,
+    LABEL: 'Plugin label',
+    ICON: 'toy-brick',
+    PROPS: {},
+  },
+} as const

package/dist/motia-plugin/{utils.d.ts → utils.ts}

@@ -1,3 +1,5 @@
+import path from 'path'
+
 /**
  * Normalizes a file path by replacing backslashes with forward slashes.
  * This is useful for consistent path comparisons across different operating systems.
@@ -11,7 +13,10 @@
  * normalizePath('/Users/file.ts')     // Returns: '/Users/file.ts'
  * ```
  */
-export declare function normalizePath(filePath: string): string;
+export function normalizePath(filePath: string): string {
+  return filePath.replace(/\\/g, '/')
+}
+
 /**
  * Checks if a package name represents a local plugin (starts with ~/).
  *
@@ -25,7 +30,10 @@ export declare function normalizePath(filePath: string): string;
  * isLocalPlugin('my-plugin')               // Returns: false
  * ```
  */
-export declare function isLocalPlugin(packageName: string): boolean;
+export function isLocalPlugin(packageName: string): boolean {
+  return packageName.startsWith('~/')
+}
+
 /**
  * Resolves a local plugin path to an absolute path.
  * Strips the ~/ prefix and joins with the current working directory.
@@ -40,7 +48,10 @@ export declare function isLocalPlugin(packageName: string): boolean;
  * // Returns: '/Users/project/plugins/my-plugin'
  * ```
  */
-export declare function resolveLocalPath(packageName: string): string;
+export function resolveLocalPath(packageName: string): string {
+  return path.join(process.cwd(), packageName.replace('~/', ''))
+}
+
 /**
  * Resolves an npm package path to the node_modules directory.
  *
@@ -54,4 +65,6 @@ export declare function resolveLocalPath(packageName: string): string;
  * // Returns: '/Users/project/node_modules/@my-org/my-plugin'
  * ```
  */
-export declare function resolveNpmPath(packageName: string): string;
+export function resolveNpmPath(packageName: string): string {
+  return path.join(process.cwd(), 'node_modules', packageName)
+}

package/dist/motia-plugin/validator.ts

@@ -0,0 +1,197 @@
+import { existsSync } from 'fs'
+import { z } from 'zod'
+import type { ValidationResult, WorkbenchPlugin } from './types'
+import { CONSTANTS, isValidPosition } from './types'
+import { isLocalPlugin, resolveLocalPath } from './utils'
+
+/**
+ * Zod schema for WorkbenchPlugin configuration.
+ * Provides runtime type validation with detailed error messages.
+ */
+const WorkbenchPluginSchema = z.object({
+  packageName: z
+    .string()
+    .min(1, 'packageName is required and cannot be empty')
+    .refine((name) => name.startsWith('~/') || name.startsWith('@') || /^[a-z0-9-_]+$/i.test(name), {
+      message: 'packageName must be a valid npm package name or local path (starting with ~/)',
+    }),
+
+  componentName: z.string().optional(),
+
+  position: z
+    .enum(['top', 'bottom'])
+    .optional()
+    .refine((pos) => pos === undefined || isValidPosition(pos), {
+      message: 'position must be either "top" or "bottom"',
+    }),
+
+  label: z.string().optional(),
+
+  labelIcon: z.string().optional(),
+
+  cssImports: z.array(z.string()).optional(),
+
+  props: z.record(z.any(), z.any()).optional(),
+})
+
+/**
+ * Validates a single plugin configuration.
+ *
+ * @param plugin - The plugin configuration to validate
+ * @param index - The index of the plugin in the array (for error messages)
+ * @returns A validation result with errors, warnings, and normalized plugin
+ */
+export function validatePluginConfig(plugin: any, index: number): ValidationResult {
+  const errors: string[] = []
+  const warnings: string[] = []
+
+  if (typeof plugin !== 'object' || plugin === null) {
+    return {
+      valid: false,
+      errors: [`Plugin at index ${index}: expected object, got ${typeof plugin}`],
+      warnings: [],
+    }
+  }
+
+  try {
+    const result = WorkbenchPluginSchema.safeParse(plugin)
+
+    if (!result.success) {
+      result.error.issues.forEach((err: z.core.$ZodIssue) => {
+        const path = err.path.join('.')
+        errors.push(`Plugin at index ${index}, field "${path}": ${err.message}`)
+      })
+
+      return { valid: false, errors, warnings }
+    }
+
+    const validatedPlugin = result.data as WorkbenchPlugin
+
+    if (isLocalPlugin(validatedPlugin.packageName)) {
+      const resolvedPath = resolveLocalPath(validatedPlugin.packageName)
+      if (!existsSync(resolvedPath)) {
+        warnings.push(
+          `Plugin at index ${index}: local path "${validatedPlugin.packageName}" does not exist at "${resolvedPath}". ` +
+            `Make sure the path is correct relative to the project root.`,
+        )
+      }
+    }
+
+    if (!validatedPlugin.label) {
+      warnings.push(`Plugin at index ${index}: "label" not specified, will use default "${CONSTANTS.DEFAULTS.LABEL}"`)
+    }
+
+    if (!validatedPlugin.labelIcon) {
+      warnings.push(
+        `Plugin at index ${index}: "labelIcon" not specified, will use default "${CONSTANTS.DEFAULTS.ICON}"`,
+      )
+    }
+
+    if (!validatedPlugin.position) {
+      warnings.push(
+        `Plugin at index ${index}: "position" not specified, will use default "${CONSTANTS.DEFAULTS.POSITION}"`,
+      )
+    }
+
+    if (validatedPlugin.props && Object.keys(validatedPlugin.props).length === 0) {
+      warnings.push(`Plugin at index ${index}: "props" is an empty object`)
+    }
+
+    if (validatedPlugin.cssImports) {
+      if (validatedPlugin.cssImports.length === 0) {
+        warnings.push(`Plugin at index ${index}: "cssImports" is an empty array`)
+      }
+
+      validatedPlugin.cssImports.forEach((cssImport, cssIndex) => {
+        if (!cssImport || cssImport.trim() === '') {
+          warnings.push(`Plugin at index ${index}: cssImport at index ${cssIndex} is empty or whitespace`)
+        }
+      })
+    }
+
+    return {
+      valid: true,
+      errors: [],
+      warnings,
+      plugin: validatedPlugin,
+    }
+  } catch (error) {
+    return {
+      valid: false,
+      errors: [`Plugin at index ${index}: unexpected validation error: ${error}`],
+      warnings: [],
+    }
+  }
+}
+
+/**
+ * Validates an array of plugin configurations.
+ *
+ * @param plugins - Array of plugin configurations to validate
+ * @param options - Validation options
+ * @returns Combined validation result for all plugins
+ */
+export function validatePlugins(plugins: any[], options: { failFast?: boolean } = {}): ValidationResult {
+  const allErrors: string[] = []
+  const allWarnings: string[] = []
+  const validatedPlugins: WorkbenchPlugin[] = []
+
+  if (!Array.isArray(plugins)) {
+    return {
+      valid: false,
+      errors: [`Expected plugins to be an array, got ${typeof plugins}`],
+      warnings: [],
+    }
+  }
+
+  if (plugins.length === 0) {
+    console.warn('[motia-plugins] No plugins provided to validate')
+    return {
+      valid: true,
+      errors: [],
+      warnings: ['No plugins configured'],
+    }
+  }
+
+  for (let i = 0; i < plugins.length; i++) {
+    const result = validatePluginConfig(plugins[i], i)
+
+    allErrors.push(...result.errors)
+    allWarnings.push(...result.warnings)
+
+    if (result.valid && result.plugin) {
+      validatedPlugins.push(result.plugin)
+    }
+
+    if (options.failFast && result.errors.length > 0) {
+      break
+    }
+  }
+
+  const packageNames = validatedPlugins.map((p) => p.packageName)
+  const duplicates = packageNames.filter((name, index) => packageNames.indexOf(name) !== index)
+
+  if (duplicates.length > 0) {
+    const uniqueDuplicates = [...new Set(duplicates)]
+    uniqueDuplicates.forEach((dup) => {
+      allWarnings.push(`Duplicate package name found: "${dup}". This may cause conflicts.`)
+    })
+  }
+
+  const valid = allErrors.length === 0
+
+  if (valid) {
+    console.log(`[motia-plugins] ✓ Validated ${validatedPlugins.length} plugin(s) successfully`)
+    if (allWarnings.length > 0) {
+      console.warn(`[motia-plugins] Found ${allWarnings.length} warning(s)`)
+    }
+  } else {
+    console.error(`[motia-plugins] ✗ Validation failed with ${allErrors.length} error(s)`)
+  }
+
+  return {
+    valid,
+    errors: allErrors,
+    warnings: allWarnings,
+  }
+}