fix: improve Windows and WSL compatibility for create command (#1089)

Co-authored-by: Anderson Leal <anderson.leal@gmail.com>

Author: andersonleal

packages/snap/src/__tests__/validate-python-environment.test.ts

@@ -111,9 +111,7 @@ describe('validatePythonEnvironment', () => {
       expect(result.success).toBe(false)
       expect(result.hasPythonFiles).toBe(true)
       expect(mockInternalLogger.error).toHaveBeenCalledWith('Python environment is incomplete')
-      expect(mockInternalLogger.info).toHaveBeenCalledWith(
-        'The python_modules directory exists but appears to be corrupted',
-      )
+      expect(mockInternalLogger.info).toHaveBeenCalledWith('The python_modules/lib directory was not found')
       expect(mockInternalLogger.info).toHaveBeenCalledWith('Run npm install to recreate your Python environment')
     })
 

packages/snap/src/create/index.ts

@@ -6,6 +6,7 @@ import type { CliContext, Message } from '../cloud/config-utils'
 import { generateTypes } from '../generate-types'
 import { pythonInstall } from '../install'
 import { pluginDependencies } from '../plugins/plugin-dependencies'
+import { getInstallCommands, getInstallSaveCommands } from '../utils/build-npm-command'
 import { executeCommand } from '../utils/execute-command'
 import { getPackageManager, getPackageManagerFromEnv } from '../utils/get-package-manager'
 import { version } from '../version'
@@ -18,12 +19,7 @@ const __dirname = path.dirname(fileURLToPath(import.meta.url))
 const installRequiredDependencies = async (packageManager: string, rootDir: string, context: CliContext) => {
   context.log('installing-dependencies', (message: Message) => message.tag('info').append('Installing dependencies...'))
 
-  const installCommand = {
-    npm: 'npm install --save',
-    yarn: 'yarn add',
-    pnpm: 'pnpm add',
-    bun: 'bun add',
-  }[packageManager]
+  const installCommand = getInstallSaveCommands(rootDir)[packageManager]
 
   const dependencies = [
     `motia@${version}`,
@@ -269,15 +265,13 @@ export const create = async ({
       message.tag('info').append('Installing plugin dependencies...'),
     )
 
-    const installCommand = {
-      npm: 'npm install',
-      yarn: 'yarn',
-      pnpm: 'pnpm install',
-      bun: 'bun install',
-    }[packageManager]
+    const installCommands: Record<string, string> = {
+      ...getInstallCommands(rootDir),
+    }
+    const installCommand = installCommands[packageManager] || installCommands['npm']
 
     try {
-      await executeCommand(installCommand!, rootDir)
+      await executeCommand(installCommand, rootDir)
       context.log('plugin-dependencies-installed', (message: Message) =>
         message.tag('success').append('Plugin dependencies installed'),
       )

packages/snap/src/create/pull-rules.ts

@@ -2,6 +2,7 @@ import fs from 'fs'
 import path from 'path'
 import { fileURLToPath } from 'url'
 import type { CliContext, Message } from '../cloud/config-utils'
+import { copyWithWSLCompat } from './utils'
 
 type PullRulesArgs = {
   rootDir: string
@@ -19,14 +20,22 @@ export const pullRules = async (args: PullRulesArgs, context: CliContext) => {
     const type = isFolder ? 'Folder' : 'File'
 
     if (args.force || !fs.existsSync(targetFile)) {
-      fs.cpSync(path.join(cursorTemplateDir, file), targetFile, {
-        recursive: isFolder,
-        force: true,
-      })
-
-      context.log(`${file}-created`, (message: Message) =>
-        message.tag('success').append(type).append(file, 'cyan').append('has been created.'),
-      )
+      try {
+        copyWithWSLCompat(path.join(cursorTemplateDir, file), targetFile, isFolder)
+        context.log(`${file}-created`, (message: Message) =>
+          message.tag('success').append(type).append(file, 'cyan').append('has been created.'),
+        )
+      } catch (error: any) {
+        context.log(`${file}-error`, (message: Message) =>
+          message
+            .tag('error')
+            .append('Failed to create')
+            .append(type, 'yellow')
+            .append(file, 'cyan')
+            .append(`: ${error.message}`),
+        )
+        throw error
+      }
     } else {
       context.log(`${file}-skipped`, (message: Message) =>
         message.tag('warning').append(type).append(file, 'cyan').append('already exists, skipping...'),

packages/snap/src/create/utils.ts

@@ -12,3 +12,68 @@ export const checkIfDirectoryExists = (dir: string): boolean => {
     return false
   }
 }
+
+/**
+ * Recursively copies a directory using read/write operations.
+ * This is a fallback method for WSL/Windows compatibility.
+ */
+function copyDirectoryRecursive(src: string, dest: string): void {
+  fs.mkdirSync(dest, { recursive: true })
+  const entries = fs.readdirSync(src, { withFileTypes: true })
+
+  for (const entry of entries) {
+    const srcPath = path.join(src, entry.name)
+    const destPath = path.join(dest, entry.name)
+
+    if (entry.isDirectory()) {
+      copyDirectoryRecursive(srcPath, destPath)
+    } else {
+      // For files, read and write manually
+      const content = fs.readFileSync(srcPath)
+      fs.writeFileSync(destPath, content)
+    }
+  }
+}
+
+/**
+ * Copies a file or directory with WSL/Windows compatibility.
+ * Attempts to use fs.cpSync first for better performance, but falls back
+ * to manual read/write operations if permission errors occur (common in WSL).
+ *
+ * @param src - Source file or directory path
+ * @param dest - Destination file or directory path
+ * @param isDirectory - Whether the source is a directory
+ * @throws Error if copy fails after all fallback attempts
+ */
+export function copyWithWSLCompat(src: string, dest: string, isDirectory: boolean): void {
+  // Ensure the destination *parent* directory exists.
+  // - For directory copies, fs.cpSync/copyDirectoryRecursive will create `dest` as needed.
+  // - For file copies, we only need the parent directory.
+  fs.mkdirSync(path.dirname(dest), { recursive: true })
+
+  try {
+    // Try the standard cpSync first (faster and works in most cases)
+    fs.cpSync(src, dest, {
+      recursive: isDirectory,
+      force: true,
+    })
+  } catch (error: unknown) {
+    // If we get permission errors (common in WSL when writing to Windows paths),
+    // fall back to manual copy using read/write operations
+    const code =
+      typeof error === 'object' && error !== null && 'code' in error ? (error as NodeJS.ErrnoException).code : undefined
+
+    if (code === 'EPERM' || code === 'EACCES') {
+      if (isDirectory) {
+        copyDirectoryRecursive(src, dest)
+      } else {
+        // For files, read and write manually
+        const content = fs.readFileSync(src)
+        fs.writeFileSync(dest, content)
+      }
+    } else {
+      // Re-throw other errors
+      throw error
+    }
+  }
+}

packages/snap/src/plugins/install-plugin-dependencies.ts

@@ -1,6 +1,7 @@
 import fs from 'node:fs'
 import path from 'node:path'
 import type { Printer } from '@motiadev/core'
+import { getInstallCommands } from '../utils/build-npm-command'
 import { executeCommand } from '../utils/execute-command'
 import { getPackageManager } from '../utils/get-package-manager'
 import { version } from '../version'
@@ -50,13 +51,8 @@ export const installPluginDependencies = async (baseDir: string, printer: Printe
   }
   printer.printPluginLog(`Installing dependencies using ${packageManager}...`)
 
-  const installCommands: Record<string, string> = {
-    npm: 'npm install',
-    yarn: 'yarn install',
-    pnpm: 'pnpm install',
-  }
-
-  const installCommand = installCommands[packageManager] || 'npm install'
+  const installCommands = getInstallCommands(baseDir)
+  const installCommand = installCommands[packageManager] || installCommands['npm']
 
   try {
     await executeCommand(installCommand, baseDir, { silent: false })

packages/snap/src/redis/memory-manager.ts

@@ -2,6 +2,8 @@ import { mkdirSync } from 'fs'
 import type { RedisClientType } from 'redis'
 import { RedisMemoryServer } from 'redis-memory-server'
 import type { RedisMemoryInstancePropT } from 'redis-memory-server/lib/types'
+import { ensureBuildTools } from '../utils/check-build-tools'
+import { internalLogger } from '../utils/internal-logger'
 import type { RedisConnectionInfo } from './types'
 
 export class RedisMemoryManager {
@@ -25,6 +27,9 @@ export class RedisMemoryManager {
   async startServer(baseDir: string): Promise<RedisConnectionInfo> {
     if (!this.server) {
       try {
+        // Check for required build tools before attempting to start
+        await ensureBuildTools()
+
         mkdirSync(baseDir, { recursive: true })
 
         const instance: RedisMemoryInstancePropT = {
@@ -36,27 +41,61 @@ export class RedisMemoryManager {
         }
 
         this.server = new RedisMemoryServer({ instance })
-        console.log('Redis Memory Server started')
-        this.running = true
         this.registerCleanupHandlers()
       } catch (error) {
-        console.error('[Redis Memory Server] Failed to start:', error)
+        internalLogger.error('Failed to initialize Redis Memory Server')
+        if (error instanceof Error) {
+          console.error(error.message)
+          if (process.env.LOG_LEVEL === 'debug' && error.stack) {
+            console.error('\nStack trace:')
+            console.error(error.stack)
+          }
+        }
         throw error
       }
     }
 
-    const host = await this.server.getHost()
-    const port = await this.server.getPort()
+    try {
+      const host = await this.server.getHost()
+      const port = await this.server.getPort()
+
+      this.running = true
+      internalLogger.info('Redis Memory Server started', `${host}:${port}`)
+
+      return { host, port }
+    } catch (error) {
+      internalLogger.error('Failed to start Redis Memory Server')
+
+      if (error instanceof Error) {
+        console.error(error.message)
+
+        // Provide helpful suggestions based on common error patterns
+        if (error.message.includes('make') || error.message.includes('compile')) {
+          console.error('\nThis error typically occurs when build tools are missing.')
+          console.error('Please ensure you have "make" and a C compiler installed.')
+        }
+
+        if (process.env.LOG_LEVEL === 'debug' && error.stack) {
+          console.error('\nStack trace:')
+          console.error(error.stack)
+        }
+      }
+
+      console.error('\nAlternative: Use an external Redis server')
+      console.error('  Set MOTIA_DISABLE_MEMORY_SERVER=true')
+      console.error('  Set MOTIA_REDIS_HOST=<your-redis-host>')
+      console.error('  Set MOTIA_REDIS_PORT=<your-redis-port> (default: 6379)')
 
-    return { host, port }
+      throw error
+    }
   }
 
   async stop(): Promise<void> {
     if (this.server && this.running) {
       try {
         await this.server.stop()
       } catch (error: unknown) {
-        console.error('[Redis Memory Server] Error stopping:', (error as Error)?.message)
+        internalLogger.error('Error stopping Redis Memory Server', (error as Error)?.message)
       } finally {
         this.running = false
         this.server = null

packages/snap/src/utils/activate-python-env.ts

@@ -11,6 +11,13 @@ interface VenvConfig {
 
 export const getSitePackagesPath = ({ baseDir, pythonVersion = '3.13' }: VenvConfig): string => {
   const venvPath = path.join(baseDir, 'python_modules')
+
+  // Windows virtualenv layout uses "Lib/site-packages"
+  if (process.platform === 'win32') {
+    return path.join(venvPath, 'Lib', 'site-packages')
+  }
+
+  // Unix-like layout uses "lib/python3.x/site-packages"
   const libPath = path.join(venvPath, 'lib')
   const actualPythonVersionPath = findPythonSitePackagesDir(libPath, pythonVersion)
   return path.join(venvPath, 'lib', actualPythonVersionPath, 'site-packages')

packages/snap/src/utils/build-npm-command.ts

@@ -0,0 +1,58 @@
+import { shouldUseNoBinLinks } from './detect-wsl'
+
+/**
+ * Build an npm install command with appropriate flags for the environment.
+ * Adds --no-bin-links when running in WSL2 on Windows filesystem to prevent
+ * EPERM errors during npm install.
+ *
+ * @param baseCommand - The base npm command (e.g., 'npm install --save' or 'npm install')
+ * @param targetPath - The path where the command will be executed
+ * @returns The command with appropriate flags added
+ */
+export function buildNpmCommand(baseCommand: string, targetPath: string): string {
+  // Only modify npm commands
+  if (!baseCommand.startsWith('npm ')) {
+    return baseCommand
+  }
+
+  // Add --no-bin-links if needed for WSL2 on Windows filesystem
+  if (shouldUseNoBinLinks(targetPath)) {
+    // Insert --no-bin-links after 'npm install' but before any other flags
+    // Handle both 'npm install' and 'npm install --save' patterns
+    if (baseCommand.includes('npm install')) {
+      return baseCommand.replace('npm install', 'npm install --no-bin-links')
+    }
+  }
+
+  return baseCommand
+}
+
+/**
+ * Get install commands for all package managers, with WSL2 compatibility for npm.
+ *
+ * @param targetPath - The path where the command will be executed
+ * @returns Record of package manager to install command
+ */
+export function getInstallCommands(targetPath: string): Record<string, string> {
+  return {
+    npm: buildNpmCommand('npm install', targetPath),
+    yarn: 'yarn install',
+    pnpm: 'pnpm install',
+    bun: 'bun install',
+  }
+}
+
+/**
+ * Get install commands with --save flag for all package managers, with WSL2 compatibility for npm.
+ *
+ * @param targetPath - The path where the command will be executed
+ * @returns Record of package manager to install command
+ */
+export function getInstallSaveCommands(targetPath: string): Record<string, string> {
+  return {
+    npm: buildNpmCommand('npm install --save', targetPath),
+    yarn: 'yarn add',
+    pnpm: 'pnpm add',
+    bun: 'bun add',
+  }
+}