@jrpool/kilotest 46.1.0 → 47.0.1

package/{index.test.js → index.test.ts}

@@ -1,47 +1,50 @@
 /*
-  index.test.js
+  index.test.ts
   Integration tests for index.js requestHandler, covering GET routes, POST routes,
   error paths, worker authentication, and helper function behavior.
 */
 
-// ENVIRONMENT (must be set before requiring index.js, because index.js reads
-// TESTARO_WORKERS and AUTH_CODE at module load time, and util.js reads DB_DIR.)
+// ENVIRONMENT (the test environment configuration; all modules now read
+// process.env at call time, so load order no longer matters.)
 
-const path = require('node:path');
-const fixtureDBDir = path.join(__dirname, 'test', 'fixtures', 'db');
+import path from 'node:path';
+import {fixtureDBDir} from './test/dbFixture.ts';
 
+const testCommentsDir = path.join(import.meta.dirname, 'test/fixtures/comments');
 process.env.DB_DIR = fixtureDBDir;
 process.env.AUTH_CODE = 'test-auth-code';
+process.env.TUTORIAL_WEB_COMMENTS_PATH = path.join(testCommentsDir, 'tutorialWeb.json');
+process.env.TUTORIAL_AI_COMMENTS_PATH = path.join(testCommentsDir, 'tutorialAI.json');
 process.env.TESTARO_WORKERS = JSON.stringify({
   worker1: {secret: 'secret1', name: 'Worker One'}
 });
 
 // IMPORTS
 
-const {test, before, beforeEach, after} = require('node:test');
-const assert = require('node:assert/strict');
-const http = require('node:http');
-const fs = require('node:fs/promises');
-const indexModule = require('./index');
+import {test, before, beforeEach, after} from 'node:test';
+import assert from 'node:assert/strict';
+import http from 'node:http';
+import fs from 'node:fs/promises';
+import * as indexModule from './index.ts';
 const {requestHandler, routes, serveError, startServer, runIfMain, isPathAllowed, getAbuseError} = indexModule;
 
 // CONSTANTS
 
 const port = 3997;
-const recsPath = path.join(fixtureDBDir, 'jobs', 'recs.json');
+const testRequestsPath = path.join(fixtureDBDir, 'jobs', 'testRequests.json');
 
 // SETUP AND TEARDOWN
 
-let server;
+let server: http.Server;
 
 before(async () => {
   server = http.createServer(requestHandler);
-  await new Promise(resolve => server.listen(port, () => resolve()));
+  await new Promise<void>(resolve => server.listen(port, () => resolve()));
 });
 
-// Restore recs.json and clean job directories before each test, so tests do not depend on execution order.
+// Restore testRequests.json and clean job directories before each test, so tests do not depend on execution order.
 beforeEach(async () => {
-  await fs.writeFile(recsPath, '{}\n');
+  await fs.writeFile(testRequestsPath, '{}\n');
   for (const sub of ['claimed', 'queue', 'failed']) {
     const dir = path.join(fixtureDBDir, 'jobs', sub);
     await fs.mkdir(dir, {recursive: true});
@@ -50,12 +53,16 @@ beforeEach(async () => {
       await fs.unlink(path.join(dir, file)).catch(() => {});
     }
   }
+  // Create test comments directory and reset test comment files so tests start clean.
+  await fs.mkdir(testCommentsDir, {recursive: true});
+  await fs.writeFile(path.join(testCommentsDir, 'tutorialWeb.json'), '[]\n');
+  await fs.writeFile(path.join(testCommentsDir, 'tutorialAI.json'), '[]\n');
 });
 
 after(async () => {
   // Close all idle connections, then close the server with a timeout.
   server.closeAllConnections?.();
-  await new Promise(resolve => {
+  await new Promise<void>(resolve => {
     const timer = setTimeout(() => {
       server.closeAllConnections?.();
       resolve();
@@ -65,8 +72,8 @@ after(async () => {
       resolve();
     });
   });
-  // Restore recs.json and clean job directories after running.
-  await fs.writeFile(recsPath, '{}\n');
+  // Restore testRequests.json and clean job directories after running.
+  await fs.writeFile(testRequestsPath, '{}\n');
   for (const sub of ['claimed', 'queue', 'failed']) {
     const dir = path.join(fixtureDBDir, 'jobs', sub);
     await fs.mkdir(dir, {recursive: true});
@@ -83,7 +90,7 @@ const uniqueStamp = Date.now();
 
 // HELPERS
 
-const request = (method, requestPath, body = null, headers = {}) => new Promise((resolve, reject) => {
+const request = (method: string, requestPath: string, body: any = null, headers: any = {}): Promise<any> => new Promise((resolve, reject) => {
   const options = {method, host: 'localhost', port, path: requestPath, headers: {...headers}};
   let bodyData = '';
   if (body) {
@@ -97,7 +104,7 @@ const request = (method, requestPath, body = null, headers = {}) => new Promise(
     options.headers['content-length'] = Buffer.byteLength(bodyData);
   }
   const req = http.request(options, response => {
-    const chunks = [];
+    const chunks: Buffer[] = [];
     response.on('data', chunk => chunks.push(chunk));
     response.on('end', () => {
       resolve({statusCode: response.statusCode, headers: response.headers, body: Buffer.concat(chunks).toString()});
@@ -107,7 +114,7 @@ const request = (method, requestPath, body = null, headers = {}) => new Promise(
   req.end(bodyData || '');
 });
 
-const formRequest = (method, requestPath, formData, headers = {}) => new Promise((resolve, reject) => {
+const formRequest = (method: string, requestPath: string, formData: any, headers: any = {}): Promise<any> => new Promise((resolve, reject) => {
   const body = new URLSearchParams(formData).toString();
   const options = {
     method,
@@ -121,7 +128,7 @@ const formRequest = (method, requestPath, formData, headers = {}) => new Promise
     }
   };
   const req = http.request(options, response => {
-    const chunks = [];
+    const chunks: Buffer[] = [];
     response.on('data', chunk => chunks.push(chunk));
     response.on('end', () => {
       resolve({statusCode: response.statusCode, headers: response.headers, body: Buffer.concat(chunks).toString()});
@@ -131,7 +138,7 @@ const formRequest = (method, requestPath, formData, headers = {}) => new Promise
   req.end(body);
 });
 
-const jsonBody = res => {
+const jsonBody = (res: any) => {
   try {
     return JSON.parse(res.body);
   }
@@ -147,6 +154,26 @@ test('routes has GET and POST arrays', () => {
   assert.ok(Array.isArray(routes.POST));
 });
 
+// TESTS: smoke-test short-circuit
+
+test('GET with x-kilotest-smoke header returns a perfunctory 200', async () => {
+  const res = await request('GET', '/api/listReports', null, {'x-kilotest-smoke': '1'});
+  assert.equal(res.statusCode, 200);
+  assert.equal(res.body, '{}');
+});
+
+test('POST with x-kilotest-smoke header returns a perfunctory 200', async () => {
+  const res = await request('POST', '/api/requestFeature', {}, {'x-kilotest-smoke': '1'});
+  assert.equal(res.statusCode, 200);
+  assert.equal(res.body, '{}');
+});
+
+test('GET without x-kilotest-smoke header executes the handler', async () => {
+  const res = await request('GET', '/api/listReports');
+  assert.equal(res.statusCode, 200);
+  assert.notEqual(res.body, '{}');
+});
+
 // TESTS: GET routes
 
 test('GET / serves the home page as HTML', async () => {
@@ -304,18 +331,18 @@ test('GET /fullReport.json/990101T0000/xxx returns an abuse error for a nonexist
   assert.ok(res.body.includes('Invalid request'));
 });
 
-test('GET /tutorial/images/newsletter-form.png serves the image', async () => {
-  const res = await request('GET', '/tutorial/images/newsletter-form.png');
+test('GET /tutorialWeb/images/newsletter-form.png serves the image', async () => {
+  const res = await request('GET', '/tutorialWeb/images/newsletter-form.png');
   assert.equal(res.statusCode, 200);
   assert.ok(res.headers['content-type'].includes('image/png'));
 });
 
-test('GET /tutorial/images with an unknown extension serves octet-stream', async () => {
+test('GET /tutorialWeb/images with an unknown extension serves octet-stream', async () => {
   // Create a temporary image file with an unknown extension.
-  const imgPath = path.join(__dirname, 'web', 'tutorial', 'images', 'test.bmp');
+  const imgPath = path.join(import.meta.dirname, 'web', 'tutorialWeb', 'images', 'test.bmp');
   await fs.writeFile(imgPath, 'fake bitmap data');
   try {
-    const res = await request('GET', '/tutorial/images/test.bmp');
+    const res = await request('GET', '/tutorialWeb/images/test.bmp');
     assert.equal(res.statusCode, 200);
     assert.ok(res.headers['content-type'].includes('application/octet-stream'));
   }
@@ -324,13 +351,34 @@ test('GET /tutorial/images with an unknown extension serves octet-stream', async
   }
 });
 
-test('GET /tutorial/images/nonexistent.png returns an error page', async () => {
-  const res = await request('GET', '/tutorial/images/nonexistent.png');
+test('GET /tutorialWeb/images/nonexistent.png returns an error page', async () => {
+  const res = await request('GET', '/tutorialWeb/images/nonexistent.png');
+  assert.equal(res.statusCode, 400);
+  assert.ok(res.body.includes('Image not found'));
+});
+
+test('GET /tutorialAI/images/test.png serves the image', async () => {
+  // Create a temporary image file in tutorialAI.
+  const imgPath = path.join(import.meta.dirname, 'web', 'tutorialAI', 'images', 'test.png');
+  await fs.mkdir(path.dirname(imgPath), {recursive: true});
+  await fs.writeFile(imgPath, 'fake png data');
+  try {
+    const res = await request('GET', '/tutorialAI/images/test.png');
+    assert.equal(res.statusCode, 200);
+    assert.ok(res.headers['content-type'].includes('image/png'));
+  }
+  finally {
+    await fs.unlink(imgPath).catch(() => {});
+  }
+});
+
+test('GET /tutorialAI/images/nonexistent.png returns an error page', async () => {
+  const res = await request('GET', '/tutorialAI/images/nonexistent.png');
   assert.equal(res.statusCode, 400);
   assert.ok(res.body.includes('Image not found'));
 });
 
-test('GET /nonexistent.html returns an abuse error', async () => {
+test('GET /nonexistent.html returns an abuse error', {timeout: 500}, async () => {
   const res = await request('GET', '/nonexistent.html');
   assert.equal(res.statusCode, 400);
   assert.ok(res.body.includes('Invalid request'));
@@ -346,7 +394,7 @@ test('GET /forbidden-path returns an invalid GET request error', async () => {
 
 test('POST /requestTest.html with valid data returns an HTML page', async () => {
   const res = await formRequest('POST', '/requestTest.html', {
-    what: `Unique Test Page ${uniqueStamp}`,
+    description: `Unique Test Page ${uniqueStamp}`,
     url: `https://example.com/unique-${uniqueStamp}`,
     why: 'Because accessibility matters'
   });
@@ -356,7 +404,7 @@ test('POST /requestTest.html with valid data returns an HTML page', async () =>
 
 test('POST /requestTest.html with an already-tested URL returns an error', async () => {
   const res = await formRequest('POST', '/requestTest.html', {
-    what: 'Mixed Outcomes Page',
+    description: 'Mixed Outcomes Page',
     url: 'https://example.com/mixed',
     why: 'Because accessibility matters'
   });
@@ -366,17 +414,23 @@ test('POST /requestTest.html with an already-tested URL returns an error', async
 
 test('POST /requestTest.html with invalid data returns an error', async () => {
   const res = await formRequest('POST', '/requestTest.html', {
-    what: '',
+    description: '',
     url: 'not-a-url',
     why: ''
   });
   assert.equal(res.statusCode, 400);
-  assert.ok(res.body.includes('Invalid test recommendation'));
+  assert.ok(res.body.includes('Invalid test request'));
+});
+
+test('POST /requestTest.html with an unreadable body returns an error', async () => {
+  const res = await request('POST', '/requestTest.html', 'rawbody', {'content-type': 'text/plain'});
+  assert.equal(res.statusCode, 400);
+  assert.ok(res.body.includes('Unreadable request body'));
 });
 
 test('POST /requestRetest.html/260202T0000/new with valid data returns HTML', async () => {
-  // Reset recs.json to avoid duplicate-recommendation errors from prior tests.
-  await fs.writeFile(recsPath, '{}\n');
+  // Reset testRequests.json to avoid duplicate-request errors from prior tests.
+  await fs.writeFile(testRequestsPath, '{}\n');
   const res = await formRequest('POST', '/requestRetest.html/260202T0000/new', {
     why: 'Because the report is obsolete and needs refreshing'
   });
@@ -389,7 +443,7 @@ test('POST /requestRetest.html/invalid/invalid with invalid data returns an erro
     why: 'Because'
   });
   assert.equal(res.statusCode, 400);
-  assert.ok(res.body.includes('Invalid retest recommendation'));
+  assert.ok(res.body.includes('Invalid retest request'));
 });
 
 test('POST /api/requestTest with valid JSON returns a JSON response', {timeout: 500}, async () => {
@@ -443,6 +497,36 @@ test('POST /worker/job without authentication returns 401', async () => {
   assert.ok(body.error.message.includes('Unauthorized'));
 });
 
+test('POST /worker/job when TESTARO_WORKERS is unset returns 401', async () => {
+  const saved = process.env.TESTARO_WORKERS;
+  delete process.env.TESTARO_WORKERS;
+  try {
+    const auth = Buffer.from('worker1:secret1').toString('base64');
+    const res = await request('POST', '/worker/job', {}, {
+      authorization: `Basic ${auth}`
+    });
+    assert.equal(res.statusCode, 401);
+  }
+  finally {
+    process.env.TESTARO_WORKERS = saved;
+  }
+});
+
+test('POST /worker/job when TESTARO_WORKERS is invalid JSON returns 401', async () => {
+  const saved = process.env.TESTARO_WORKERS;
+  process.env.TESTARO_WORKERS = 'not valid JSON {';
+  try {
+    const auth = Buffer.from('worker1:secret1').toString('base64');
+    const res = await request('POST', '/worker/job', {}, {
+      authorization: `Basic ${auth}`
+    });
+    assert.equal(res.statusCode, 401);
+  }
+  finally {
+    process.env.TESTARO_WORKERS = saved;
+  }
+});
+
 test('POST /worker/job with valid authentication returns a job or no-job response', async () => {
   // Clean up any claimed jobs left by prior tests.
   const claimedDir = path.join(fixtureDBDir, 'jobs', 'claimed');
@@ -494,6 +578,26 @@ test('PUT / returns an invalid method error', async () => {
   assert.ok(res.body.includes('Invalid request method'));
 });
 
+// TESTS: requestHandler catch boundary
+
+test('GET /listReports.html returns a 500 error when an unexpected internal error occurs', {timeout: 500}, async () => {
+  // Corrupt testRequests.json so that getTestRequests throws, an error that should never occur in normal
+  // operation and so is not handled by handleRequest itself, only by requestHandler's
+  // outer catch boundary.
+  const backup = await fs.readFile(testRequestsPath, 'utf8');
+  await fs.writeFile(testRequestsPath, 'not valid json');
+  try {
+    const res = await request('GET', '/listReports.html');
+    assert.equal(res.statusCode, 500);
+    assert.ok(res.headers['content-type'].includes('application/json'));
+    const body = jsonBody(res);
+    assert.ok(body.error);
+  }
+  finally {
+    await fs.writeFile(testRequestsPath, backup);
+  }
+});
+
 // TESTS: serveError behavior
 
 test('serveError sends JSON for agent requests (isHumanUser = false)', async () => {
@@ -510,10 +614,10 @@ test('serveError sends HTML for human requests (isHumanUser = true)', async () =
   assert.ok(res.headers['content-type'].includes('text/html'));
 });
 
-// TESTS: recAction.html
+// TESTS: requestAction.html
 
-test('POST /recAction.html with invalid auth code returns an error', {timeout: 500}, async () => {
-  const res = await formRequest('POST', '/recAction.html', {
+test('POST /requestAction.html with invalid auth code returns an error', {timeout: 500}, async () => {
+  const res = await formRequest('POST', '/requestAction.html', {
     target: 'https://example.com\tTest Page',
     authCode: 'wrong-code'
   });
@@ -521,13 +625,13 @@ test('POST /recAction.html with invalid auth code returns an error', {timeout: 5
   assert.ok(res.body.includes('Invalid test order'));
 });
 
-test('POST /recAction.html with valid auth code and rejection (no what) returns HTML', async () => {
+test('POST /requestAction.html with valid auth code and rejection (no description) returns HTML', async () => {
   await formRequest('POST', '/requestTest.html', {
-    what: `Reject Test Page ${uniqueStamp}`,
+    description: `Reject Test Page ${uniqueStamp}`,
     url: `https://example.com/reject-${uniqueStamp}`,
     why: 'Because accessibility matters'
   });
-  const res = await formRequest('POST', '/recAction.html', {
+  const res = await formRequest('POST', '/requestAction.html', {
     target: `https://example.com/reject-${uniqueStamp}`,
     authCode: 'test-auth-code'
   });
@@ -535,31 +639,38 @@ test('POST /recAction.html with valid auth code and rejection (no what) returns
   assert.ok(res.headers['content-type'].includes('text/html'));
 });
 
-// TESTS: tutorialComment
+// TESTS: tutorialWeb (web user tutorial)
 
-test('POST /tutorialComment.html with content returns JSON', async () => {
-  const res = await request('POST', '/tutorialComment.html', {
-    content: 'This is a test comment'
+test('GET /tutorialWeb.html returns HTML', async () => {
+  const res = await request('GET', '/tutorialWeb.html');
+  assert.equal(res.statusCode, 200);
+  assert.ok(res.headers['content-type'].includes('text/html'));
+});
+
+test('POST /tutorialWebComment.html with content returns JSON', async () => {
+  const res = await request('POST', '/tutorialWebComment.html', {
+    content: `This is a test comment ${uniqueStamp}`
   });
   assert.ok(res.headers['content-type'].includes('application/json'));
+  assert.deepEqual(JSON.parse(res.body), {status: 'ok'});
 });
 
 // TESTS: additional branch coverage
 
-test('GET /fullReport.json/260101T0007/hid returns an abuse error for a hidden report', async () => {
+test('GET /fullReport.json/260101T0007/hid returns an error for an unavailable report', async () => {
   const res = await request('GET', '/fullReport.json/260101T0007/hid');
   assert.equal(res.statusCode, 400);
   assert.ok(res.body.includes('Invalid request'));
 });
 
-test('POST /recAction.html with valid auth code and approval returns HTML', {timeout: 500}, async () => {
-  await fs.writeFile(recsPath, '{}\n');
+test('POST /requestAction.html with valid auth code and approval returns HTML', {timeout: 500}, async () => {
+  await fs.writeFile(testRequestsPath, '{}\n');
   await formRequest('POST', '/requestTest.html', {
-    what: `Approval Test Page ${uniqueStamp}`,
+    description: `Approval Test Page ${uniqueStamp}`,
     url: `https://example.com/approval-${uniqueStamp}`,
     why: 'Because accessibility matters'
   });
-  const res = await formRequest('POST', '/recAction.html', {
+  const res = await formRequest('POST', '/requestAction.html', {
     target: `https://example.com/approval-${uniqueStamp}\tApproval Test Page ${uniqueStamp}`,
     authCode: 'test-auth-code'
   });
@@ -575,10 +686,10 @@ test('POST /reannotate.html with invalid auth code returns an error page', async
 });
 
 test('POST /reannotate.html with valid auth code serves the answer page', async () => {
-  // Back up all fixture reports, because annotateReport modifies them in place.
+  // Back up all fixture reports, because reannotation modifies them in place.
   const reportsDir = path.join(fixtureDBDir, 'reports');
   const reportFiles = await fs.readdir(reportsDir);
-  const backups = {};
+  const backups: Record<string, string> = {};
   for (const file of reportFiles) {
     backups[file] = await fs.readFile(path.join(reportsDir, file), 'utf8');
   }
@@ -593,7 +704,7 @@ test('POST /reannotate.html with valid auth code serves the answer page', async
   finally {
     // Restore all fixture reports.
     for (const file of reportFiles) {
-      await fs.writeFile(path.join(reportsDir, file), backups[file]);
+      await fs.writeFile(path.join(reportsDir, file), backups[file]!);
     }
   }
 });
@@ -608,7 +719,7 @@ test('POST /renewWCAG.html with invalid auth code returns an error page', async
 test('POST /renewWCAG.html with valid auth code serves the answer page', async () => {
   // Mock fetch to avoid a network dependency.
   const originalFetch = global.fetch;
-  const wcagMapPath = path.join(__dirname, 'wcagMap.json');
+  const wcagMapPath = path.join(import.meta.dirname, 'wcagMap.json');
   const wcagMapBackup = await fs.readFile(wcagMapPath, 'utf8');
   // @ts-expect-error: Replacing the real function with a mock for testing.
   global.fetch = async () => ({
@@ -629,21 +740,56 @@ test('POST /renewWCAG.html with valid auth code serves the answer page', async (
   }
 });
 
-test('POST /tutorialComment.html with empty content returns a JSON error', {timeout: 500}, async () => {
-  const res = await request('POST', '/tutorialComment.html', {
+test('POST /tutorialWebComment.html with empty content returns a JSON error', {timeout: 500}, async () => {
+  const res = await request('POST', '/tutorialWebComment.html', {
+    content: ''
+  });
+  assert.ok(res.headers['content-type'].includes('application/json'));
+});
+
+// TESTS: tutorialAI (AI agent configuration tutorial)
+
+test('GET /tutorialAI.html returns HTML', async () => {
+  const res = await request('GET', '/tutorialAI.html');
+  assert.equal(res.statusCode, 200);
+  assert.ok(res.headers['content-type'].includes('text/html'));
+});
+
+test('POST /tutorialAIComment.html with content returns JSON', async () => {
+  const res = await request('POST', '/tutorialAIComment.html', {
+    content: `This is a test AI tutorial comment ${uniqueStamp}`
+  });
+  assert.ok(res.headers['content-type'].includes('application/json'));
+  assert.deepEqual(JSON.parse(res.body), {status: 'ok'});
+});
+
+test('POST /tutorialAIComment.html with empty content returns a JSON error', {timeout: 500}, async () => {
+  const res = await request('POST', '/tutorialAIComment.html', {
     content: ''
   });
   assert.ok(res.headers['content-type'].includes('application/json'));
 });
 
+test('GET /qai redirects to /tutorialAI.html', async () => {
+  const res = await request('GET', '/qai', {}, {followRedirects: false});
+  assert.equal(res.statusCode, 301);
+  assert.equal(res.headers['location'], '/tutorialAI.html');
+});
+
+test('GET /qai/comments redirects to /tutorialAI.html', async () => {
+  const res = await request('GET', '/qai/comments', {}, {followRedirects: false});
+  assert.equal(res.statusCode, 301);
+  assert.equal(res.headers['location'], '/tutorialAI.html');
+});
+
 test('POST /requestTest.html with non-https URL returns an error', async () => {
   const res = await formRequest('POST', '/requestTest.html', {
-    what: 'Test Page',
+    description: 'Test Page',
     url: 'http://example.com',
     why: 'Because accessibility matters'
   });
   assert.equal(res.statusCode, 400);
-  assert.ok(res.body.includes('Invalid test recommendation'));
+  assert.ok(res.body.includes('Invalid test request'));
 });
 
 test('POST /requestRetest.html/260202T0000/new with missing why returns an error', async () => {
@@ -651,7 +797,7 @@ test('POST /requestRetest.html/260202T0000/new with missing why returns an error
     why: ''
   });
   assert.equal(res.statusCode, 400);
-  assert.ok(res.body.includes('Invalid retest recommendation'));
+  assert.ok(res.body.includes('Invalid retest request'));
 });
 
 test('POST /worker/report with valid authentication and wrong worker returns an error', async () => {
@@ -669,6 +815,31 @@ test('POST /worker/report with valid authentication and wrong worker returns an
   assert.ok(body.error);
 });
 
+test('POST /worker/report with a claimed job file that is not valid JSON returns a 500 error', {timeout: 500}, async () => {
+  // A corrupt claimed-job file is not the normal "no such claim" outcome (ENOENT), so it
+  // should propagate as an unexpected error rather than being treated as an unassigned job.
+  const jobID = '990101T0002-bad';
+  const claimedDir = path.join(fixtureDBDir, 'jobs', 'claimed');
+  const jobPath = path.join(claimedDir, `${jobID}.json`);
+  await fs.writeFile(jobPath, 'not valid json');
+  const auth = Buffer.from('worker1:secret1').toString('base64');
+  const report = {
+    id: jobID,
+    target: {what: 'Test', url: 'https://example.com/test'}
+  };
+  try {
+    const res = await request('POST', '/worker/report', {report}, {
+      authorization: `Basic ${auth}`
+    });
+    assert.equal(res.statusCode, 500);
+    const body = jsonBody(res);
+    assert.ok(body.error);
+  }
+  finally {
+    await fs.unlink(jobPath).catch(() => {});
+  }
+});
+
 test('POST /worker/job with wrong secret returns 401', async () => {
   const auth = Buffer.from('worker1:wrongsecret').toString('base64');
   const res = await request('POST', '/worker/job', {}, {
@@ -723,7 +894,7 @@ test('POST /worker/job with a claimed job assigned to the worker returns an erro
   const body = jsonBody(res);
   assert.ok(body.error.message.includes('has not completed job'));
   // Wait for the async rename to complete.
-  await new Promise(resolve => setTimeout(resolve, 100));
+  await new Promise<void>(resolve => setTimeout(resolve, 100));
   // The job should have been moved to failed.
   const failedExists = await fs.access(failedJobPath).then(() => true).catch(() => false);
   assert.ok(failedExists, 'Job should be moved to failed directory');
@@ -758,7 +929,7 @@ test('POST /worker/job with a queued job assigns it to the worker', {timeout: 50
   assert.equal(body.id, '260101T0000-mix');
   assert.equal(body.sources.worker, 'Worker One');
   // Wait for the async unlink to complete.
-  await new Promise(resolve => setTimeout(resolve, 100));
+  await new Promise<void>(resolve => setTimeout(resolve, 100));
   // The job should have been moved from queue to claimed.
   const queueExists = await fs.access(path.join(queueDir, jobFile)).then(() => true).catch(() => false);
   assert.equal(queueExists, false, 'Job should be removed from queue');
@@ -803,12 +974,57 @@ test('POST /worker/report with valid authentication and valid claimed job proces
   assert.equal(body.status, 'ok');
 });
 
+test('POST /worker/report with a claimed job but an unusable report returns an error and reclassifies the job', {timeout: 500}, async () => {
+  // Use a unique job ID that does not conflict with existing fixtures.
+  const jobID = '990101T0001-unu';
+  const reportPath = path.join(fixtureDBDir, 'reports', `${jobID}.json`);
+  const claimedDir = path.join(fixtureDBDir, 'jobs', 'claimed');
+  const failedDir = path.join(fixtureDBDir, 'jobs', 'failed');
+  const jobFile = `${jobID}.json`;
+  const claimedJobPath = path.join(claimedDir, jobFile);
+  const failedJobPath = path.join(failedDir, jobFile);
+  // Clean up any leftover files.
+  await fs.unlink(reportPath).catch(() => {});
+  await fs.unlink(failedJobPath).catch(() => {});
+  // Create a claimed job assigned to Worker One.
+  await fs.writeFile(claimedJobPath, JSON.stringify({
+    id: jobID,
+    target: {what: 'Test', url: 'https://example.com/test'},
+    sources: {worker: 'Worker One'}
+  }));
+  const auth = Buffer.from('worker1:secret1').toString('base64');
+  // A report that is syntactically valid (has id, target.what, target.url) but is not
+  // usable by Kilotest, because it has no acts, jobData, or catalog.
+  const report = {
+    id: jobID,
+    target: {what: 'Test', url: 'https://example.com/test'}
+  };
+  const res = await request('POST', '/worker/report', {report}, {
+    authorization: `Basic ${auth}`
+  });
+  assert.equal(res.statusCode, 400);
+  const body = jsonBody(res);
+  assert.ok(body.error.message.includes('not usable'));
+  // The report should not have been recorded.
+  const reportExists = await fs.access(reportPath).then(() => true).catch(() => false);
+  assert.equal(reportExists, false, 'Unusable report should not be saved');
+  // Wait for the async rename to complete.
+  await new Promise<void>(resolve => setTimeout(resolve, 100));
+  // The job should have been reclassified as failed rather than left claimed.
+  const failedExists = await fs.access(failedJobPath).then(() => true).catch(() => false);
+  assert.ok(failedExists, 'Job should be moved to the failed directory');
+  const claimedExists = await fs.access(claimedJobPath).then(() => true).catch(() => false);
+  assert.equal(claimedExists, false, 'Job should be removed from the claimed directory');
+  // Clean up.
+  await fs.unlink(failedJobPath).catch(() => {});
+});
+
 // TESTS: remaining error branches and web pages
 
 test('GET /style.css with a read error returns an error page', async () => {
   // Temporarily rename style.css to trigger a read error.
-  const stylePath = path.join(__dirname, 'style.css');
-  const tempPath = path.join(__dirname, 'style.css.bak');
+  const stylePath = path.join(import.meta.dirname, 'style.css');
+  const tempPath = path.join(import.meta.dirname, 'style.css.bak');
   await fs.rename(stylePath, tempPath);
   try {
     const res = await request('GET', '/style.css');
@@ -835,7 +1051,7 @@ test('GET /requestRetest.html/260202T0000/new returns an error page when called
 // TESTS: GET HTML page routing
 // These verify that the HTTP routing layer connects each URL to the correct
 // handler and returns HTML with a 200 status. The handler logic itself is
-// tested by the unit tests in web/*/*.test.js.
+// tested by the unit tests in web/*/*.test.cjs.
 
 const htmlPagePaths = [
   '/listReports.html',
@@ -843,7 +1059,8 @@ const htmlPagePaths = [
   '/listDiagnoses.html/linkNoText/260101T0000/mix/0',
   '/enqueueForm.html',
   '/manage.html',
-  '/tutorial.html',
+  '/tutorialWeb.html',
+  '/tutorialAI.html',
   '/listTopIssues.html',
   '/reannotateForm.html',
   '/renewWCAGForm.html',
@@ -856,17 +1073,17 @@ const htmlPagePaths = [
 ];
 
 for (const pagePath of htmlPagePaths) {
-  test(`GET ${pagePath} serves a generated HTML page`, async () => {
+  test(`GET ${pagePath} serves a generated HTML page`, {timeout: 500}, async () => {
     const res = await request('GET', pagePath);
     assert.equal(res.statusCode, 200);
     assert.ok(res.headers['content-type'].includes('text/html'));
   });
 }
 
-test('GET /enqueueForm.html shows recommendations when recs.json has entries', async () => {
-  await fs.writeFile(recsPath, JSON.stringify({
+test('GET /enqueueForm.html shows requests when testRequests.json has entries', async () => {
+  await fs.writeFile(testRequestsPath, JSON.stringify({
     'https://example.com/enqueue-test': [
-      {what: 'Enqueue Test Page', why: 'Needs testing for accessibility'}
+      {description: 'Enqueue Test Page', why: 'Needs testing for accessibility'}
     ]
   }));
   const res = await request('GET', '/enqueueForm.html');
@@ -889,52 +1106,104 @@ test('GET /test.html.bak matches isPathAllowed but falls through to catch-all',
   assert.ok(res.body.includes('Invalid GET request'));
 });
 
-test('GET /mcp returns a response from the MCP handler', async () => {
-  const res = await request('GET', '/mcp');
-  // The MCP handler responds to GET requests, typically with an error
-  // about acceptable content types or a similar MCP protocol message.
-  assert.ok(res.statusCode >= 400);
+test('GET /mcp with an SSE-capable Accept header returns a JSON-RPC 405 error instead of opening an SSE stream', async () => {
+  const res = await request('GET', '/mcp', null, {accept: 'application/json, text/event-stream'});
+  assert.equal(res.statusCode, 405);
+  const body = jsonBody(res);
+  assert.equal(body.jsonrpc, '2.0');
+  assert.equal(body.error.code, -32000);
+});
+
+test('GET /mcp without an SSE-capable Accept header serves an HTML explanation page instead of the MCP protocol response', async () => {
+  const res = await request('GET', '/mcp', null, {accept: 'text/html'});
+  assert.equal(res.statusCode, 400);
+  assert.ok(res.headers['content-type'].includes('text/html'));
+  assert.ok(res.body.includes('/tutorialAI.html'));
+});
+
+test('POST /mcp without an SSE-capable Accept header returns a JSON-RPC 406 error', async () => {
+  const res = await request('POST', '/mcp', {jsonrpc: '2.0', method: 'initialize', id: 1, params: {}});
+  assert.equal(res.statusCode, 406);
+  assert.equal(jsonBody(res).error.code, -32000);
+});
+
+test('POST /mcp with malformed JSON returns a JSON-RPC 400 parse error', async () => {
+  const res = await request('POST', '/mcp', '{not json', {
+    'content-type': 'application/json',
+    accept: 'application/json, text/event-stream'
+  });
+  assert.equal(res.statusCode, 400);
+  assert.equal(jsonBody(res).error.code, -32700);
+});
+
+test('POST /mcp with a non-JSON-RPC body returns a JSON-RPC 400 error', async () => {
+  const res = await request('POST', '/mcp', {foo: 'bar'}, {accept: 'application/json, text/event-stream'});
+  assert.equal(res.statusCode, 400);
+  assert.equal(jsonBody(res).error.code, -32700);
+});
+
+test('POST /mcp with a non-JSON content type returns a JSON-RPC 415 error', async () => {
+  const res = await request('POST', '/mcp', 'x=1', {
+    'content-type': 'application/x-www-form-urlencoded',
+    accept: 'application/json, text/event-stream'
+  });
+  assert.equal(res.statusCode, 415);
+  assert.equal(jsonBody(res).error.code, -32000);
 });
 
-test('POST /mcp returns a response from the MCP handler', async () => {
+test('POST /mcp with an unknown JSON-RPC method returns a -32601 error', async () => {
+  const res = await request('POST', '/mcp', {jsonrpc: '2.0', method: 'bogus/method', id: 9}, {
+    accept: 'application/json, text/event-stream'
+  });
+  assert.equal(res.statusCode, 200);
+  const dataLine = res.body.split('\n').find((line: string) => line.startsWith('data: '));
+  assert.ok(dataLine);
+  const message = JSON.parse(dataLine.slice(6));
+  assert.equal(message.error.code, -32601);
+});
+
+test('POST /mcp with a valid initialize request returns server info via SSE', async () => {
   const res = await request('POST', '/mcp', {
     jsonrpc: '2.0',
     method: 'initialize',
     id: 1,
     params: {
-      protocolVersion: '2024-11-05',
+      protocolVersion: '2025-06-18',
       capabilities: {},
       clientInfo: {name: 'test-client', version: '1.0'}
     }
   }, {
     accept: 'application/json, text/event-stream'
   });
-  // The MCP handler should process the initialize request.
-  assert.ok(res.statusCode === 200 || res.statusCode >= 400);
+  assert.equal(res.statusCode, 200);
+  const dataLine = res.body.split('\n').find((line: string) => line.startsWith('data: '));
+  assert.ok(dataLine);
+  const message = JSON.parse(dataLine.slice(6));
+  assert.equal(message.result.serverInfo.name, 'Kilotest');
 });
 
 // TESTS: answer error branches
 
 test('POST /requestTest.html with valid format but duplicate URL returns an answer error', {timeout: 500}, async () => {
-  await fs.writeFile(recsPath, '{}\n');
-  // First request to create the recommendation.
+  await fs.writeFile(testRequestsPath, '{}\n');
+  // First request to create the request.
   await formRequest('POST', '/requestTest.html', {
-    what: `Dup Test Page ${uniqueStamp}`,
+    description: `Dup Test Page ${uniqueStamp}`,
     url: `https://example.com/dup-${uniqueStamp}`,
     why: 'Because accessibility matters'
   });
   // Second request with the same URL should get a duplicate error.
   const res = await formRequest('POST', '/requestTest.html', {
-    what: `Dup Test Page ${uniqueStamp}`,
+    description: `Dup Test Page ${uniqueStamp}`,
     url: `https://example.com/dup-${uniqueStamp}`,
     why: 'Because accessibility matters again'
   });
   assert.equal(res.statusCode, 400);
-  assert.ok(res.body.includes('Duplicate recommendation'));
+  assert.ok(res.body.includes('Duplicate request'));
 });
 
 test('POST /requestRetest.html with valid format but duplicate retest returns an answer error', {timeout: 500}, async () => {
-  await fs.writeFile(recsPath, '{}\n');
+  await fs.writeFile(testRequestsPath, '{}\n');
   // First retest to create the recommendation.
   await formRequest('POST', '/requestRetest.html/260202T0000/new', {
     why: 'Because the report is obsolete and needs refreshing'
@@ -944,26 +1213,26 @@ test('POST /requestRetest.html with valid format but duplicate retest returns an
     why: 'Because the report is obsolete and needs refreshing again'
   });
   assert.equal(res.statusCode, 400);
-  assert.ok(res.body.includes('Duplicate recommendation'));
+  assert.ok(res.body.includes('Duplicate request'));
 });
 
-test('POST /recAction.html with valid auth code and approval of a duplicate returns an error', {timeout: 500}, async () => {
-  await fs.writeFile(recsPath, '{}\n');
-  // Create a recommendation.
+test('POST /requestAction.html with valid auth code and approval of a duplicate returns an error', {timeout: 500}, async () => {
+  await fs.writeFile(testRequestsPath, '{}\n');
+  // Create a request.
   await formRequest('POST', '/requestTest.html', {
-    what: `Action Dup Page ${uniqueStamp}`,
+    description: `Action Dup Page ${uniqueStamp}`,
     url: `https://example.com/action-dup-${uniqueStamp}`,
     why: 'Because accessibility matters'
   });
   // Approve it once.
-  await formRequest('POST', '/recAction.html', {
+  await formRequest('POST', '/requestAction.html', {
     target: `https://example.com/action-dup-${uniqueStamp}\tAction Dup Page ${uniqueStamp}`,
     authCode: 'test-auth-code',
     what: 'yes'
   });
-  // Approve it again (the recs may have been cleared, so this may succeed or fail).
-  // This test covers the recAction answer error branch.
-  const res = await formRequest('POST', '/recAction.html', {
+  // Approve it again (the requests may have been cleared, so this may succeed or fail).
+  // This test covers the requestAction answer error branch.
+  const res = await formRequest('POST', '/requestAction.html', {
     target: `https://example.com/action-dup-${uniqueStamp}\tAction Dup Page ${uniqueStamp}`,
     authCode: 'test-auth-code',
     what: 'yes'
@@ -972,10 +1241,10 @@ test('POST /recAction.html with valid auth code and approval of a duplicate retu
   assert.ok(res.statusCode === 200 || res.statusCode === 400);
 });
 
-test('POST /recAction.html with valid auth code and approval of an invalid URL returns an error', async () => {
+test('POST /requestAction.html with valid auth code and approval of an invalid URL returns an error', async () => {
   // A URL that starts with https:// but is not a valid URL causes
   // enqueue.answer to return status error.
-  const res = await formRequest('POST', '/recAction.html', {
+  const res = await formRequest('POST', '/requestAction.html', {
     target: 'https://\tTest Page',
     authCode: 'test-auth-code',
     what: 'yes'
@@ -986,22 +1255,22 @@ test('POST /recAction.html with valid auth code and approval of an invalid URL r
 
 // UNIT TESTS FOR serveError
 
-const mockRes = () => {
-  const state = {statusCode: null, headers: {}, body: null, writableEnded: false};
+const mockRes = (): any => {
+  const state: any = {statusCode: null, headers: {}, body: null, writableEnded: false};
   return {
     get statusCode() {return state.statusCode;},
-    set statusCode(value) {state.statusCode = value;},
-    setHeader(name, value) {state.headers[name] = value;},
-    end(data) {state.body = data; state.writableEnded = true;},
+    set statusCode(value: any) {state.statusCode = value;},
+    setHeader(name: any, value: any) {state.headers[name] = value;},
+    end(data: any) {state.body = data; state.writableEnded = true;},
     _state: state
   };
 };
 
 test('serveError does not write to a response that has already ended', async () => {
   let wrote = false;
-  const mockResponse = {
+  const mockResponse: any = {
     writableEnded: true,
-    set statusCode(value) {
+    set statusCode(value: any) {
       wrote = true;
     },
     setHeader() {
@@ -1043,29 +1312,80 @@ test('getAbuseError uses unknown IP when no forwarding header or remote address'
     headers: {},
     socket: {remoteAddress: undefined}
   };
-  const result = getAbuseError(mockRequest, 'test reason');
+  const result = getAbuseError(mockRequest as any, 'test reason');
   assert.equal(result['IP address'], 'unknown');
   assert.equal(result.reason, 'test reason');
 });
 
 // UNIT TESTS FOR startServer
 
-test('startServer starts an HTTP server when protocol is http', async () => {
+test('startServer starts an HTTP server when protocol is http', {timeout: 500}, async () => {
   // Delete PROTOCOL to exercise the 'http' fallback in startServer.
   const savedProtocol = process.env.PROTOCOL;
+  // Use port 0 so the OS assigns an ephemeral port, avoiding collisions with production.
+  const savedPort = process.env.PORT;
+  process.env.PORT = '0';
   delete process.env.PROTOCOL;
   const server = await startServer();
   process.env.PROTOCOL = savedProtocol;
+  if (savedPort !== undefined) {
+    process.env.PORT = savedPort;
+  }
+  else {
+    delete process.env.PORT;
+  }
   try {
     assert.ok(server);
     assert.equal(typeof server.listen, 'function');
     // Verify the server is listening by making a request.
     const address = server.address();
-    assert.ok(typeof address === 'object' && address.port > 0);
+    assert.ok(typeof address === 'object' && address !== null && address.port > 0);
   }
   finally {
+    server?.closeAllConnections?.();
+    await new Promise<void>(resolve => {
+      const timer = setTimeout(() => {
+        server?.closeAllConnections?.();
+        resolve();
+      }, 1000);
+      server?.close(() => {
+        clearTimeout(timer);
+        resolve();
+      });
+    });
+  }
+});
+
+test('serve uses the default port 3000 when PORT is not set', {timeout: 500}, async () => {
+  // Exercise the '|| 3000' fallback branch in serve by deleting PORT and calling
+  // serve directly. The server will attempt to bind to port 3000. On a system
+  // where port 3000 is free, it succeeds and we close it. Where it is occupied,
+  // the error event fires and we accept that as proof the fallback was reached.
+  const savedPort = process.env.PORT;
+  delete process.env.PORT;
+  try {
+    const server = await indexModule.serve(http, {});
+    let bindError: any = null;
+    server.on('error', error => {
+      bindError = error;
+    });
+    // Wait briefly for either successful binding or an EADDRINUSE error.
+    await new Promise<void>(resolve => {
+      const timer = setTimeout(resolve, 200);
+      server.on('listening', () => {
+        clearTimeout(timer);
+        resolve();
+      });
+    });
+    if (bindError) {
+      assert.equal(bindError.code, 'EADDRINUSE', `Expected EADDRINUSE, got: ${bindError.message}`);
+    }
+    else {
+      const address = server.address();
+      assert.ok(typeof address === 'object' && address !== null && address.port === 3000);
+    }
     server.closeAllConnections?.();
-    await new Promise(resolve => {
+    await new Promise<void>(resolve => {
       const timer = setTimeout(() => {
         server.closeAllConnections?.();
         resolve();
@@ -1076,13 +1396,21 @@ test('startServer starts an HTTP server when protocol is http', async () => {
       });
     });
   }
+  finally {
+    if (savedPort !== undefined) {
+      process.env.PORT = savedPort;
+    }
+    else {
+      delete process.env.PORT;
+    }
+  }
 });
 
 test('startServer starts an HTTPS server when protocol is https', {timeout: 2000}, async () => {
   // Generate a self-signed certificate for the test using openssl.
-  const {execSync} = require('node:child_process');
-  const os = require('node:os');
-  const fsSync = require('node:fs');
+  const {execSync} = await import('node:child_process');
+  const os = await import('node:os');
+  const fsSync = await import('node:fs');
   const tmpDir = fsSync.mkdtempSync(path.join(os.tmpdir(), 'kilotest-https-'));
   const keyPath = path.join(tmpDir, 'key.pem');
   const certPath = path.join(tmpDir, 'cert.pem');
@@ -1094,6 +1422,9 @@ test('startServer starts an HTTPS server when protocol is https', {timeout: 2000
   const savedProtocol = process.env.PROTOCOL;
   const savedKey = process.env.KEY;
   const savedCert = process.env.CERT;
+  // Use port 0 so the OS assigns an ephemeral port, avoiding collisions with production.
+  const savedPort = process.env.PORT;
+  process.env.PORT = '0';
   process.env.PROTOCOL = 'https';
   process.env.KEY = keyPath;
   process.env.CERT = certPath;
@@ -1102,9 +1433,9 @@ test('startServer starts an HTTPS server when protocol is https', {timeout: 2000
     assert.ok(server);
     assert.equal(typeof server.listen, 'function');
     const address = server.address();
-    assert.ok(typeof address === 'object' && address.port > 0);
+    assert.ok(typeof address === 'object' && address !== null && address.port > 0);
     server.closeAllConnections?.();
-    await new Promise(resolve => {
+    await new Promise<void>(resolve => {
       const timer = setTimeout(() => {
         server.closeAllConnections?.();
         resolve();
@@ -1134,43 +1465,37 @@ test('startServer starts an HTTPS server when protocol is https', {timeout: 2000
     else {
       delete process.env.CERT;
     }
+    if (savedPort !== undefined) {
+      process.env.PORT = savedPort;
+    }
+    else {
+      delete process.env.PORT;
+    }
     fsSync.rmSync(tmpDir, {recursive: true, force: true});
   }
 });
 
 test('runIfMain calls startServer when mainModule matches currentModule', async () => {
   let called = false;
-  const originalStartServer = indexModule.startServer;
-  indexModule.startServer = async () => {
+  const starter = async () => {
     called = true;
     return null;
   };
-  try {
-    // Pass the same object for both arguments so the guard is true.
-    const fakeModule = {};
-    runIfMain(fakeModule, fakeModule);
-    // Wait for the microtask queue to flush the promise.
-    await new Promise(resolve => setImmediate(resolve));
-    assert.equal(called, true);
-  }
-  finally {
-    indexModule.startServer = originalStartServer;
-  }
+  // Pass the same object for both arguments so the guard is true.
+  const fakeModule = {};
+  runIfMain(fakeModule, fakeModule, starter);
+  // Wait for the microtask queue to flush the promise.
+  await new Promise<void>(resolve => setImmediate(resolve));
+  assert.equal(called, true);
 });
 
 test('runIfMain does not call startServer when mainModule differs from currentModule', async () => {
   let called = false;
-  const originalStartServer = indexModule.startServer;
-  indexModule.startServer = async () => {
+  const starter = async () => {
     called = true;
     return null;
   };
-  try {
-    runIfMain({}, {});
-    await new Promise(resolve => setImmediate(resolve));
-    assert.equal(called, false);
-  }
-  finally {
-    indexModule.startServer = originalStartServer;
-  }
+  runIfMain({}, {}, starter);
+  await new Promise<void>(resolve => setImmediate(resolve));
+  assert.equal(called, false);
 });