ci: Bump version to 0.0.28 [skip ci]

.gitea/workflows/deploy-to-prod.yml

@@ -47,6 +47,19 @@ jobs:
       - name: Install Dependencies
         run: npm ci
 
+      - name: Bump Minor Version and Push
+        run: |
+          # Configure git for the commit.
+          git config --global user.name 'Gitea Actions'
+          git config --global user.email 'actions@gitea.projectium.com'
+
+          # Bump the minor version number. This creates a new commit and a new tag.
+          # The commit message includes [skip ci] to prevent this push from triggering another workflow run.
+          npm version minor -m "ci: Bump version to %s for production release [skip ci]"
+
+          # Push the new commit and the new tag back to the main branch.
+          git push --follow-tags
+
       - name: Check for Production Database Schema Changes
         env:
           DB_HOST: ${{ secrets.DB_HOST }}
@@ -61,9 +74,10 @@ jobs:
           echo "--- Checking for production schema changes ---"
           CURRENT_HASH=$(cat sql/master_schema_rollup.sql | dos2unix | sha256sum | awk '{ print $1 }')
           echo "Current Git Schema Hash: $CURRENT_HASH"
-          DEPLOYED_HASH=$(PGPASSWORD="$DB_PASSWORD" psql -v ON_ERROR_STOP=1 -h "$DB_HOST" -p 5432 -U "$DB_USER" -d "$DB_NAME" -c "SELECT schema_hash FROM public.schema_info WHERE environment = 'production';" -t -A || echo "none")
+          # The psql command will now fail the step if the query errors (e.g., column missing), preventing deployment on a bad schema.
+          DEPLOYED_HASH=$(PGPASSWORD="$DB_PASSWORD" psql -v ON_ERROR_STOP=1 -h "$DB_HOST" -p 5432 -U "$DB_USER" -d "$DB_NAME" -c "SELECT schema_hash FROM public.schema_info WHERE environment = 'production';" -t -A)
           echo "Deployed DB Schema Hash: $DEPLOYED_HASH"
-          if [ "$DEPLOYED_HASH" = "none" ] || [ -z "$DEPLOYED_HASH" ]; then
+          if [ -z "$DEPLOYED_HASH" ]; then
             echo "WARNING: No schema hash found in the production database. This is expected for a first-time deployment."
           elif [ "$CURRENT_HASH" != "$DEPLOYED_HASH" ]; then
             echo "ERROR: Database schema mismatch detected! A manual database migration is required."

.gitea/workflows/deploy-to-test.yml

@@ -143,9 +143,9 @@ jobs:
           npm run test:integration -- --coverage --reporter=verbose --includeTaskLocation --testTimeout=10000 --silent=passed-only || true
 
           echo "--- Running E2E Tests ---"
-          # Run E2E tests using the integration config (for DB setup) but output coverage separately.
-          # We increase timeout significantly (120s) for E2E flows that involve AI processing.
-          npx vitest run src/tests/e2e --config vitest.config.integration.ts --coverage --coverage.reportsDirectory=.coverage/e2e --reporter=verbose --testTimeout=120000 --no-file-parallelism || true
+          # Run E2E tests using the dedicated E2E config which inherits from integration config.
+          # We still pass --coverage to enable it, but directory and timeout are now in the config.
+          npx vitest run --config vitest.config.e2e.ts --coverage --reporter=verbose --no-file-parallelism || true
 
           # Re-enable secret masking for subsequent steps.
           echo "::secret-masking::"
@@ -264,16 +264,14 @@ jobs:
           # We normalize line endings to ensure the hash is consistent across different OS environments.
           CURRENT_HASH=$(cat sql/master_schema_rollup.sql | dos2unix | sha256sum | awk '{ print $1 }')
           echo "Current Git Schema Hash: $CURRENT_HASH"
-
           # Query the production database to get the hash of the deployed schema.
           # The `psql` command requires PGPASSWORD to be set.
           # `\t` sets tuples-only mode and `\A` unaligns output to get just the raw value.
-          # The `|| echo "none"` ensures the command doesn't fail if the table or row doesn't exist yet.          
-          DEPLOYED_HASH=$(PGPASSWORD="$DB_PASSWORD" psql -v ON_ERROR_STOP=1 -h "$DB_HOST" -p 5432 -U "$DB_USER" -d "$DB_NAME" -c "SELECT schema_hash FROM public.schema_info WHERE environment = 'test';" -t -A || echo "none")
+          # The psql command will now fail the step if the query errors (e.g., column missing), preventing deployment on a bad schema.
+          DEPLOYED_HASH=$(PGPASSWORD="$DB_PASSWORD" psql -v ON_ERROR_STOP=1 -h "$DB_HOST" -p 5432 -U "$DB_USER" -d "$DB_NAME" -c "SELECT schema_hash FROM public.schema_info WHERE environment = 'test';" -t -A)
           echo "Deployed DB Schema Hash: $DEPLOYED_HASH"
-
           # Check if the hash is "none" (command failed) OR if it's an empty string (table exists but is empty).
-          if [ "$DEPLOYED_HASH" = "none" ] || [ -z "$DEPLOYED_HASH" ]; then
+          if [ -z "$DEPLOYED_HASH" ]; then
             echo "WARNING: No schema hash found in the test database."
             echo "This is expected for a first-time deployment. The hash will be set after a successful deployment."
             # We allow the deployment to continue, but a manual schema update is required.

.gitea/workflows/manual-deploy-major.yml

@@ -0,0 +1,180 @@
+# .gitea/workflows/manual-deploy-major.yml
+#
+# This workflow provides a MANUAL trigger to perform a MAJOR version bump
+# and deploy the application to the PRODUCTION environment.
+name: Manual - Deploy Major Version to Production
+
+on:
+  workflow_dispatch:
+    inputs:
+      confirmation:
+        description: 'Type "deploy-major-to-prod" to confirm you want to deploy a new major version.'
+        required: true
+        default: 'do-not-run'
+      force_reload:
+        description: 'Force PM2 reload even if version matches (true/false).'
+        required: false
+        type: boolean
+        default: false
+
+jobs:
+  deploy-production-major:
+    runs-on: projectium.com
+
+    steps:
+      - name: Verify Confirmation Phrase
+        run: |
+          if [ "${{ gitea.event.inputs.confirmation }}" != "deploy-major-to-prod" ]; then
+            echo "ERROR: Confirmation phrase did not match. Aborting deployment."
+            exit 1
+          fi
+          echo "✅ Confirmation accepted. Proceeding with major version production deployment."
+
+      - name: Checkout Code from 'main' branch
+        uses: actions/checkout@v3
+        with:
+          ref: 'main' # Explicitly check out the main branch for production deployment
+          fetch-depth: 0
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v3
+        with:
+          node-version: '20'
+          cache: 'npm'
+          cache-dependency-path: '**/package-lock.json'
+
+      - name: Install Dependencies
+        run: npm ci
+
+      - name: Bump Major Version and Push
+        run: |
+          # Configure git for the commit.
+          git config --global user.name 'Gitea Actions'
+          git config --global user.email 'actions@gitea.projectium.com'
+
+          # Bump the major version number. This creates a new commit and a new tag.
+          # The commit message includes [skip ci] to prevent this push from triggering another workflow run.
+          npm version major -m "ci: Bump version to %s for major release [skip ci]"
+
+          # Push the new commit and the new tag back to the main branch.
+          git push --follow-tags
+
+      - name: Check for Production Database Schema Changes
+        env:
+          DB_HOST: ${{ secrets.DB_HOST }}
+          DB_USER: ${{ secrets.DB_USER }}
+          DB_PASSWORD: ${{ secrets.DB_PASSWORD }}
+          DB_NAME: ${{ secrets.DB_DATABASE_PROD }}
+        run: |
+          if [ -z "$DB_HOST" ] || [ -z "$DB_USER" ] || [ -z "$DB_PASSWORD" ] || [ -z "$DB_NAME" ]; then
+            echo "ERROR: One or more production database secrets (DB_HOST, DB_USER, DB_PASSWORD, DB_DATABASE_PROD) are not set."
+            exit 1
+          fi
+          echo "--- Checking for production schema changes ---"
+          CURRENT_HASH=$(cat sql/master_schema_rollup.sql | dos2unix | sha256sum | awk '{ print $1 }')
+          echo "Current Git Schema Hash: $CURRENT_HASH"
+          # The psql command will now fail the step if the query errors (e.g., column missing), preventing deployment on a bad schema.
+          DEPLOYED_HASH=$(PGPASSWORD="$DB_PASSWORD" psql -v ON_ERROR_STOP=1 -h "$DB_HOST" -p 5432 -U "$DB_USER" -d "$DB_NAME" -c "SELECT schema_hash FROM public.schema_info WHERE environment = 'production';" -t -A)
+          echo "Deployed DB Schema Hash: $DEPLOYED_HASH"
+          if [ -z "$DEPLOYED_HASH" ]; then
+            echo "WARNING: No schema hash found in the production database. This is expected for a first-time deployment."
+          elif [ "$CURRENT_HASH" != "$DEPLOYED_HASH" ]; then
+            echo "ERROR: Database schema mismatch detected! A manual database migration is required."
+            exit 1
+          else
+            echo "✅ Schema is up to date. No changes detected."
+          fi
+
+      - name: Build React Application for Production
+        run: |
+          if [ -z "${{ secrets.VITE_GOOGLE_GENAI_API_KEY }}" ]; then
+            echo "ERROR: The VITE_GOOGLE_GENAI_API_KEY secret is not set."
+            exit 1
+          fi
+          GITEA_SERVER_URL="https://gitea.projectium.com"
+          COMMIT_MESSAGE=$(git log -1 --pretty=%s)
+          VITE_APP_VERSION="$(date +'%Y%m%d-%H%M'):$(git rev-parse --short HEAD)" \
+          VITE_APP_COMMIT_URL="$GITEA_SERVER_URL/${{ gitea.repository }}/commit/${{ gitea.sha }}" \
+          VITE_APP_COMMIT_MESSAGE="$COMMIT_MESSAGE" \
+          VITE_API_BASE_URL=/api VITE_API_KEY=${{ secrets.VITE_GOOGLE_GENAI_API_KEY }} npm run build
+
+      - name: Deploy Application to Production Server
+        run: |
+          echo "Deploying application files to /var/www/flyer-crawler.projectium.com..."
+          APP_PATH="/var/www/flyer-crawler.projectium.com"
+          mkdir -p "$APP_PATH"
+          mkdir -p "$APP_PATH/flyer-images/icons" "$APP_PATH/flyer-images/archive"
+          rsync -avz --delete --exclude 'node_modules' --exclude '.git' --exclude 'dist' --exclude 'flyer-images' ./ "$APP_PATH/"
+          rsync -avz dist/ "$APP_PATH"
+          echo "Application deployment complete."
+
+      - name: Install Backend Dependencies and Restart Production Server
+        env:
+          # --- Production Secrets Injection ---
+          DB_HOST: ${{ secrets.DB_HOST }}
+          DB_USER: ${{ secrets.DB_USER }}
+          DB_PASSWORD: ${{ secrets.DB_PASSWORD }}
+          DB_NAME: ${{ secrets.DB_DATABASE_PROD }}
+          REDIS_URL: 'redis://localhost:6379'
+          REDIS_PASSWORD: ${{ secrets.REDIS_PASSWORD_PROD }}
+          FRONTEND_URL: 'https://flyer-crawler.projectium.com'
+          JWT_SECRET: ${{ secrets.JWT_SECRET }}
+          GEMINI_API_KEY: ${{ secrets.VITE_GOOGLE_GENAI_API_KEY }}
+          GOOGLE_MAPS_API_KEY: ${{ secrets.GOOGLE_MAPS_API_KEY }}
+          SMTP_HOST: 'localhost'
+          SMTP_PORT: '1025'
+          SMTP_SECURE: 'false'
+          SMTP_USER: ''
+          SMTP_PASS: ''
+          SMTP_FROM_EMAIL: 'noreply@flyer-crawler.projectium.com'
+        run: |
+          if [ -z "$DB_HOST" ] || [ -z "$DB_USER" ] || [ -z "$DB_PASSWORD" ] || [ -z "$DB_NAME" ]; then
+            echo "ERROR: One or more production database secrets (DB_HOST, DB_USER, DB_PASSWORD, DB_DATABASE_PROD) are not set."
+            exit 1
+          fi
+          echo "Installing production dependencies and restarting server..."
+          cd /var/www/flyer-crawler.projectium.com
+          npm install --omit=dev
+
+          # --- Version Check Logic ---
+          # Get the version from the newly deployed package.json
+          NEW_VERSION=$(node -p "require('./package.json').version")
+          echo "Deployed Package Version: $NEW_VERSION"
+
+          # Get the running version from PM2 for the main API process
+          # We use a small node script to parse the JSON output from pm2 jlist
+          RUNNING_VERSION=$(pm2 jlist | node -e "try { const list = JSON.parse(require('fs').readFileSync(0, 'utf-8')); const app = list.find(p => p.name === 'flyer-crawler-api'); console.log(app ? app.pm2_env.version : ''); } catch(e) { console.log(''); }")
+          echo "Running PM2 Version: $RUNNING_VERSION"
+
+          if [ "${{ gitea.event.inputs.force_reload }}" == "true" ] || [ "$NEW_VERSION" != "$RUNNING_VERSION" ] || [ -z "$RUNNING_VERSION" ]; then
+            if [ "${{ gitea.event.inputs.force_reload }}" == "true" ]; then
+              echo "Force reload triggered by manual input. Reloading PM2..."
+            else
+              echo "Version mismatch (Running: $RUNNING_VERSION -> Deployed: $NEW_VERSION) or app not running. Reloading PM2..."
+            fi
+            pm2 startOrReload ecosystem.config.cjs --env production && pm2 save
+            echo "Production backend server reloaded successfully."
+          else
+            echo "Version $NEW_VERSION is already running. Skipping PM2 reload."
+          fi
+
+          echo "Updating schema hash in production database..."
+          CURRENT_HASH=$(cat sql/master_schema_rollup.sql | dos2unix | sha256sum | awk '{ print $1 }')
+          PGPASSWORD="$DB_PASSWORD" psql -v ON_ERROR_STOP=1 -h "$DB_HOST" -p 5432 -U "$DB_USER" -d "$DB_NAME" -c \
+          "INSERT INTO public.schema_info (environment, schema_hash, deployed_at) VALUES ('production', '$CURRENT_HASH', NOW())
+           ON CONFLICT (environment) DO UPDATE SET schema_hash = EXCLUDED.schema_hash, deployed_at = NOW();"
+
+          UPDATED_HASH=$(PGPASSWORD="$DB_PASSWORD" psql -v ON_ERROR_STOP=1 -h "$DB_HOST" -p 5432 -U "$DB_USER" -d "$DB_NAME" -c "SELECT schema_hash FROM public.schema_info WHERE environment = 'production';" -t -A)
+          if [ "$CURRENT_HASH" = "$UPDATED_HASH" ]; then
+            echo "✅ Schema hash successfully updated in the database to: $UPDATED_HASH"
+          else
+            echo "ERROR: Failed to update schema hash in the database."
+          fi
+
+      - name: Show PM2 Environment for Production
+        run: |
+          echo "--- Displaying recent PM2 logs for flyer-crawler-api ---"
+          sleep 5
+          pm2 describe flyer-crawler-api || echo "Could not find production pm2 process."
+          pm2 logs flyer-crawler-api --lines 20 --nostream || echo "Could not find production pm2 process."
+          pm2 env flyer-crawler-api || echo "Could not find production pm2 process."

package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "flyer-crawler",
-  "version": "0.0.25",
+  "version": "0.0.28",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "flyer-crawler",
-      "version": "0.0.25",
+      "version": "0.0.28",
       "dependencies": {
         "@bull-board/api": "^6.14.2",
         "@bull-board/express": "^6.14.2",

package.json

@@ -1,7 +1,7 @@
 {
   "name": "flyer-crawler",
   "private": true,
-  "version": "0.0.25",
+  "version": "0.0.28",
   "type": "module",
   "scripts": {
     "dev": "concurrently \"npm:start:dev\" \"vite\"",

src/routes/ai.routes.test.ts

@@ -353,10 +353,11 @@ describe('AI Routes (/api/ai)', () => {
       expect(response.status).toBe(400);
     });
 
-    it('should return 409 Conflict if flyer checksum already exists', async () => {
+    it('should return 409 Conflict and delete the uploaded file if flyer checksum already exists', async () => {
       // Arrange
       const mockExistingFlyer = createMockFlyer({ flyer_id: 99 });
       vi.mocked(mockedDb.flyerRepo.findFlyerByChecksum).mockResolvedValue(mockExistingFlyer); // Duplicate found
+      const unlinkSpy = vi.spyOn(fs.promises, 'unlink').mockResolvedValue(undefined);
 
       // Act
       const response = await supertest(app)
@@ -368,6 +369,10 @@ describe('AI Routes (/api/ai)', () => {
       expect(response.status).toBe(409);
       expect(response.body.message).toBe('This flyer has already been processed.');
       expect(mockedDb.createFlyerAndItems).not.toHaveBeenCalled();
+      // Assert that the file was deleted
+      expect(unlinkSpy).toHaveBeenCalledTimes(1);
+      // The filename is predictable in the test environment because of the multer config in ai.routes.ts
+      expect(unlinkSpy).toHaveBeenCalledWith(expect.stringContaining('flyerImage-test-flyer-image.jpg'));
     });
 
     it('should accept payload when extractedData.items is missing and save with empty items', async () => {

src/routes/ai.routes.ts

@@ -50,6 +50,15 @@ const errMsg = (e: unknown) => {
   return String(e || 'An unknown error occurred.');
 };
 
+const cleanupUploadedFile = async (file?: Express.Multer.File) => {
+  if (!file) return;
+  try {
+    await fs.promises.unlink(file.path);
+  } catch (err) {
+    // Ignore cleanup errors (e.g. file already deleted)
+  }
+};
+
 const cropAreaObjectSchema = z.object({
   x: z.number(),
   y: z.number(),
@@ -185,7 +194,7 @@ router.use((req: Request, res: Response, next: NextFunction) => {
       '[API /ai] Incoming request',
     );
   } catch (e: unknown) {
-    logger.error({ error: e }, 'Failed to log incoming AI request headers');
+    logger.error({ error: errMsg(e) }, 'Failed to log incoming AI request headers');
   }
   next();
 });
@@ -316,7 +325,7 @@ router.post(
 
       // Try several ways to obtain the payload so we are tolerant to client variations.
       let parsed: FlyerProcessPayload = {};
-      let extractedData: Partial<ExtractedCoreData> = {};
+      let extractedData: Partial<ExtractedCoreData> | null | undefined = {};
       try {
         // If the client sent a top-level `data` field (stringified JSON), parse it.
         if (req.body && (req.body.data || req.body.extractedData)) {
@@ -337,7 +346,7 @@ router.post(
             ) as FlyerProcessPayload;
           }
           // If parsed itself contains an `extractedData` field, use that, otherwise assume parsed is the extractedData
-          extractedData = parsed.extractedData ?? (parsed as Partial<ExtractedCoreData>);
+          extractedData = 'extractedData' in parsed ? parsed.extractedData : (parsed as Partial<ExtractedCoreData>);
         } else {
           // No explicit `data` field found. Attempt to interpret req.body as an object (Express may have parsed multipart fields differently).
           try {
@@ -383,6 +392,12 @@ router.post(
 
       // Pull common metadata fields (checksum, originalFileName) from whichever shape we parsed.
       const checksum = parsed.checksum ?? parsed?.data?.checksum ?? '';
+
+      if (!checksum) {
+        await cleanupUploadedFile(req.file);
+        return res.status(400).json({ message: 'Checksum is required.' });
+      }
+
       const originalFileName =
         parsed.originalFileName ?? parsed?.data?.originalFileName ?? req.file.originalname;
       const userProfile = req.user as UserProfile | undefined;
@@ -429,6 +444,7 @@ router.post(
       const existingFlyer = await db.flyerRepo.findFlyerByChecksum(checksum, req.log);
       if (existingFlyer) {
         logger.warn(`Duplicate flyer upload attempt blocked for checksum: ${checksum}`);
+        await cleanupUploadedFile(req.file);
         return res.status(409).json({ message: 'This flyer has already been processed.' });
       }
 
@@ -476,6 +492,7 @@ router.post(
 
       res.status(201).json({ message: 'Flyer processed and saved successfully.', flyer: newFlyer });
     } catch (error) {
+      await cleanupUploadedFile(req.file);
       next(error);
     }
   },

src/routes/price.routes.test.ts

@@ -96,7 +96,8 @@ describe('Price Routes (/api/price-history)', () => {
         .send({ masterItemIds: 'not-an-array' });
 
       expect(response.status).toBe(400);
-      expect(response.body.errors[0].message).toContain('Expected array, received string');
+      // The actual message is "Invalid input: expected array, received string"
+      expect(response.body.errors[0].message).toBe('Invalid input: expected array, received string');
     });
 
     it('should return 400 if masterItemIds contains non-positive integers', async () => {
@@ -112,7 +113,8 @@ describe('Price Routes (/api/price-history)', () => {
       const response = await supertest(app).post('/api/price-history').send({});
 
       expect(response.status).toBe(400);
-      expect(response.body.errors[0].message).toBe('Required');
+      // The actual message is "Invalid input: expected array, received undefined"
+      expect(response.body.errors[0].message).toBe('Invalid input: expected array, received undefined');
     });
 
     it('should return 400 for invalid limit and offset', async () => {
@@ -122,8 +124,9 @@ describe('Price Routes (/api/price-history)', () => {
 
       expect(response.status).toBe(400);
       expect(response.body.errors).toHaveLength(2);
-      expect(response.body.errors[0].message).toBe('Number must be greater than 0');
-      expect(response.body.errors[1].message).toBe('Expected number, received string');
+      // The actual message is "Too small: expected number to be >0"
+      expect(response.body.errors[0].message).toBe('Too small: expected number to be >0');
+      expect(response.body.errors[1].message).toBe('Invalid input: expected number, received NaN');
     });
   });
 });

src/utils/zodUtils.test.ts

@@ -59,7 +59,7 @@ describe('Zod Utilities', () => {
       expect(result.success).toBe(false);
       if (!result.success) {
         // z.string() will throw its own error message before min(1) is checked.
-        expect(result.error.issues[0].message).toBe('Expected string, received number');
+        expect(result.error.issues[0].message).toBe('Invalid input: expected string, received number');
       }
     });
 
@@ -67,7 +67,7 @@ describe('Zod Utilities', () => {
       const result = schema.safeParse({ a: 1 });
       expect(result.success).toBe(false);
       if (!result.success) {
-        expect(result.error.issues[0].message).toBe('Expected string, received object');
+        expect(result.error.issues[0].message).toBe('Invalid input: expected string, received object');
       }
     });
   });
@@ -95,7 +95,7 @@ describe('Zod Utilities', () => {
       const result = schema.safeParse({ params: { id: 'abc' } });
       expect(result.success).toBe(false);
       if (!result.success) {
-        expect(result.error.issues[0].message).toContain('Expected number, received nan');
+        expect(result.error.issues[0].message).toBe('Invalid input: expected number, received NaN');
       }
     });
 
@@ -103,7 +103,7 @@ describe('Zod Utilities', () => {
       const result = schema.safeParse({ params: { id: -1 } });
       expect(result.success).toBe(false);
       if (!result.success) {
-        expect(result.error.issues[0].message).toContain('Must be a number');
+        expect(result.error.issues[0].message).toBe("Invalid ID for parameter 'id'. Must be a number.");
       }
     });
 
@@ -111,7 +111,7 @@ describe('Zod Utilities', () => {
       const result = schema.safeParse({ params: { id: 1.5 } });
       expect(result.success).toBe(false);
       if (!result.success) {
-        expect(result.error.issues[0].message).toContain('Must be a number');
+        expect(result.error.issues[0].message).toBe("Invalid ID for parameter 'id'. Must be a number.");
       }
     });
 
@@ -119,7 +119,7 @@ describe('Zod Utilities', () => {
       const result = schema.safeParse({ params: { id: 0 } });
       expect(result.success).toBe(false);
       if (!result.success) {
-        expect(result.error.issues[0].message).toContain('Must be a number');
+        expect(result.error.issues[0].message).toBe("Invalid ID for parameter 'id'. Must be a number.");
       }
     });
 
@@ -224,7 +224,7 @@ describe('Zod Utilities', () => {
       const floatResult = schema.safeParse('123.45');
       expect(floatResult.success).toBe(false);
       if (!floatResult.success) {
-        expect(floatResult.error.issues[0].message).toBe('Expected integer, received float');
+        expect(floatResult.error.issues[0].message).toBe('Invalid input: expected int, received number');
       }
     });
 
@@ -234,7 +234,7 @@ describe('Zod Utilities', () => {
       const zeroResult = schema.safeParse('0');
       expect(zeroResult.success).toBe(false);
       if (!zeroResult.success) {
-        expect(zeroResult.error.issues[0].message).toBe('Number must be greater than 0');
+        expect(zeroResult.error.issues[0].message).toBe('Too small: expected number to be >0');
       }
     });
 
@@ -244,7 +244,7 @@ describe('Zod Utilities', () => {
       const negativeResult = schema.safeParse('-1');
       expect(negativeResult.success).toBe(false);
       if (!negativeResult.success) {
-        expect(negativeResult.error.issues[0].message).toBe('Number must be greater than or equal to 0');
+        expect(negativeResult.error.issues[0].message).toBe('Too small: expected number to be >=0');
       }
     });
 
@@ -254,12 +254,12 @@ describe('Zod Utilities', () => {
       const tooSmallResult = schema.safeParse('9');
       expect(tooSmallResult.success).toBe(false);
       if (!tooSmallResult.success) {
-        expect(tooSmallResult.error.issues[0].message).toBe('Number must be greater than or equal to 10');
+        expect(tooSmallResult.error.issues[0].message).toBe('Too small: expected number to be >=10');
       }
       const tooLargeResult = schema.safeParse('21');
       expect(tooLargeResult.success).toBe(false);
       if (!tooLargeResult.success) {
-        expect(tooLargeResult.error.issues[0].message).toBe('Number must be less than or equal to 20');
+        expect(tooLargeResult.error.issues[0].message).toBe('Too big: expected number to be <=20');
       }
     });
   });

src/utils/zodUtils.ts

@@ -59,18 +59,27 @@ export const optionalNumeric = (
     nonnegative?: boolean;
   } = {},
 ) => {
-  let schema = z.coerce.number();
+  let numberSchema = z.coerce.number();
 
-  if (options.integer) schema = schema.int();
-  if (options.positive) schema = schema.positive();
-  else if (options.nonnegative) schema = schema.nonnegative();
+  if (options.integer) numberSchema = numberSchema.int();
+  if (options.positive) numberSchema = numberSchema.positive();
+  else if (options.nonnegative) numberSchema = numberSchema.nonnegative();
 
-  if (options.min !== undefined) schema = schema.min(options.min);
-  if (options.max !== undefined) schema = schema.max(options.max);
+  if (options.min !== undefined) numberSchema = numberSchema.min(options.min);
+  if (options.max !== undefined) numberSchema = numberSchema.max(options.max);
 
-  if (options.default !== undefined) return schema.optional().default(options.default);
+  // Make the number schema optional *before* preprocessing. This allows it to correctly handle
+  // the `undefined` value that our preprocessor generates from `null`.
+  const optionalNumberSchema = numberSchema.optional();
 
-  return schema.optional();
+  // This is crucial because z.coerce.number(null) results in 0, which bypasses
+  // the .optional() and .default() logic for null inputs. We want null to be
+  // treated as "not provided", just like undefined.
+  const schema = z.preprocess((val) => (val === null ? undefined : val), optionalNumberSchema);
+  
+  if (options.default !== undefined) return schema.default(options.default);
+
+  return schema;
 };
 
 /**

vitest.config.e2e.ts

@@ -0,0 +1,26 @@
+import { defineConfig, mergeConfig } from 'vitest/config';
+import integrationConfig from './vitest.config.integration';
+
+const e2eConfig = mergeConfig(
+  integrationConfig,
+  defineConfig({
+    test: {
+      name: 'e2e',
+      // Point specifically to E2E tests
+      include: ['src/tests/e2e/**/*.e2e.test.ts'],
+      // Increase timeout for E2E flows that involve AI or full API chains
+      testTimeout: 120000,
+      coverage: {
+        reportsDirectory: '.coverage/e2e',
+      },
+    },
+  }),
+);
+
+// Explicitly override the include array to ensure we don't inherit integration tests
+// (mergeConfig might concatenate arrays by default)
+if (e2eConfig.test) {
+  e2eConfig.test.include = ['src/tests/e2e/**/*.e2e.test.ts'];
+}
+
+export default e2eConfig;