@nlabs/lex 1.48.7 → 1.49.0

package/.storybook/main.ts

@@ -50,9 +50,9 @@ const config = {
                 loader: 'babel-loader',
                 options: {
                   presets: [
-                    '/Users/nitrog7/Development/gothamjs/node_modules/@babel/preset-typescript',
+                    '@babel/preset-typescript',
                     [
-                      '/Users/nitrog7/Development/gothamjs/node_modules/@babel/preset-react',
+                      '@babel/preset-react',
                       {
                         runtime: 'automatic'
                       }
@@ -63,6 +63,13 @@ const config = {
             ]
           }
         ]
+      },
+      resolve: {
+        ...config.resolve,
+        extensions: ['.js', '.ts', '.tsx', '.json', '.mdx'],
+        extensionAlias: {
+          '.js': ['.ts', '.tsx', '.js']
+        }
       }
     };
   }

package/.vscode/settings.json

@@ -6,7 +6,7 @@
     "editor.defaultFormatter": "dbaeumer.vscode-eslint"
   },
   "[typescript]": {
-    "editor.defaultFormatter": "vscode.typescript-language-features"
+    "editor.defaultFormatter": "dbaeumer.vscode-eslint"
   },
   "[typescriptreact]": {
     "editor.defaultFormatter": "dbaeumer.vscode-eslint"
@@ -43,12 +43,7 @@
   "eslint.experimental.useFlatConfig": true,
   "eslint.format.enable": true,
   "eslint.lintTask.enable": true,
-  "eslint.nodePath": "./node_modules",
-  "eslint.options": {
-    "overrideConfigFile": "./eslint.config.js"
-  },
   "eslint.run": "onType",
-  "eslint.runtime": "./node_modules/eslint/bin/eslint.js",
   "eslint.validate": [
     "javascript",
     "javascriptreact",

package/README.md

@@ -142,8 +142,17 @@ lex dev --bundleAnalyzer
 
 # Custom webpack config
 lex dev --config ./custom.webpack.js
+
+# Force refresh cached public IP
+lex dev --usePublicIp
 ```
 
+**🌐 Public IP Caching**: Lex automatically caches your public IP address for 1 week to reduce API calls. Use `--usePublicIp` to force refresh the cache when needed.
+
+**📁 Static Assets**: If your HTML template references static assets (like favicon.ico, manifest.json, or images) with absolute paths, ensure these files exist in your source directory or use relative paths to avoid webpack compilation errors.
+
+**🎨 Public Assets**: Use the `webpack.publicPath` configuration to specify a directory for public assets (images, videos, audio, PDFs, etc.). Files in this directory will be automatically copied to the output and optimized for web delivery.
+
 ### 🏗️ **Production Builds**
 
 ```bash
@@ -270,6 +279,246 @@ export default {
 };
 ```
 
+## 📋 Configuration Options Reference
+
+Lex provides extensive configuration options through the `lex.config.js` file. Here's a comprehensive reference of all available options:
+
+### 🎯 **Project Settings**
+
+| Option | Type | Default | Description | Example |
+|--------|------|---------|-------------|---------|
+| `entryHTML` | `string` | `'index.html'` | HTML template file | `entryHTML: 'app.html'` |
+| `entryJs` | `string` | `'index.js'` | Main JavaScript entry file | `entryJs: 'main.tsx'` |
+| `outputFile` | `string` | `undefined` | Specific output filename | `outputFile: 'bundle.js'` |
+| `outputFullPath` | `string` | `path.resolve('./dist')` | Absolute output path for build artifacts. Used by webpack dev server for static file serving. | `outputFullPath: '/absolute/build'` |
+| `outputHash` | `boolean` | `false` | Add hash to output filenames | `outputHash: true` |
+| `outputPath` | `string` | `'./dist'` | Output directory path | `outputPath: './build'` |
+| `packageManager` | `'npm' \| 'yarn'` | `'npm'` | Package manager to use | `packageManager: 'yarn'` |
+| `preset` | `'web' \| 'node' \| 'lambda' \| 'mobile'` | `'web'` | Project preset type | `preset: 'node'` |
+| `sourceFullPath` | `string` | `path.resolve('./src')` | Absolute source code path | `sourceFullPath: '/absolute/path'` |
+| `sourcePath` | `string` | `'./src'` | Source code directory path | `sourcePath: './app'` |
+| `targetEnvironment` | `'web' \| 'node'` | `'web'` | Target runtime environment | `targetEnvironment: 'node'` |
+| `useGraphQl` | `boolean` | `false` | Enable GraphQL support | `useGraphQl: true` |
+| `useTypescript` | `boolean` | `false` | Enable TypeScript support | `useTypescript: true` |
+
+### 🤖 **AI Configuration**
+
+| Option | Type | Default | Description | Example |
+|--------|------|---------|-------------|---------|
+| `ai.apiKey` | `string` | `undefined` | API key for AI provider | `ai: { apiKey: 'sk-...' }` |
+| `ai.maxTokens` | `number` | `4000` | Maximum tokens for AI responses | `ai: { maxTokens: 8000 }` |
+| `ai.model` | `string` | `'gpt-4o'` | AI model to use | `ai: { model: 'gpt-4' }` |
+| `ai.provider` | `'cursor' \| 'copilot' \| 'openai' \| 'anthropic' \| 'none'` | `'none'` | AI service provider | `ai: { provider: 'openai' }` |
+| `ai.temperature` | `number` | `0.1` | AI response creativity (0-1) | `ai: { temperature: 0.7 }` |
+
+### ⚡ **ESBuild Configuration**
+
+| Option | Type | Default | Description | Example |
+|--------|------|---------|-------------|---------|
+| `esbuild.banner` | `Record<string, string>` | `undefined` | Banner text for output files | `esbuild: { banner: { js: '// My Banner' } }` |
+| `esbuild.define` | `Record<string, string>` | `undefined` | Global variable definitions | `esbuild: { define: { 'process.env.NODE_ENV': '"production"' } }` |
+| `esbuild.drop` | `string[]` | `['console', 'debugger']` | Code to drop in production | `esbuild: { drop: ['console'] }` |
+| `esbuild.entryPoints` | `string[]` | `undefined` | Entry points for ESBuild | `esbuild: { entryPoints: ['src/index.ts'] }` |
+| `esbuild.external` | `string[]` | `undefined` | External dependencies | `esbuild: { external: ['react'] }` |
+| `esbuild.footer` | `Record<string, string>` | `undefined` | Footer text for output files | `esbuild: { footer: { js: '// My Footer' } }` |
+| `esbuild.format` | `'cjs' \| 'esm'` | `undefined` | Output format | `esbuild: { format: 'esm' }` |
+| `esbuild.legalComments` | `'none' \| 'inline' \| 'eof' \| 'linked' \| 'separate'` | `'none'` | Legal comments handling | `esbuild: { legalComments: 'inline' }` |
+| `esbuild.metafile` | `boolean` | `false` | Generate metafile | `esbuild: { metafile: true }` |
+| `esbuild.minify` | `boolean` | `true` | Enable minification | `esbuild: { minify: false }` |
+| `esbuild.outdir` | `string` | `undefined` | Output directory for ESBuild | `esbuild: { outdir: './build' }` |
+| `esbuild.platform` | `'node' \| 'browser'` | `undefined` | Target platform | `esbuild: { platform: 'browser' }` |
+| `esbuild.pure` | `string[]` | `['console.log', 'console.warn', 'console.error']` | Pure function calls | `esbuild: { pure: ['console.log'] }` |
+| `esbuild.sourcemap` | `boolean \| 'inline' \| 'external'` | `false` | Source map generation | `esbuild: { sourcemap: true }` |
+| `esbuild.splitting` | `boolean` | `true` | Enable code splitting | `esbuild: { splitting: false }` |
+| `esbuild.target` | `string` | `undefined` | Target environment | `esbuild: { target: 'es2020' }` |
+| `esbuild.treeShaking` | `boolean` | `true` | Enable tree shaking | `esbuild: { treeShaking: false }` |
+
+### 🧪 **Jest Configuration**
+
+| Option | Type | Default | Description | Example |
+|--------|------|---------|-------------|---------|
+| `jest.extensionsToTreatAsEsm` | `string[]` | `undefined` | Extensions to treat as ES modules | `jest: { extensionsToTreatAsEsm: ['.ts', '.tsx'] }` |
+| `jest.moduleNameMapper` | `Record<string, string>` | `undefined` | Module name mappings | `jest: { moduleNameMapper: { '\\.(css)$': 'identity-obj-proxy' } }` |
+| `jest.preset` | `string` | `undefined` | Jest preset | `jest: { preset: 'ts-jest' }` |
+| `jest.roots` | `string[]` | `undefined` | Test root directories | `jest: { roots: ['<rootDir>/src'] }` |
+| `jest.testEnvironment` | `string` | `undefined` | Test environment | `jest: { testEnvironment: 'jsdom' }` |
+| `jest.transform` | `Record<string, [string, object]>` | `undefined` | Transform configurations | `jest: { transform: { '^.+\\.tsx?$': ['ts-jest'] } }` |
+| `jest.transformIgnorePatterns` | `string[]` | `undefined` | Patterns to ignore in transforms | `jest: { transformIgnorePatterns: ['node_modules'] }` |
+
+### 🔧 **ESLint Configuration**
+
+| Option | Type | Default | Description | Example |
+|--------|------|---------|-------------|---------|
+| `eslint.extends` | `string[]` | `undefined` | ESLint extends configurations | `eslint: { extends: ['@typescript-eslint/recommended'] }` |
+| `eslint.rules` | `Linter.RulesRecord` | `undefined` | ESLint rules | `eslint: { rules: { 'no-console': 'warn' } }` |
+
+### 📦 **Webpack Configuration**
+
+| Option | Type | Default | Description | Example |
+|--------|------|---------|-------------|---------|
+| `webpack.entry` | `string \| string[]` | `undefined` | Webpack entry points | `webpack: { entry: './src/index.js' }` |
+| `webpack.module` | `object` | `undefined` | Webpack module configuration | `webpack: { module: { rules: [...] } }` |
+| `webpack.output` | `object` | `undefined` | Webpack output configuration | `webpack: { output: { filename: 'bundle.js' } }` |
+| `webpack.plugins` | `unknown[]` | `undefined` | Webpack plugins | `webpack: { plugins: [new MyPlugin()] }` |
+| `webpack.publicPath` | `string` | `'./src/static'` | Path to public assets directory. Files in this directory will be copied to the output and optimized (images/videos compressed, audio optimized) | `webpack: { publicPath: './assets' }` |
+
+### 🔗 **Library Configuration**
+
+| Option | Type | Default | Description | Example |
+|--------|------|---------|-------------|---------|
+| `libraryName` | `string` | `undefined` | Library name for UMD builds | `libraryName: 'MyLibrary'` |
+| `libraryTarget` | `string` | `undefined` | Library target format | `libraryTarget: 'umd'` |
+
+### 📁 **File Management**
+
+| Option | Type | Default | Description | Example |
+|--------|------|---------|-------------|---------|
+| `configFiles` | `string[]` | `[]` | Additional config files to include | `configFiles: ['./config/custom.js']` |
+| `copyFiles` | `string[]` | `[]` | Files to copy during build | `copyFiles: ['public/assets']` |
+| `env` | `object` | `null` | Environment variables | `env: { NODE_ENV: 'development' }` |
+| `gitUrl` | `string` | `undefined` | Git repository URL | `gitUrl: 'https://github.com/user/repo'` |
+
+### 📝 **Usage Examples**
+
+#### Basic TypeScript Project
+
+```javascript
+export default {
+  useTypescript: true,
+  sourcePath: './src',
+  outputPath: './dist',
+  preset: 'web',
+  targetEnvironment: 'web'
+};
+```
+
+#### Node.js Library
+
+```javascript
+export default {
+  useTypescript: true,
+  preset: 'node',
+  targetEnvironment: 'node',
+  libraryName: 'MyLibrary',
+  libraryTarget: 'umd',
+  esbuild: {
+    format: 'cjs',
+    platform: 'node',
+    external: ['lodash']
+  }
+};
+```
+
+#### AI-Powered Development
+
+```javascript
+export default {
+  useTypescript: true,
+  ai: {
+    provider: 'openai',
+    apiKey: process.env.OPENAI_API_KEY,
+    model: 'gpt-4',
+    maxTokens: 8000,
+    temperature: 0.3
+  },
+  jest: {
+    testEnvironment: 'jsdom',
+    setupFilesAfterEnv: ['./src/setupTests.ts']
+  }
+};
+```
+
+#### Advanced ESBuild Configuration
+
+```javascript
+export default {
+  useTypescript: true,
+  esbuild: {
+    minify: true,
+    sourcemap: 'inline',
+    target: 'es2020',
+    format: 'esm',
+    splitting: true,
+    metafile: true,
+    define: {
+      'process.env.NODE_ENV': '"production"',
+      'global': 'globalThis'
+    },
+    banner: {
+      js: '// My Awesome Library v1.0.0'
+    }
+  }
+};
+```
+
+## 🚨 Troubleshooting
+
+### Common Issues
+
+#### 404 Error with "Static Paths" Message
+
+If you see a 404 error with a message like "Static Paths /path/to/dist", this is likely because the webpack dev server is trying to serve static files from a directory that doesn't exist yet.
+
+**Solution**: The `outputFullPath` directory should exist before starting the dev server. You can:
+
+- Run `lex build` first to create the output directory
+- Or ensure your `outputPath` configuration points to an existing directory
+
+#### Port Already in Use
+
+If you get an "address already in use" error, another process is using the default port (7001).
+
+**Solution**: Kill the existing process or use a different port:
+
+```bash
+# Kill processes on port 7001
+lsof -ti:7001 | xargs kill -9
+
+# Or use a different port
+lex dev --port 3000
+```
+
+#### TypeScript Configuration Issues
+
+If TypeScript compilation fails, ensure your `tsconfig.json` is properly configured.
+
+**Solution**: Check that your `tsconfig.json` includes the correct paths:
+
+```json
+{
+  "compilerOptions": {
+    "outDir": "./dist",
+    "rootDir": "./src"
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}
+```
+
+#### Missing Static Assets Error
+
+If you see webpack compilation errors about missing static assets (like favicon.ico, manifest.json, or images), this is because your HTML template references files that don't exist.
+
+**Solution**: Either create the missing files or update your HTML template to use relative paths:
+
+```html
+<!-- Instead of absolute paths -->
+<link rel="icon" href="/favicon.ico" />
+<link rel="manifest" href="/manifest.json" />
+
+<!-- Use relative paths -->
+<link rel="icon" href="favicon.ico" />
+<link rel="manifest" href="manifest.json" />
+```
+
+Or create the missing files in your source directory:
+
+```bash
+touch src/favicon.ico
+touch src/manifest.json
+mkdir -p src/images && touch src/images/logo-icon-64.png
+```
+
 ## 📚 Documentation
 
 - 📖 **[Full Documentation](http://lex.nitrogenlabs.com)** - Complete API reference

package/eslint.config.mjs

@@ -0,0 +1,24 @@
+import {typescriptConfig} from 'eslint-config-styleguidejs';
+
+export default [
+  ...typescriptConfig,
+  {
+    rules: {
+      'keyword-spacing': ['error', {
+        after: true,
+        before: true,
+        overrides: {
+          for: {after: false},
+          if: {after: false},
+          switch: {after: false},
+          while: {after: false}
+        }
+      }],
+      'space-before-blocks': ['error', {
+        classes: 'always',
+        functions: 'always',
+        keywords: 'always'
+      }]
+    }
+  }
+];

package/examples/lex.config.js

@@ -7,32 +7,42 @@ export default {
   // Source and output paths
   sourcePath: './src',
   outputPath: './dist',
-  
+
   // Project settings
   useTypescript: true,
   targetEnvironment: 'web',
   preset: 'web',
-  
+
   // AI configuration
   // Use this section to configure AI features for lint --fix and ai commands
   ai: {
     // Available providers: 'cursor', 'copilot', 'openai', 'anthropic', 'none'
     provider: 'cursor',
-    
+
     // API key for external providers (recommended to use environment variables)
     // apiKey: process.env.OPENAI_API_KEY,
-    
+
     // Model configuration (specific to each provider)
     model: 'cursor-code', // For Cursor IDE
     // model: 'copilot-codex', // For GitHub Copilot
     // model: 'gpt-4o', // For OpenAI
     // model: 'claude-3-sonnet', // For Anthropic
-    
+
     // Optional parameters
     maxTokens: 4000,
     temperature: 0.1
   },
-  
+
+  // Webpack configuration
+  webpack: {
+    // Path to public assets directory (defaults to './src/static')
+    publicPath: './src/static',
+
+    // Other webpack configuration options
+    devtool: 'source-map',
+    plugins: []
+  },
+
   // Build configuration
   esbuild: {
     entryPoints: ['src/index.ts'],
@@ -41,10 +51,10 @@ export default {
     target: 'es2020',
     format: 'esm'
   },
-  
+
   // Test configuration
   jest: {
     roots: ['<rootDir>/src'],
     testEnvironment: 'node'
   }
-}; 
+};

package/examples/serverless-example/README.md

@@ -0,0 +1,109 @@
+# Serverless Example
+
+This example demonstrates how to use the `lex serverless` command to run AWS Lambda functions locally with HTTP and WebSocket support.
+
+## Setup
+
+1. Navigate to this directory:
+
+```bash
+cd examples/serverless-example
+```
+
+2. Start the serverless development server:
+
+```bash
+lex serverless
+```
+
+## Available Endpoints
+
+### HTTP Endpoints
+
+- **GET /hello** - Returns a hello message with request details
+- **POST /echo** - Echoes back the request body
+
+### WebSocket Endpoint
+
+- **ws://localhost:3002** - WebSocket server for real-time communication
+
+## Testing the Endpoints
+
+### HTTP Testing
+
+```bash
+# Test GET endpoint
+curl http://localhost:3000/hello
+
+# Test POST endpoint
+curl -X POST http://localhost:3000/echo \
+  -H "Content-Type: application/json" \
+  -d '{"message": "Hello from curl!"}'
+```
+
+### WebSocket Testing
+
+You can use a WebSocket client or browser console:
+
+```javascript
+// In browser console
+const ws = new WebSocket('ws://localhost:3002');
+ws.onopen = () => {
+  console.log('Connected to WebSocket');
+  ws.send(JSON.stringify({
+    action: '$default',
+    body: 'Hello from WebSocket!'
+  }));
+};
+ws.onmessage = (event) => {
+  console.log('Received:', JSON.parse(event.data));
+};
+```
+
+## Configuration
+
+The serverless configuration is defined in `lex.config.mjs`:
+
+```javascript
+export default {
+  outputFullPath: './dist',
+  serverless: {
+    functions: {
+      hello: {
+        handler: 'handlers/hello.js',
+        events: [
+          {
+            http: {
+              path: '/hello',
+              method: 'GET',
+              cors: true
+            }
+          }
+        ]
+      }
+    },
+    custom: {
+      'serverless-offline': {
+        httpPort: 3000,
+        wsPort: 3002,
+        host: 'localhost'
+      }
+    }
+  }
+};
+```
+
+## Handler Functions
+
+Handler functions receive AWS Lambda-style event and context objects:
+
+- **event**: Contains request data (HTTP method, path, headers, body, etc.)
+- **context**: Contains Lambda context information (function name, request ID, etc.)
+
+## Features
+
+- **HTTP Server**: Routes HTTP requests to appropriate Lambda functions
+- **WebSocket Server**: Handles WebSocket connections and messages
+- **CORS Support**: Automatic CORS headers for cross-origin requests
+- **Dynamic Loading**: Loads handlers from the output directory
+- **AWS Lambda Simulation**: Provides event and context objects similar to AWS Lambda

package/examples/serverless-example/dist/handlers/echo.js

@@ -0,0 +1,15 @@
+export const handler = async (event, context) => {
+  return {
+    statusCode: 200,
+    headers: {
+      'Content-Type': 'application/json'
+    },
+    body: JSON.stringify({
+      message: 'Echo response',
+      receivedData: event.body,
+      path: event.path,
+      method: event.httpMethod,
+      timestamp: new Date().toISOString()
+    })
+  };
+};

package/examples/serverless-example/dist/handlers/graphql.js

@@ -0,0 +1,137 @@
+export const handler = async (event, context) => {
+  console.log('GraphQL handler started');
+  console.log('Event:', JSON.stringify(event, null, 2));
+
+  // Simulate GraphQL resolver logic
+  const resolvers = {
+    Query: {
+      hello: () => {
+        console.log('Resolver: hello called');
+        return 'Hello from GraphQL!';
+      },
+      users: () => {
+        console.log('Resolver: users called');
+        return [
+          { id: 1, name: 'John Doe', email: 'john@example.com' },
+          { id: 2, name: 'Jane Smith', email: 'jane@example.com' }
+        ];
+      }
+    },
+    Mutation: {
+      signUp: (_, args) => {
+        const user = args.user;
+        console.log('Resolver: signUp called with user:', user);
+        console.log('Processing signup for:', user.email);
+
+        // Simulate some processing
+        const userId = Math.floor(Math.random() * 1000);
+        console.log('Generated user ID:', userId);
+
+        return {
+          userId,
+          username: user.username,
+          email: user.email
+        };
+      }
+    }
+  };
+
+  try {
+    // Parse the GraphQL request
+    const body = JSON.parse(event.body);
+    console.log('GraphQL Query:', body.query);
+    console.log('GraphQL Variables:', body.variables);
+
+    // Simulate GraphQL execution
+    if (body.query.includes('signUp')) {
+      console.log('Executing signUp mutation');
+      // Extract user data from the query since we're not using a real GraphQL parser
+      const userMatch = body.query.match(/signUp\(user:\s*{([^}]+)}\)/);
+      if (userMatch) {
+        const userData = userMatch[1];
+        const emailMatch = userData.match(/email:\s*"([^"]+)"/);
+        const passwordMatch = userData.match(/password:\s*"([^"]+)"/);
+        const usernameMatch = userData.match(/username:\s*"([^"]+)"/);
+        const confirmMatch = userData.match(/confirm:\s*"([^"]+)"/);
+
+        const user = {
+          email: emailMatch ? emailMatch[1] : '',
+          password: passwordMatch ? passwordMatch[1] : '',
+          username: usernameMatch ? usernameMatch[1] : '',
+          confirm: confirmMatch ? confirmMatch[1] : ''
+        };
+
+        const result = resolvers.Mutation.signUp(null, { user });
+        console.log('SignUp result:', result);
+
+        return {
+          statusCode: 200,
+          headers: {
+            'Content-Type': 'application/json'
+          },
+          body: JSON.stringify({
+            data: {
+              users: {
+                signUp: result
+              }
+            }
+          })
+        };
+      }
+    } else if (body.query.includes('hello')) {
+      console.log('Executing hello query');
+      const result = resolvers.Query.hello();
+      console.log('Hello result:', result);
+
+      return {
+        statusCode: 200,
+        headers: {
+          'Content-Type': 'application/json'
+        },
+        body: JSON.stringify({
+          data: {
+            hello: result
+          }
+        })
+      };
+    } else if (body.query.includes('users')) {
+      console.log('Executing users query');
+      const result = resolvers.Query.users();
+      console.log('Users result:', result);
+
+      return {
+        statusCode: 200,
+        headers: {
+          'Content-Type': 'application/json'
+        },
+        body: JSON.stringify({
+          data: {
+            users: result
+          }
+        })
+      };
+    }
+
+    console.log('No matching query found');
+    return {
+      statusCode: 400,
+      headers: {
+        'Content-Type': 'application/json'
+      },
+      body: JSON.stringify({
+        errors: [{ message: 'Query not supported' }]
+      })
+    };
+  } catch (error) {
+    console.error('GraphQL handler error:', error);
+    return {
+      statusCode: 500,
+      headers: {
+        'Content-Type': 'application/json'
+      },
+      body: JSON.stringify({
+        errors: [{ message: error.message }]
+      })
+    };
+  }
+};

package/examples/serverless-example/dist/handlers/hello.js

@@ -0,0 +1,15 @@
+export const handler = async (event, context) => {
+  return {
+    statusCode: 200,
+    headers: {
+      'Content-Type': 'application/json'
+    },
+    body: JSON.stringify({
+      message: 'Hello from serverless!',
+      path: event.path,
+      method: event.httpMethod,
+      queryParams: event.queryStringParameters,
+      timestamp: new Date().toISOString()
+    })
+  };
+};