@veloxts/core 0.6.31 → 0.6.52

package/CHANGELOG.md

@@ -1,5 +1,131 @@
 # @veloxts/core
 
+## 0.6.52
+
+### Patch Changes
+
+- feat(mcp): smart CLI resolution with fallbacks
+
+## 0.6.51
+
+### Patch Changes
+
+- fix(web): configure @vinxi/server-functions for RSC server actions
+
+## 0.6.50
+
+### Patch Changes
+
+- lint fixed
+
+## 0.6.49
+
+### Patch Changes
+
+- feat(create): add client import lint script for RSC templates
+
+## 0.6.48
+
+### Patch Changes
+
+- fix(web): remove server-only guards incompatible with Vite SS
+
+## 0.6.47
+
+### Patch Changes
+
+- fix(web): use /adapters for createH3ApiHandler to avoid server-only
+
+## 0.6.46
+
+### Patch Changes
+
+- fix(web): remove transitive server-only import from main entry
+
+## 0.6.45
+
+### Patch Changes
+
+- fix(web): remove server-only guard from main entry for Vinxi compat
+
+## 0.6.44
+
+### Patch Changes
+
+- refactor(web): implement proper RSC server/client separation
+
+## 0.6.43
+
+### Patch Changes
+
+- fix(web): exclude native modules from Vite dependency optimization
+
+## 0.6.42
+
+### Patch Changes
+
+- fix(web): enable tsconfig path aliases for Vite/Vinxi + docs(web): add @public/@internal JSDoc annotations to server actions
+
+## 0.6.41
+
+### Patch Changes
+
+- feat(web): add authAction helper for procedure bridge authentication
+
+## 0.6.40
+
+### Patch Changes
+
+- feat(create): consolidate template styles with unified dark mode design
+
+## 0.6.39
+
+### Patch Changes
+
+- fix RSC client hydration with split layout architecture
+
+## 0.6.38
+
+### Patch Changes
+
+- fix client hydration for RSC templates
+
+## 0.6.37
+
+### Patch Changes
+
+- feat(web): add validated() helper for secure server actions & add rsc-auth template with validated()
+
+## 0.6.36
+
+### Patch Changes
+
+- Gap Remediation Plan
+
+## 0.6.35
+
+### Patch Changes
+
+- proper auth template testing in verify-publis
+
+## 0.6.34
+
+### Patch Changes
+
+- update PostgreSQL adapter for Prisma 7 API
+
+## 0.6.33
+
+### Patch Changes
+
+- changed claude.md instruction, added prisma config
+
+## 0.6.32
+
+### Patch Changes
+
+- Introducing new Ecosystem Expansion packages: cache, queue, mail, storage, scheduler, events. Do not use yet
+
 ## 0.6.31
 
 ### Patch Changes

package/dist/errors/catalog.d.ts

@@ -1,10 +1,14 @@
 /**
  * Error Catalog - Centralized error definitions with fix suggestions
  *
- * Error codes follow the pattern: VELOX-XYYY
- * - X: Domain (1=Core, 2=Router, 3=Auth, 4=ORM, 5=Validation, 6=Client)
+ * Error codes follow the pattern: VELOX-XYYY or VELOX-XXYYY
+ * - X/XX: Domain (1=Core, 2=Router, 3=Auth, 4=ORM, 5=Validation, 6=Client,
+ *                 7=Cache, 8=Queue, 9=Mail, 10=Storage, 11=Scheduler, 12=Events)
  * - YYY: Sequential number within domain
  *
+ * Note: Domains 1-9 use 4-digit codes (e.g., VELOX-1001)
+ *       Domains 10+ use 5-digit codes (e.g., VELOX-10001)
+ *
  * @module errors/catalog
  */
 /**
@@ -17,6 +21,12 @@ export declare const ERROR_DOMAINS: {
     readonly ORM: 4;
     readonly VALIDATION: 5;
     readonly CLIENT: 6;
+    readonly CACHE: 7;
+    readonly QUEUE: 8;
+    readonly MAIL: 9;
+    readonly STORAGE: 10;
+    readonly SCHEDULER: 11;
+    readonly EVENTS: 12;
 };
 export type ErrorDomain = keyof typeof ERROR_DOMAINS;
 /**

package/dist/errors/catalog.js

@@ -1,10 +1,14 @@
 /**
  * Error Catalog - Centralized error definitions with fix suggestions
  *
- * Error codes follow the pattern: VELOX-XYYY
- * - X: Domain (1=Core, 2=Router, 3=Auth, 4=ORM, 5=Validation, 6=Client)
+ * Error codes follow the pattern: VELOX-XYYY or VELOX-XXYYY
+ * - X/XX: Domain (1=Core, 2=Router, 3=Auth, 4=ORM, 5=Validation, 6=Client,
+ *                 7=Cache, 8=Queue, 9=Mail, 10=Storage, 11=Scheduler, 12=Events)
  * - YYY: Sequential number within domain
  *
+ * Note: Domains 1-9 use 4-digit codes (e.g., VELOX-1001)
+ *       Domains 10+ use 5-digit codes (e.g., VELOX-10001)
+ *
  * @module errors/catalog
  */
 // ============================================================================
@@ -20,6 +24,12 @@ export const ERROR_DOMAINS = {
     ORM: 4,
     VALIDATION: 5,
     CLIENT: 6,
+    CACHE: 7,
+    QUEUE: 8,
+    MAIL: 9,
+    STORAGE: 10,
+    SCHEDULER: 11,
+    EVENTS: 12,
 };
 // ============================================================================
 // Error Catalog Registry
@@ -483,6 +493,389 @@ const api = createClient({
         },
         docsUrl: 'https://veloxts.dev/errors/VELOX-6002',
     },
+    // ==========================================================================
+    // CACHE ERRORS (7XXX)
+    // ==========================================================================
+    'VELOX-7001': {
+        code: 'VELOX-7001',
+        title: 'Cache Driver Not Found',
+        description: 'The specified cache driver is not available or not installed.',
+        statusCode: 500,
+        fix: {
+            suggestion: 'Install the required cache driver dependencies.',
+            example: `# For Redis cache
+pnpm add ioredis
+
+# Configure the cache
+app.register(cachePlugin({
+  driver: 'redis',
+  config: { url: process.env.REDIS_URL },
+}));`,
+        },
+        docsUrl: 'https://veloxts.dev/errors/VELOX-7001',
+    },
+    'VELOX-7002': {
+        code: 'VELOX-7002',
+        title: 'Redis Connection Failed',
+        description: 'Could not establish a connection to the Redis server.',
+        statusCode: 503,
+        fix: {
+            suggestion: 'Verify REDIS_URL is correct and the Redis server is running.',
+            example: `# Check your .env file
+REDIS_URL="redis://localhost:6379"
+
+# Or with authentication
+REDIS_URL="redis://:password@localhost:6379"
+
+# Start Redis with Docker
+docker run -d -p 6379:6379 redis:7-alpine`,
+        },
+        docsUrl: 'https://veloxts.dev/errors/VELOX-7002',
+    },
+    'VELOX-7003': {
+        code: 'VELOX-7003',
+        title: 'Cache Key Too Long',
+        description: 'The cache key exceeds the maximum allowed length.',
+        statusCode: 400,
+        fix: {
+            suggestion: 'Use shorter cache keys or hash long keys.',
+            example: `import { createHash } from 'crypto';
+
+// Hash long keys
+function cacheKey(data: string): string {
+  if (data.length > 200) {
+    return createHash('sha256').update(data).digest('hex');
+  }
+  return data;
+}`,
+        },
+        docsUrl: 'https://veloxts.dev/errors/VELOX-7003',
+    },
+    // ==========================================================================
+    // QUEUE ERRORS (8XXX)
+    // ==========================================================================
+    'VELOX-8001': {
+        code: 'VELOX-8001',
+        title: 'Queue Connection Failed',
+        description: 'Could not connect to the queue backend (Redis/BullMQ).',
+        statusCode: 503,
+        fix: {
+            suggestion: 'Verify Redis is running and REDIS_URL is configured.',
+            example: `# Check your .env file
+REDIS_URL="redis://localhost:6379"
+
+# Start Redis
+docker run -d -p 6379:6379 redis:7-alpine
+
+# Configure queue
+app.register(queuePlugin({
+  driver: 'bullmq',
+  config: { connection: { url: process.env.REDIS_URL } },
+}));`,
+        },
+        docsUrl: 'https://veloxts.dev/errors/VELOX-8001',
+    },
+    'VELOX-8002': {
+        code: 'VELOX-8002',
+        title: 'Job Handler Not Found',
+        description: 'No handler is registered for the dispatched job type.',
+        statusCode: 500,
+        fix: {
+            suggestion: 'Register the job handler before dispatching.',
+            example: `// Define the job
+export const sendEmail = defineJob({
+  name: 'email.send',
+  schema: z.object({ to: z.string().email() }),
+  handler: async ({ data }) => {
+    await mailer.send(data.to, 'Hello!');
+  },
+});
+
+// Register with queue
+queue.registerJob(sendEmail);
+
+// Now you can dispatch
+await dispatch(sendEmail, { to: 'user@example.com' });`,
+        },
+        docsUrl: 'https://veloxts.dev/errors/VELOX-8002',
+    },
+    'VELOX-8003': {
+        code: 'VELOX-8003',
+        title: 'Job Execution Failed',
+        description: 'A job failed to execute after all retry attempts.',
+        statusCode: 500,
+        fix: {
+            suggestion: 'Check the job logs for error details. Consider adding error handling.',
+            example: `export const processOrder = defineJob({
+  name: 'order.process',
+  schema: OrderSchema,
+  retries: 3,
+  backoff: { type: 'exponential', delay: 1000 },
+  handler: async ({ data }) => {
+    try {
+      await processOrderLogic(data);
+    } catch (error) {
+      // Log and rethrow for retry
+      console.error('Order processing failed:', error);
+      throw error;
+    }
+  },
+});`,
+        },
+        docsUrl: 'https://veloxts.dev/errors/VELOX-8003',
+    },
+    // ==========================================================================
+    // MAIL ERRORS (9XXX)
+    // ==========================================================================
+    'VELOX-9001': {
+        code: 'VELOX-9001',
+        title: 'SMTP Connection Failed',
+        description: 'Could not connect to the SMTP mail server.',
+        statusCode: 503,
+        fix: {
+            suggestion: 'Verify your SMTP configuration and server availability.',
+            example: `# Check your .env file
+SMTP_HOST="smtp.example.com"
+SMTP_PORT="587"
+SMTP_USER="your-user"
+SMTP_PASS="your-password"
+
+# Configure mail
+app.register(mailPlugin({
+  driver: 'smtp',
+  config: {
+    host: process.env.SMTP_HOST,
+    port: parseInt(process.env.SMTP_PORT),
+    auth: {
+      user: process.env.SMTP_USER,
+      pass: process.env.SMTP_PASS,
+    },
+  },
+}));`,
+        },
+        docsUrl: 'https://veloxts.dev/errors/VELOX-9001',
+    },
+    'VELOX-9002': {
+        code: 'VELOX-9002',
+        title: 'Mail Send Failed',
+        description: 'The email could not be sent due to a delivery error.',
+        statusCode: 500,
+        fix: {
+            suggestion: 'Check the recipient address, email content, and server logs.',
+            example: `try {
+  await mail.send({
+    to: 'user@example.com',
+    subject: 'Hello',
+    html: '<p>Welcome!</p>',
+  });
+} catch (error) {
+  if (error.code === 'VELOX-9002') {
+    // Log the original error for debugging
+    console.error('Mail delivery failed:', error.cause);
+  }
+}`,
+        },
+        docsUrl: 'https://veloxts.dev/errors/VELOX-9002',
+    },
+    'VELOX-9003': {
+        code: 'VELOX-9003',
+        title: 'Invalid Email Address',
+        description: 'One or more email addresses in the message are invalid.',
+        statusCode: 400,
+        fix: {
+            suggestion: 'Validate email addresses before sending.',
+            example: `import { z } from 'zod';
+
+const emailSchema = z.string().email();
+
+// Validate before sending
+const result = emailSchema.safeParse(recipientEmail);
+if (!result.success) {
+  throw new Error('Invalid email address');
+}`,
+        },
+        docsUrl: 'https://veloxts.dev/errors/VELOX-9003',
+    },
+    // ==========================================================================
+    // STORAGE ERRORS (10XXX)
+    // ==========================================================================
+    'VELOX-10001': {
+        code: 'VELOX-10001',
+        title: 'Storage Driver Not Found',
+        description: 'The specified storage driver is not available or not installed.',
+        statusCode: 500,
+        fix: {
+            suggestion: 'Install the required storage driver dependencies.',
+            example: `# For S3 storage
+pnpm add @aws-sdk/client-s3 @aws-sdk/s3-request-presigner
+
+# Configure storage
+app.register(storagePlugin({
+  driver: 's3',
+  config: {
+    bucket: 'my-bucket',
+    region: 'us-east-1',
+  },
+}));`,
+        },
+        docsUrl: 'https://veloxts.dev/errors/VELOX-10001',
+    },
+    'VELOX-10002': {
+        code: 'VELOX-10002',
+        title: 'File Not Found',
+        description: 'The requested file does not exist in storage.',
+        statusCode: 404,
+        fix: {
+            suggestion: 'Verify the file path is correct and the file has been uploaded.',
+            example: `// Check if file exists before reading
+if (await storage.exists('path/to/file.pdf')) {
+  const content = await storage.get('path/to/file.pdf');
+} else {
+  console.log('File not found');
+}`,
+        },
+        docsUrl: 'https://veloxts.dev/errors/VELOX-10002',
+    },
+    'VELOX-10003': {
+        code: 'VELOX-10003',
+        title: 'Storage Permission Denied',
+        description: 'Access to the file or bucket was denied due to permissions.',
+        statusCode: 403,
+        fix: {
+            suggestion: 'Check your storage credentials and bucket/directory permissions.',
+            example: `# For S3, verify IAM permissions include:
+# - s3:GetObject
+# - s3:PutObject
+# - s3:DeleteObject
+# - s3:ListBucket
+
+# For local storage, check directory permissions
+chmod 755 ./storage`,
+        },
+        docsUrl: 'https://veloxts.dev/errors/VELOX-10003',
+    },
+    'VELOX-10004': {
+        code: 'VELOX-10004',
+        title: 'S3 Connection Failed',
+        description: 'Could not connect to the S3-compatible storage service.',
+        statusCode: 503,
+        fix: {
+            suggestion: 'Verify your S3 credentials and endpoint configuration.',
+            example: `# Check your .env file
+AWS_ACCESS_KEY_ID="your-access-key"
+AWS_SECRET_ACCESS_KEY="your-secret-key"
+AWS_REGION="us-east-1"
+S3_BUCKET="your-bucket"
+
+# For S3-compatible services (R2, MinIO)
+S3_ENDPOINT="https://your-endpoint.com"`,
+        },
+        docsUrl: 'https://veloxts.dev/errors/VELOX-10004',
+    },
+    // ==========================================================================
+    // SCHEDULER ERRORS (11XXX)
+    // ==========================================================================
+    'VELOX-11001': {
+        code: 'VELOX-11001',
+        title: 'Task Already Registered',
+        description: 'A scheduled task with the same name is already registered.',
+        statusCode: 500,
+        fix: {
+            suggestion: 'Use unique names for each scheduled task.',
+            example: `// Each task must have a unique name
+const schedule = defineSchedule([
+  task('cleanup-sessions', async () => { ... }).daily().build(),
+  task('cleanup-tokens', async () => { ... }).daily().build(), // Different name
+]);`,
+        },
+        docsUrl: 'https://veloxts.dev/errors/VELOX-11001',
+    },
+    'VELOX-11002': {
+        code: 'VELOX-11002',
+        title: 'Invalid Cron Expression',
+        description: 'The provided cron expression is malformed or invalid.',
+        statusCode: 400,
+        fix: {
+            suggestion: 'Use a valid cron expression or the fluent scheduling API.',
+            example: `// Fluent API (recommended)
+task('my-task', handler)
+  .daily()
+  .at('03:00')
+  .build();
+
+// Or valid cron expression
+task('my-task', handler)
+  .cron('0 3 * * *')  // Every day at 3:00 AM
+  .build();
+
+// Cron format: minute hour day-of-month month day-of-week`,
+        },
+        docsUrl: 'https://veloxts.dev/errors/VELOX-11002',
+    },
+    // ==========================================================================
+    // EVENTS ERRORS (12XXX)
+    // ==========================================================================
+    'VELOX-12001': {
+        code: 'VELOX-12001',
+        title: 'WebSocket Connection Failed',
+        description: 'Could not establish a WebSocket connection.',
+        statusCode: 503,
+        fix: {
+            suggestion: 'Verify the WebSocket endpoint is correct and the server is running.',
+            example: `// Client-side connection
+const socket = new WebSocket('ws://localhost:3000/ws');
+
+socket.onopen = () => console.log('Connected');
+socket.onerror = (error) => console.error('Connection failed:', error);
+
+// Ensure server is configured
+app.register(eventsPlugin({
+  driver: 'ws',
+  path: '/ws',
+}));`,
+        },
+        docsUrl: 'https://veloxts.dev/errors/VELOX-12001',
+    },
+    'VELOX-12002': {
+        code: 'VELOX-12002',
+        title: 'Channel Authorization Failed',
+        description: 'The user is not authorized to subscribe to this channel.',
+        statusCode: 403,
+        fix: {
+            suggestion: 'Implement channel authorization or use public channels.',
+            example: `// Private channel authorization
+app.register(eventsPlugin({
+  driver: 'ws',
+  authorize: async (channel, user) => {
+    // Private channels start with 'private-'
+    if (channel.startsWith('private-user.')) {
+      const userId = channel.replace('private-user.', '');
+      return user?.id === userId;
+    }
+    return true; // Public channels
+  },
+}));`,
+        },
+        docsUrl: 'https://veloxts.dev/errors/VELOX-12002',
+    },
+    'VELOX-12003': {
+        code: 'VELOX-12003',
+        title: 'Redis Pub/Sub Failed',
+        description: 'Could not publish or subscribe to Redis channels.',
+        statusCode: 503,
+        fix: {
+            suggestion: 'Verify Redis is running and configured for the events plugin.',
+            example: `# Check Redis connection
+REDIS_URL="redis://localhost:6379"
+
+# Configure events with Redis for horizontal scaling
+app.register(eventsPlugin({
+  driver: 'ws',
+  redis: process.env.REDIS_URL,  // Enables pub/sub across instances
+}));`,
+        },
+        docsUrl: 'https://veloxts.dev/errors/VELOX-12003',
+    },
 };
 // ============================================================================
 // Catalog Access Functions

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@veloxts/core",
-  "version": "0.6.31",
+  "version": "0.6.52",
   "description": "Fastify wrapper, DI container, and plugin system for VeloxTS framework",
   "type": "module",
   "main": "dist/index.js",