@jrpool/kilotest 46.1.2 → 47.0.1

package/{index.js → index.ts}

@@ -1,70 +1,165 @@
 /*
-  index.js
+  index.ts
   Manages Kilotest.
 */
 
-// ENVIRONMENT
-
-require('dotenv').config({quiet: true});
-
 // IMPORTS
-const {
-  annotateReport,
+
+import dotenv from 'dotenv';
+import {
+  annotateReportObject,
   createLock,
+  deleteTestRequests,
+  errorMessage,
   getJobNames,
   getJSON,
   getObject,
   getPOSTData,
   getReport,
-  getRecs,
+  isReportError,
   getReportPath,
   hiddenReportsPath,
-  isHidden,
   isReportAvailable,
   isTimeStamp,
   isJobID,
+  isUsableReport,
   jobsPath,
-  recsLock,
   reportsPath
-} = require('./util');
-const {handleMCP, mcpPath} = require('./mcp');
-const fs = require('fs/promises');
-const {handleComment} = require('./web/tutorial/index');
-const http = require('http');
-const https = require('https');
-const path = require('path');
-const {sendAlert} = require('./alerts');
-const answer = {
-  ai0BalanceForm: require('./web/ai0BalanceForm/index').answer,
-  enqueue: require('./web/enqueue/index').answer,
-  enqueueForm: require('./web/enqueueForm/index').answer,
-  expungeReportsForm: require('./web/expungeReportsForm/index').answer,
-  hideReportForm: require('./web/hideReportForm/index').answer,
-  listDiagnoses: require('./web/listDiagnoses/index').answer,
-  listIssues: require('./web/listIssues/index').answer,
-  listReports: require('./web/listReports/index').answer,
-  listRules: require('./web/listRules/index').answer,
-  listTopIssues: require('./web/listTopIssues/index').answer,
-  listViolators: require('./web/listViolators/index').answer,
-  manage: require('./web/manage/index').answer,
-  pruneReportsForm: require('./web/pruneReportsForm/index').answer,
-  reannotate: require('./web/reannotate/index').answer,
-  reannotateForm: require('./web/reannotateForm/index').answer,
-  renewWCAG: require('./web/renewWCAG/index').answer,
-  renewWCAGForm: require('./web/renewWCAGForm/index').answer,
-  requestRetest: require('./web/requestRetest/index').answer,
-  requestRetestForm: require('./web/requestRetestForm/index').answer,
-  requestTest: require('./web/requestTest/index').answer,
-  requestTestForm: require('./web/requestTestForm/index').answer,
-  rewindReportsForm: require('./web/rewindReportsForm/index').answer,
-  unhideReportForm: require('./web/unhideReportForm/index').answer,
-  tutorial: require('./web/tutorial/index').answer
+} from './util.ts';
+import {sendAlert} from './alerts.ts';
+import {checkBalancesForAlerts} from './balances.ts';
+import type {Report} from 'testaro';
+import {handleMCP, mcpPath} from './mcp.ts';
+import fs from 'node:fs/promises';
+import {handleComment as handleTutorialWebComment} from './web/tutorialWeb/index.ts';
+import {answer as tutorialWeb} from './web/tutorialWeb/index.ts';
+import {answer as tutorialAI, handleComment as handleTutorialAIComment} from './web/tutorialAI/index.ts';
+import http, {type IncomingMessage, type ServerResponse} from 'node:http';
+import https from 'node:https';
+import path from 'node:path';
+import {answer as ai0BalanceForm} from './web/ai0BalanceForm/index.ts';
+import {answer as enqueue} from './web/enqueue/index.ts';
+import {answer as enqueueForm} from './web/enqueueForm/index.ts';
+import {answer as expungeReportsForm} from './web/expungeReportsForm/index.ts';
+import {answer as hideReportForm} from './web/hideReportForm/index.ts';
+import {answer as listDiagnosesPage} from './web/listDiagnoses/index.ts';
+import {answer as listIssuesPage} from './web/listIssues/index.ts';
+import {answer as listReportsPage} from './web/listReports/index.ts';
+import {answer as listRules} from './web/listRules/index.ts';
+import {answer as listTopIssues} from './web/listTopIssues/index.ts';
+import {answer as listViolatorsPage} from './web/listViolators/index.ts';
+import {answer as manage} from './web/manage/index.ts';
+import {answer as pruneReportsForm} from './web/pruneReportsForm/index.ts';
+import {answer as reannotate} from './web/reannotate/index.ts';
+import {answer as reannotateForm} from './web/reannotateForm/index.ts';
+import {answer as renewWCAG} from './web/renewWCAG/index.ts';
+import {answer as renewWCAGForm} from './web/renewWCAGForm/index.ts';
+import {answer as requestRetestPage} from './web/requestRetest/index.ts';
+import {answer as requestRetestForm} from './web/requestRetestForm/index.ts';
+import {answer as requestTestPage} from './web/requestTest/index.ts';
+import {answer as requestTestForm} from './web/requestTestForm/index.ts';
+import {answer as rewindReportsForm} from './web/rewindReportsForm/index.ts';
+import {answer as unhideReportForm} from './web/unhideReportForm/index.ts';
+import {response as getReportAPI} from './api/getReport.ts';
+import {response as listDiagnosesAPI} from './api/listDiagnoses.ts';
+import {response as listIssuesAPI} from './api/listIssues.ts';
+import {response as listReportsAPI} from './api/listReports.ts';
+import {response as listViolatorsAPI} from './api/listViolators.ts';
+import {response as requestFeatureAPI} from './api/requestFeature.ts';
+import {response as requestRetestAPI} from './api/requestRetest.ts';
+import {response as requestTestAPI} from './api/requestTest.ts';
+
+// ENVIRONMENT
+
+dotenv.config({quiet: true});
+
+// CONSTANTS
+
+// The data returned by a page-answering handler.
+type AnswerData = {status: string; message?: string; answerPage?: string};
+// A page-answering handler, whose parameters vary by topic.
+type PageHandler = (...args: any[]) => Promise<AnswerData>;
+
+const answer: {
+  ai0BalanceForm: PageHandler;
+  enqueue: PageHandler;
+  enqueueForm: PageHandler;
+  expungeReportsForm: PageHandler;
+  hideReportForm: PageHandler;
+  listDiagnoses: PageHandler;
+  listIssues: PageHandler;
+  listReports: PageHandler;
+  listRules: PageHandler;
+  listTopIssues: PageHandler;
+  listViolators: PageHandler;
+  manage: PageHandler;
+  pruneReportsForm: PageHandler;
+  tutorialWeb: PageHandler;
+  tutorialAI: PageHandler;
+  reannotate: PageHandler;
+  reannotateForm: PageHandler;
+  renewWCAG: PageHandler;
+  renewWCAGForm: PageHandler;
+  requestRetest: PageHandler;
+  requestRetestForm: PageHandler;
+  requestTest: PageHandler;
+  requestTestForm: PageHandler;
+  rewindReportsForm: PageHandler;
+  unhideReportForm: PageHandler;
+  [key: string]: PageHandler | undefined;
+} = {
+  ai0BalanceForm,
+  enqueue,
+  enqueueForm,
+  expungeReportsForm,
+  hideReportForm,
+  listDiagnoses: listDiagnosesPage,
+  listIssues: listIssuesPage,
+  listReports: listReportsPage,
+  listRules,
+  listTopIssues,
+  listViolators: listViolatorsPage,
+  manage,
+  pruneReportsForm,
+  tutorialWeb,
+  tutorialAI,
+  reannotate,
+  reannotateForm,
+  renewWCAG,
+  renewWCAGForm,
+  requestRetest: requestRetestPage,
+  requestRetestForm,
+  requestTest: requestTestPage,
+  requestTestForm,
+  rewindReportsForm,
+  unhideReportForm
+};
+// Response functions of the API services.
+type ApiResponder = (args: string[]) => Promise<unknown>;
+const apiRespond: {
+  getReport: ApiResponder;
+  listDiagnoses: ApiResponder;
+  listIssues: ApiResponder;
+  listReports: ApiResponder;
+  listViolators: ApiResponder;
+  requestFeature: ApiResponder;
+  requestRetest: ApiResponder;
+  requestTest: ApiResponder;
+} = {
+  getReport: getReportAPI,
+  listDiagnoses: listDiagnosesAPI,
+  listIssues: listIssuesAPI,
+  listReports: listReportsAPI,
+  listViolators: listViolatorsAPI,
+  requestFeature: requestFeatureAPI,
+  requestRetest: requestRetestAPI,
+  requestTest: requestTestAPI
 };
 
 // CONSTANTS
 
 // Paths that the application is authorized to handle, by method, as glob-style patterns where * matches any sequence of characters.
-const routes = exports.routes = {
+export const routes = {
   GET: [
     '*.html*',
     '/',
@@ -79,46 +174,31 @@ const routes = exports.routes = {
     '/mcp',
     '/openapi.json',
     '/openapi.yaml',
+    '/qai',
+    '/qai/comments',
     '/robots.txt',
     '/sitemap.xml',
     '/style.css',
     '/swagger.json',
     '/swagger.yaml',
-    '/tutorial/images/*'
+    '/tutorialWeb/images/*',
+    '/tutorialAI/images/*'
   ],
   POST: [
     '/api/*',
     '/mcp',
+    '/tutorialAIComment.html',
     '/reannotate.html',
-    '/recAction.html',
+    '/requestAction.html',
     '/renewWCAG.html',
     '/requestRetest.html/*',
     '/requestTest.html',
-    '/tutorialComment.html',
+    '/tutorialWebComment.html',
     '/worker/job',
     '/worker/report'
   ]
 };
-const protocol = process.env.PROTOCOL || 'http';
-// Credentials of the Testaro workers, by worker ID, from a JSON-object environment variable.
-// Each worker ID maps to a secret (used only to authenticate the worker, never published) and a
-// name (a non-secret label safe to publish, e.g. in report data and logs).
-const workerCredentials = (() => {
-  try {
-    return JSON.parse(process.env.TESTARO_WORKERS || '{}');
-  }
-  catch (error) {
-    console.error(`ERROR: TESTARO_WORKERS is not valid JSON (${error.message})`);
-    return {};
-  }
-})();
-// Values that may require alerts.
-const balancePath = path.join(__dirname, 'ai0Balance.json');
 const jobLock = createLock();
-const WAVE_THRESHOLD = Number(process.env.WAVE_BALANCE_THRESHOLD);
-const AI_SERVICE0_THRESHOLD = Number(process.env.AI_SERVICE0_BALANCE_THRESHOLD);
-const AI_MODEL0_INPUT_PRICE = Number(process.env.AI_MODEL0_INPUT_PRICE);
-const AI_MODEL0_OUTPUT_PRICE = Number(process.env.AI_MODEL0_OUTPUT_PRICE);
 
 // FUNCTIONS
 
@@ -126,19 +206,19 @@ const queuePath = () => path.join(jobsPath(), 'queue');
 const claimedPath = () => path.join(jobsPath(), 'claimed');
 const failedPath = () => path.join(jobsPath(), 'failed');
 // Returns whether a pathname matches a glob-style pattern.
-const matchPath = (pattern, pathname) => {
+const matchPath = (pattern: string, pathname: string) => {
   const regex = new RegExp(
     '^' + pattern.replace(/[.+?^${}()|[\]\\]/g, '\\$&').replace(/\*/g, '.*') + '$'
   );
   return regex.test(pathname);
 };
 // Returns whether a pathname is authorized for a method.
-const isPathAllowed = exports.isPathAllowed = (method, pathname) => {
-  const patterns = routes[method] || [];
+export const isPathAllowed = (method: string, pathname: string): boolean => {
+  const patterns = (routes as Record<string, string[]>)[method] || [];
   return patterns.some(pattern => matchPath(pattern, pathname));
 };
 // Serves or sends an error message.
-const serveError = exports.serveError = async (error, response, isHumanUser = true, statusCode = 400) => {
+export const serveError = async (error: Record<string, unknown>, response: ServerResponse, isHumanUser = true, statusCode = 400): Promise<void> => {
   const errorLines = Object.entries(error).map(pair => `${pair[0]}: ${pair[1]}`);
   const errorSummary = errorLines.join('\n') || 'ERROR';
   console.log(errorSummary);
@@ -152,7 +232,7 @@ const serveError = exports.serveError = async (error, response, isHumanUser = tr
       response.setHeader('Access-Control-Allow-Origin', '*');
       response.setHeader('Cache-Control', 'public, max-age=300, stale-while-revalidate=3000');
       const errorTemplate = await fs.readFile('error.html', 'utf8');
-      const errorMessage = error.message || 'ERROR';
+      const errorMessage = typeof error.message === 'string' ? error.message : 'ERROR';
       const errorPage = errorTemplate.replace(/__error__/, errorMessage);
       response.end(errorPage);
     }
@@ -167,68 +247,8 @@ const serveError = exports.serveError = async (error, response, isHumanUser = tr
     console.log('Cannot send error response because the response has ended.');
   }
 };
-// Checks a report for balances nearing exhaustion.
-const checkBalancesForAlerts = async report => {
-  // If the variables to be monitored for alerts are defined:
-  if (WAVE_THRESHOLD && AI_SERVICE0_THRESHOLD && AI_MODEL0_INPUT_PRICE && AI_MODEL0_OUTPUT_PRICE) {
-    // WAVE.
-    const waveAct = report.acts.find(act => act.type === 'test' && act.which === 'wave');
-    const creditsRemaining = waveAct?.data?.creditsRemaining;
-    // If a WAVE balance nearing exhaustion is reported:
-    if (typeof creditsRemaining === 'number' && creditsRemaining < WAVE_THRESHOLD) {
-      // Alert a manager.
-      await sendAlert(
-        'Kilotest: WAVE balance low',
-        `Only ${creditsRemaining} WAVE credits remain (3 used per job)`
-      );
-    }
-    const testaroAct = report.acts.find(act => act.type === 'test' && act.which === 'testaro');
-    // Get the AI model token usage for the testaro allCaps test.
-    const usage = testaroAct?.data?.ruleData?.allCaps?.aiModelUsage;
-    let balanceJSON = null;
-    try {
-      // Get the recorded AI service 0 balance.
-      balanceJSON = await fs.readFile(balancePath, 'utf8');
-    }
-    catch {
-      console.error('ERROR: AI service 0 balance file missing');
-    }
-    // If the variables required for an AI service 0 balance alert are defined:
-    if (usage && AI_MODEL0_INPUT_PRICE && AI_MODEL0_OUTPUT_PRICE && balanceJSON) {
-      const inputCost = AI_MODEL0_INPUT_PRICE * usage.inputTokens;
-      const outputCost = AI_MODEL0_OUTPUT_PRICE * usage.outputTokens;
-      const cost = inputCost + outputCost;
-      // If any cost was incurred:
-      if (cost > 0) {
-        // Warn about this.
-        console.log(
-          'This job has made the production AI service 0 balance record wrong. Update it.'
-        );
-      }
-      try {
-        const balanceData = JSON.parse(balanceJSON);
-        // Get an estimate of the balance after this job.
-        const newBalance = balanceData.balance - cost;
-        // Update the recorded balance.
-        await fs.writeFile(balancePath, getJSON({balance: newBalance}));
-        console.log(`Estimated new AI Service 0 balance: $${newBalance.toFixed(2)}`);
-        // If it is nearing exhaustion:
-        if (newBalance < AI_SERVICE0_THRESHOLD) {
-          // Alert a manager.
-          await sendAlert(
-            'Kilotest: AI service 0 balance low',
-            `Balance of AI service 0 account (https://console.anthropic.com) only about $${newBalance.toFixed(2)} (about $0.01 used per job)`
-          );
-        }
-      }
-      catch (error) {
-        console.log(`ERROR managing AI service 0 balance: ${error.message}`);
-      }
-    }
-  }
-};
 // Creates an error object about a suspicious request.
-const getAbuseError = exports.getAbuseError = (request, reason) => {
+export const getAbuseError = (request: IncomingMessage, reason: string | undefined) => {
   const {method, url, headers} = request;
   const forwardedFor = headers['x-forwarded-for'];
   const remoteAddress = request.socket.remoteAddress;
@@ -246,23 +266,36 @@ const getAbuseError = exports.getAbuseError = (request, reason) => {
 };
 // Gets the ID and secret from a request's HTTP Basic Authorization header, or null if the header
 // is absent or malformed.
-const getBasicAuth = request => {
+const getBasicAuth = (request: IncomingMessage) => {
   const header = request.headers['authorization'] || '';
   const match = header.match(/^Basic\s+(\S+)$/i);
   if (!match) {
     return null;
   }
-  const decoded = Buffer.from(match[1], 'base64').toString('utf8');
+  const decoded = Buffer.from(match[1]!, 'base64').toString('utf8');
   const sepIndex = decoded.indexOf(':');
   if (sepIndex === -1) {
     return null;
   }
   return {id: decoded.slice(0, sepIndex), secret: decoded.slice(sepIndex + 1)};
 };
+// Returns the credentials of the Testaro workers, by worker ID, from a JSON-object
+// environment variable. Each worker ID maps to a secret (used only to authenticate the worker,
+// never published) and a name (a non-secret label safe to publish, e.g. in report data and logs).
+const getWorkerCredentials = () => {
+  try {
+    return JSON.parse(process.env.TESTARO_WORKERS || '{}');
+  }
+  catch (error) {
+    console.error(`ERROR: TESTARO_WORKERS is not valid JSON (${errorMessage(error)})`);
+    return {};
+  }
+};
 // Gets the published name of a Testaro worker or null if not authenticated.
-const getAuthorizedWorkerName = request => {
+const getAuthorizedWorkerName = (request: IncomingMessage) => {
   const credentials = getBasicAuth(request);
   if (credentials) {
+    const workerCredentials = getWorkerCredentials();
     const worker = workerCredentials[credentials.id];
     if (worker && worker.secret === credentials.secret && worker.name) {
       return worker.name;
@@ -271,7 +304,7 @@ const getAuthorizedWorkerName = request => {
   return null;
 };
 // Processes a job request from a Testaro worker.
-const processJobRequest = async (request, response, workerName) => jobLock(async () => {
+const processJobRequest = async (request: IncomingMessage, response: ServerResponse, workerName: string) => jobLock(async () => {
   let clean = true;
   const messageStart = `Testaro worker ${workerName} requested a job, `;
   const jobNames = await getJobNames();
@@ -279,7 +312,7 @@ const processJobRequest = async (request, response, workerName) => jobLock(async
   // For each claimed job:
   for (const jobName of claimedJobNames) {
     const job = await getObject(path.join(jobsPath(), 'claimed', jobName));
-    const {id, sources} = job;
+    const {id, sources} = job as {id: string, sources: {worker: string}};
     const {worker} = sources;
     // If its assignee is the worker:
     if (worker === workerName) {
@@ -300,9 +333,9 @@ const processJobRequest = async (request, response, workerName) => jobLock(async
     const queuedJobNames = jobNames.queue;
     // If any jobs are queued:
     if (queuedJobNames.length) {
-      const oldestJobName = queuedJobNames[0];
+      const oldestJobName = queuedJobNames[0]!;
       // Get the first one.
-      const firstJob = await getObject(path.join(queuePath(), oldestJobName));
+      const firstJob = await getObject(path.join(queuePath(), oldestJobName)) as {id: string, sources: {worker: string}, target: {what: string}};
       // Add the public worker name to the job, in a property Testaro does not read or alter.
       firstJob.sources.worker = workerName;
       console.log(
@@ -336,15 +369,15 @@ const processJobRequest = async (request, response, workerName) => jobLock(async
   }
 });
 // Handles a request.
-const requestHandler = async (request, response) => {
+const handleRequest = async (request: IncomingMessage, response: ServerResponse) => {
   // Sets response headers.
-  const setHeaders = (contentType, location, volatility = 'high') => {
+  const setHeaders = (contentType: string, location: string | null, volatility: string = 'high') => {
     response.setHeader('content-type', `${contentType}; charset=utf-8`);
     if (location) {
       response.setHeader('content-location', location);
     }
     response.setHeader('Access-Control-Allow-Origin', '*');
-    const lives = {
+    const lives: Record<string, number[]> = {
       ultra: [3, 30],
       high: [300, 3000],
       medium: [1000, 10000],
@@ -352,13 +385,13 @@ const requestHandler = async (request, response) => {
     };
     response.setHeader(
       'Cache-Control',
-      `public, max-age=${lives[volatility][0]}, stale-while-revalidate=${lives[volatility][1]}`
+      `public, max-age=${lives[volatility]![0]}, stale-while-revalidate=${lives[volatility]![1]}`
     );
   };
   const {method, url} = request;
-  const requestURL = new URL(url, 'https://localhost:3000');
+  const requestURL = new URL(url as string, 'https://localhost:3000');
   const {pathname, search} = requestURL;
-  const pageName = pathname.split('/')[1];
+  const pageName = pathname.split('/')[1]!;
   const pathTail = pathname.split('/').slice(2).join('/');
   // If the request is a smoke-test probe, respond perfunctorily without executing a handler.
   if (request.headers['x-kilotest-smoke']) {
@@ -374,8 +407,19 @@ const requestHandler = async (request, response) => {
     }
     // If it is for the model context protocol server:
     else if (pathname === mcpPath) {
-      // Handle the MCP request.
-      await handleMCP(request, response);
+      // If the request does not identify itself as capable of an SSE stream: it is a human
+      // browsing to the endpoint directly, not an MCP client, so explain what the endpoint is
+      // for instead of handing it a bare protocol-level rejection.
+      if (!request.headers.accept?.includes('text/event-stream')) {
+        await serveError({
+          message: 'This endpoint is for AI agents, not for direct browsing. See the <a href="/tutorialAI.html">tutorial on connecting an AI platform to Kilotest</a>.'
+        }, response);
+      }
+      // Otherwise, i.e. if it identifies itself as capable of an SSE stream:
+      else {
+        // Handle the MCP request.
+        await handleMCP(request, response);
+      }
     }
     // Otherwise, if it is for the home page:
     else if (['/', '/index.html'].includes(pathname)) {
@@ -405,6 +449,18 @@ const requestHandler = async (request, response) => {
       response.writeHead(301, {Location: '/openapi.yaml'});
       response.end();
     }
+    // Otherwise, if it is for the old QAI comments path:
+    else if (pathname === '/qai/comments') {
+      // Redirect the client permanently to the new tutorial path (comments are now integrated).
+      response.writeHead(301, {Location: '/tutorialAI.html'});
+      response.end();
+    }
+    // Otherwise, if it is for the old QAI root path:
+    else if (pathname === '/qai') {
+      // Redirect the client permanently to the new tutorial path.
+      response.writeHead(301, {Location: '/tutorialAI.html'});
+      response.end();
+    }
     // Otherwise, if it is for the large-language-model summary guide:
     else if (pageName === 'llms.txt') {
       const llms = await fs.readFile('llms.txt', 'utf8');
@@ -435,43 +491,37 @@ const requestHandler = async (request, response) => {
     }
     // Otherwise, if it is for a full report download:
     else if (pageName === 'fullReport.json') {
-      const [timeStamp, jobID] = pathTail.split('/');
+      const [timeStamp, jobID] = pathTail.split('/') as [string, string, ...string[]];
       // If the request is syntactically valid:
       if (isTimeStamp(timeStamp) && isJobID(jobID)) {
-        const reportHidden = await isHidden(timeStamp, jobID);
-        // If the report exists and is hidden:
-        if (reportHidden) {
-          console.error(`Hidden report ${timeStamp}-${jobID} requested`);
-          // Report this as suspected abuse.
-          await serveError(
-            getAbuseError(request, `Hidden report ${timeStamp}-${jobID} requested`),
-            response,
-            true
+        // Get it.
+        const report = await getReport(timeStamp, jobID);
+        // If this failed:
+        if (isReportError(report)) {
+          // This is not necessarily abuse: the link may have been generated (e.g. by
+          // listIssues.html) before the report was pruned or rewound, or the stored report
+          // may have become unreadable or unusable, none of which is the requester's fault.
+          // So tell the requester only that the request was invalid, without accusing them,
+          // but alert a manager with the real reason, since a syntactically valid report ID
+          // should otherwise always be usable.
+          console.error(
+            `Full report ${timeStamp}-${jobID} requested but unavailable (${report.error})`
+          );
+          await sendAlert(
+            'Kilotest: requested full report unavailable',
+            `Full report ${timeStamp}-${jobID} was requested but could not be retrieved: ${report.error}`
           );
+          await serveError({message: 'ERROR: Invalid request'}, response, true);
         }
-        // Otherwise, i.e. if the report is not hidden:
+        // Otherwise, i.e. if it succeeded:
         else {
-          // Get it.
-          const report = await getReport(timeStamp, jobID);
-          // If this failed:
-          if (report.error) {
-            // Report this as suspected abuse.
-            await serveError(
-              getAbuseError(request, `Nonexistent report ${timeStamp}-${jobID} requested`),
-              response,
-              true
-            );
-          }
-          // Otherwise, i.e. if it succeeded:
-          else {
-            // Serve response headers for a JSON download.
-            setHeaders('application/json', null, 'low');
-            response.setHeader(
-              'content-disposition', `attachment; filename="${timeStamp}-${jobID}.json"`,
-            );
-            // Download the report.
-            response.end(getJSON(report));
-          }
+          // Serve response headers for a JSON download.
+          setHeaders('application/json', null, 'low');
+          response.setHeader(
+            'content-disposition', `attachment; filename="${timeStamp}-${jobID}.json"`,
+          );
+          // Download the report.
+          response.end(getJSON(report));
         }
       }
       // Otherwise, i.e. if the request is syntactically invalid:
@@ -511,8 +561,7 @@ const requestHandler = async (request, response) => {
       // If the service lists the available reports:
       if (service === 'listReports') {
         // Get the response body.
-        const responseBody = await require(path.join(__dirname, 'api', 'listReports'))
-        .response(specs);
+        const responseBody = await apiRespond.listReports([]);
         // Send it.
         setHeaders('application/json', null, 'ultra');
         response.end(JSON.stringify(responseBody));
@@ -520,8 +569,7 @@ const requestHandler = async (request, response) => {
       // Otherwise, if the service lists the issues in a report:
       else if (service === 'listIssues') {
         // Get the response body.
-        const responseBody = await require(path.join(__dirname, 'api', 'listIssues'))
-        .response(specs);
+        const responseBody = await apiRespond.listIssues(specs);
         // Send it.
         setHeaders('application/json', null, 'high');
         response.end(JSON.stringify(responseBody));
@@ -529,8 +577,7 @@ const requestHandler = async (request, response) => {
       // Otherwise, if the service lists the violators of an issue in a report:
       else if (service === 'listViolators') {
         // Get the response body.
-        const responseBody = await require(path.join(__dirname, 'api', 'listViolators'))
-        .response(specs);
+        const responseBody = await apiRespond.listViolators(specs);
         // Send it.
         setHeaders('application/json', null, 'high');
         response.end(JSON.stringify(responseBody));
@@ -538,8 +585,7 @@ const requestHandler = async (request, response) => {
       // Otherwise, if the service lists the diagnoses of a violation of an issue in a report:
       else if (service === 'listDiagnoses') {
         // Get the response body.
-        const responseBody = await require(path.join(__dirname, 'api', 'listDiagnoses'))
-        .response(specs);
+        const responseBody = await apiRespond.listDiagnoses(specs);
         // Send it.
         setHeaders('application/json', null, 'high');
         response.end(JSON.stringify(responseBody));
@@ -547,8 +593,7 @@ const requestHandler = async (request, response) => {
       // Otherwise, if the service serves a report:
       else if (service === 'getReport') {
         // Get the response body.
-        const responseBody = await require(path.join(__dirname, 'api', 'getReport'))
-        .response(specs);
+        const responseBody = await apiRespond.getReport(specs);
         // Send it.
         setHeaders('application/json', null, 'low');
         response.end(JSON.stringify(responseBody));
@@ -560,13 +605,22 @@ const requestHandler = async (request, response) => {
       }
     }
     // Otherwise, if it is for a tutorial image:
-    else if (pathname.startsWith('/tutorial/images/')) {
-      const imgFile = pathname.slice('/tutorial/images/'.length);
-      const imgPath = path.join(__dirname, 'web', 'tutorial', 'images', imgFile);
+    else if (pathname.startsWith('/tutorialWeb/images/') || pathname.startsWith('/tutorialAI/images/')) {
+      let imgFile: string;
+      let tutorialDir: string;
+      if (pathname.startsWith('/tutorialWeb/images/')) {
+        imgFile = pathname.slice('/tutorialWeb/images/'.length);
+        tutorialDir = 'tutorialWeb';
+      }
+      else {
+        imgFile = pathname.slice('/tutorialAI/images/'.length);
+        tutorialDir = 'tutorialAI';
+      }
+      const imgPath = path.join(import.meta.dirname, 'web', tutorialDir, 'images', imgFile);
       try {
         const img = await fs.readFile(imgPath);
         const ext = path.extname(imgFile).toLowerCase();
-        const mimeTypes = {
+        const mimeTypes: Record<string, string> = {
           '.png': 'image/png',
           '.jpg': 'image/jpeg',
           '.jpeg': 'image/jpeg',
@@ -585,7 +639,7 @@ const requestHandler = async (request, response) => {
     // Otherwise, if it is for the application icon:
     else if (pathname.includes('favicon.')) {
       // Get the site icon.
-      const icon = await fs.readFile(path.join(__dirname, 'favicon.ico'));
+      const icon = await fs.readFile(path.join(import.meta.dirname, 'favicon.ico'));
       // Serve it.
       setHeaders('image/x-icon', null, 'low');
       response.write(icon, 'binary');
@@ -600,7 +654,7 @@ const requestHandler = async (request, response) => {
         response.end(styleSheet);
       }
       catch (error) {
-        await serveError({message: error.message}, response, true);
+        await serveError({message: errorMessage(error)}, response, true);
       }
     }
     // Otherwise, i.e. if it is any other GET request:
@@ -625,13 +679,17 @@ const requestHandler = async (request, response) => {
     else {
       // Get the data from the request body.
       const postData = await getPOSTData(request);
-      // If the request is a test recommendation:
-      if (pageName === 'requestTest.html') {
-        const {what, url, why} = postData;
+      // If the body could not be parsed (unknown content-type or malformed JSON):
+      if (postData === null) {
+        await serveError({message: 'ERROR: Unreadable request body'}, response, true);
+      }
+      // If the request is a test request:
+      else if (pageName === 'requestTest.html') {
+        const {description, url, why} = postData as {description?: string; url: string; why?: string};
         // If the request is valid:
-        if (what && url.startsWith('https://') && why) {
+        if (description && url.startsWith('https://') && why) {
           // If a report on the page is already available:
-          if (await isReportAvailable(what, url)) {
+          if (await isReportAvailable(description, url)) {
             // Report the error.
             await serveError({message: 'ERROR: Page has already been tested'}, response, true);
           }
@@ -640,8 +698,7 @@ const requestHandler = async (request, response) => {
             // Serve headers for a response.
             setHeaders('text/html', pathname, 'ultra');
             // Get the answer data.
-            const answerData = await require(path.join(__dirname, 'web', 'requestTest', 'index'))
-            .answer(what, url, why);
+            const answerData = await answer.requestTest(description, url, why);
             // If they are valid:
             if (answerData.status === 'ok') {
               // Serve the answer page.
@@ -657,20 +714,19 @@ const requestHandler = async (request, response) => {
         // Otherwise, i.e. if the request is invalid:
         else {
           // Report the error.
-          await serveError({message: 'ERROR: Invalid test recommendation'}, response, true);
+          await serveError({message: 'ERROR: Invalid test request'}, response, true);
         }
       }
-      // Otherwise, if it is a retest recommendation:
+      // Otherwise, if it is a retest request:
       else if (pageName === 'requestRetest.html') {
-        const {why} = postData;
-        const [timeStamp, jobID] = pathTail.split('/');
+        const {why} = postData as {why?: string};
+        const [timeStamp, jobID] = pathTail.split('/') as [string, string, ...string[]];
         // If the request is valid:
         if (isTimeStamp(timeStamp) && isJobID(jobID) && why) {
           // Serve response headers.
           setHeaders('text/html', pathname, 'ultra');
           // Get the answer data.
-          const answerData = await require(path.join(__dirname, 'web', 'requestRetest', 'index'))
-          .answer(pathTail, why);
+          const answerData = await answer.requestRetest(pathTail, why);
           // If they are valid:
           if (answerData.status === 'ok') {
             // Serve the answer page.
@@ -685,24 +741,23 @@ const requestHandler = async (request, response) => {
         // Otherwise, i.e. if the request is invalid:
         else {
           // Report the error.
-          await serveError({message: 'ERROR: Invalid retest recommendation'}, response, true);
+          await serveError({message: 'ERROR: Invalid retest request'}, response, true);
         }
       }
       // Otherwise, if it is an approval or rejection of a test request:
-      else if (pageName === 'recAction.html') {
-        const {target, authCode} = postData;
-        const [url, what] = target.split('\t');
+      else if (pageName === 'requestAction.html') {
+        const {target, authCode} = postData as {target: string; authCode?: string};
+        const [url, description] = target.split('\t') as [string, string];
         // If the request is valid:
         if (url.startsWith('https://') && authCode === process.env.AUTH_CODE) {
           // Set the non-location headers for a response.
           setHeaders('text/html', null, 'ultra');
           // If the request is an approval:
-          if (what) {
+          if (description) {
             // Set a location header for a response.
             response.setHeader('content-location', pathname);
-            // Process the approval and get the answer data about the remaining recommendations.
-            const answerData = await require(path.join(__dirname, 'web', 'enqueue', 'index'))
-            .answer(url, what, authCode);
+            // Process the approval and get the answer data about the remaining requests.
+            const answerData = await answer.enqueue(url, description, authCode);
             // If the answer data are valid:
             if (answerData.status === 'ok') {
               // Serve the test-order page with the remaining recommendations.
@@ -716,20 +771,12 @@ const requestHandler = async (request, response) => {
           }
           // Otherwise, i.e. if it is a rejection:
           else {
-            // Isolate this revision.
-            await recsLock(async () => {
-              // Get the recommendations.
-              const recs = await getRecs();
-              // Delete the rejected URL.
-              delete recs[url];
-              // Save the revised recommendations.
-              await fs.writeFile(path.join(jobsPath(), 'recs.json'), getJSON(recs));
-            });
+            // Delete the test requests for the URL.
+            await deleteTestRequests(url);
             // Set a location header for a response.
             response.setHeader('content-location', '/enqueueForm.html');
             // Get the answer data.
-            const answerData = await require(path.join(__dirname, 'web', 'enqueueForm', 'index'))
-            .answer();
+            const answerData = await answer.enqueueForm();
             // Serve the test-order form with the remaining recommendations.
             response.end(answerData.answerPage);
           }
@@ -742,12 +789,11 @@ const requestHandler = async (request, response) => {
       }
       // Otherwise, if it is a reannotation order:
       else if (pageName === 'reannotate.html') {
-        const {authCode} = postData;
+        const {authCode} = postData as {authCode?: string};
         // Set headers for a response.
         setHeaders('text/html', pathname, 'ultra');
         // Get the answer data.
-        const answerData = await require(path.join(__dirname, 'web', 'reannotate', 'index'))
-        .answer(authCode);
+        const answerData = await answer.reannotate(authCode);
         // If the answer data are valid:
         if (answerData.status === 'ok') {
           // Serve the answer page.
@@ -761,12 +807,11 @@ const requestHandler = async (request, response) => {
       }
       // Otherwise, if it is a WCAG map renewal:
       else if (pageName === 'renewWCAG.html') {
-        const {authCode} = postData;
+        const {authCode} = postData as {authCode?: string};
         // Set headers for a response.
         setHeaders('text/html', pathname, 'low');
         // Get the answer data.
-        const answerData = await require(path.join(__dirname, 'web', 'renewWCAG', 'index'))
-        .answer(authCode);
+        const answerData = await answer.renewWCAG(authCode);
         // If the answer data are valid:
         if (answerData.status === 'ok') {
           // Serve the answer page.
@@ -793,37 +838,68 @@ const requestHandler = async (request, response) => {
           }
           // Otherwise, if it is report acquisition:
           else if (service === 'report') {
-            const {report} = postData;
-            const reportObj = report || {};
+            const {report} = postData as {report?: Report};
+            const reportObj: Partial<Report> = report ?? {};
             const {id, target} = reportObj;
-            const {what, url} = target || {};
-            const [timeStamp, jobID] = id?.split('-') ?? ['', ''];
+            const {what: description, url} = (target ?? {}) as Partial<NonNullable<Report['target']>>;
+            const [timeStamp, jobID] = (id?.split('-') ?? ['', '']) as [string, string];
             // If the request is syntactically valid:
-            if (id && isTimeStamp(timeStamp) && isJobID(jobID) && what && url) {
-              const [timeStamp, jobID] = id.split('-');
-              // Get the job the report is from.
-              const claimedJob = await getObject(path.join(claimedPath(), `${id}.json`));
+            if (id && isTimeStamp(timeStamp) && isJobID(jobID) && description && url) {
+              // Get the job the report is from. A missing claimed-job file (the job was
+              // never claimed, or was already completed) is a normal outcome, handled below
+              // as if the job were not assigned to this worker; any other failure to read it
+              // should never occur and is left to propagate.
+              let claimedJob: unknown = null;
+              try {
+                claimedJob = await getObject(path.join(claimedPath(), `${id}.json`));
+              }
+              catch (error: unknown) {
+                if (!(error instanceof Error && (error.cause as NodeJS.ErrnoException | undefined)?.code === 'ENOENT')) {
+                  throw error;
+                }
+              }
               // If the job was actually assigned to this worker:
-              if (typeof claimedJob === 'object' && claimedJob.sources?.worker === workerName) {
-                console.log(`Testaro report ${id} was received from worker ${workerName}`);
-                // Add the public worker name to the report.
-                report.sources = {...report.sources, worker: workerName};
-                // Save the report.
-                await fs.writeFile(getReportPath(timeStamp, jobID), getJSON(report));
-                // Annotate the report.
-                await annotateReport(timeStamp, jobID);
-                console.log(`Testaro report ${id} was annotated, saved, and indexed`);
-                // Check the monetary balances and send alerts if nearing exhaustion.
-                await checkBalancesForAlerts(report);
-                // Delete the job.
-                await fs.unlink(path.join(claimedPath(), `${id}.json`));
-                console.log(`Completed job ${id} deleted`);
-                // Acknowledge receipt.
-                response.setHeader('content-type', 'application/json; charset=utf-8');
-                response.end(JSON.stringify({status: 'ok'}));
-                console.log(
-                  `Testaro report ${id} was received from Testaro worker ${workerName}`
-                );
+              if (typeof claimedJob === 'object' && claimedJob !== null && (claimedJob as {sources?: {worker?: string}}).sources?.worker === workerName) {
+                // If the report is usable by Kilotest (as any report of an assigned job should be):
+                if (isUsableReport(reportObj)) {
+                  console.log(`Testaro report ${id} was received from worker ${workerName}`);
+                  // Add the public worker name to the report.
+                  report!.sources = {...report!.sources, worker: workerName};
+                  // Annotate the report before it is ever written, rather than writing it,
+                  // reading it back, annotating that copy, and writing it again: the read-back
+                  // could fail even though the just-written report is fine.
+                  await annotateReportObject(reportObj);
+                  // Save the annotated report.
+                  await fs.writeFile(getReportPath(timeStamp, jobID), getJSON(report));
+                  console.log(`Testaro report ${id} was annotated and saved`);
+                  // Check the monetary balances and send alerts if nearing exhaustion.
+                  await checkBalancesForAlerts(report!);
+                  // Delete the job.
+                  await fs.unlink(path.join(claimedPath(), `${id}.json`));
+                  console.log(`Completed job ${id} deleted`);
+                  // Acknowledge receipt.
+                  response.setHeader('content-type', 'application/json; charset=utf-8');
+                  response.end(JSON.stringify({status: 'ok'}));
+                  console.log(
+                    `Testaro report ${id} was received from Testaro worker ${workerName}`
+                  );
+                }
+                // Otherwise, i.e. if the report is not usable by Kilotest:
+                else {
+                  console.error(`ERROR: Report ${id} from worker ${workerName} is not usable`);
+                  // Alert a manager, since an assigned job should never produce an unusable report.
+                  await sendAlert(
+                    'Kilotest: unusable report received',
+                    `Job ${id} from worker ${workerName} produced a report that Kilotest cannot use. The job was reclassified as failed instead of being recorded.`
+                  );
+                  // Reclassify the job as failed, instead of recording the unusable report or
+                  // leaving the job claimed indefinitely.
+                  await fs.rename(
+                    path.join(claimedPath(), `${id}.json`), path.join(failedPath(), `${id}.json`)
+                  );
+                  // Report the error.
+                  await serveError({message: `ERROR: Report ${id} is not usable`}, response, false);
+                }
               }
               // Otherwise, i.e. if the job was not assigned to this worker:
               else {
@@ -857,30 +933,27 @@ const requestHandler = async (request, response) => {
         const segments = pathTail.split('/');
         // If the service is to receive a test request:
         if (segments[0] === 'requestTest') {
-          const {description, URL, reason} = postData;
+          const {description, URL, reason} = postData as {description: string; URL: string; reason: string};
           // Get the response body.
-          const responseBody = await require(path.join(__dirname, 'api', 'requestTest'))
-          .response([description, URL, reason]);
+          const responseBody = await apiRespond.requestTest([description, URL, reason]);
           // Send it.
           setHeaders('application/json', null, 'ultra');
           response.end(JSON.stringify(responseBody));
         }
         // Otherwise, if the service is to receive a retest request:
         else if (segments[0] === 'requestRetest') {
-          const {reason} = postData;
+          const {reason} = postData as {reason: string};
           // Get the response body.
-          const responseBody = await require(path.join(__dirname, 'api', 'requestRetest'))
-          .response(segments.slice(1).concat(reason));
+          const responseBody = await apiRespond.requestRetest(segments.slice(1).concat(reason));
           // Send it.
           setHeaders('application/json', null, 'ultra');
           response.end(JSON.stringify(responseBody));
         }
         // Otherwise, if the service is to receive a feature request:
         else if (segments[0] === 'requestFeature') {
-          const {feature} = postData;
+          const {feature} = postData as {feature: string};
           // Get the response body.
-          const responseBody = await require(path.join(__dirname, 'api', 'requestFeature'))
-          .response([feature]);
+          const responseBody = await apiRespond.requestFeature([feature]);
           // Send it.
           setHeaders('application/json', null, 'ultra');
           response.end(JSON.stringify(responseBody));
@@ -893,10 +966,23 @@ const requestHandler = async (request, response) => {
         }
       }
       // Otherwise, if it is a tutorial comment:
-      else if (pageName === 'tutorialComment.html') {
-        const {content} = postData;
+      else if (pageName === 'tutorialWebComment.html') {
+        const {content} = postData as {content?: unknown};
+        setHeaders('application/json', null, 'low');
+        const answerData = await handleTutorialWebComment(content);
+        if (answerData.status === 'ok') {
+          response.end(JSON.stringify({status: 'ok'}));
+        }
+        else {
+          response.statusCode = 400;
+          response.end(JSON.stringify({status: 'error', message: answerData.message}));
+        }
+      }
+      // Otherwise, if it is an AI tutorial comment:
+      else if (pageName === 'tutorialAIComment.html') {
+        const {content} = postData as {content?: unknown};
         setHeaders('application/json', null, 'low');
-        const answerData = await handleComment(content);
+        const answerData = await handleTutorialAIComment(content);
         if (answerData.status === 'ok') {
           response.end(JSON.stringify({status: 'ok'}));
         }
@@ -913,14 +999,26 @@ const requestHandler = async (request, response) => {
     await serveError({message: 'ERROR: Invalid request method'}, response, true);
   }
 };
+// Handles a request, converting any error not already handled by handleRequest (i.e. one
+// that should never occur, such as a job or report file becoming unreadable or corrupt)
+// into a safe response instead of letting it crash the process as an unhandled rejection.
+const requestHandler = async (request: IncomingMessage, response: ServerResponse) => {
+  try {
+    await handleRequest(request, response);
+  }
+  catch (error: unknown) {
+    console.error(`ERROR: Unhandled request error (${errorMessage(error)})`);
+    await serveError({message: 'ERROR: Internal server error'}, response, false, 500);
+  }
+};
 
 // EXPORTS
 
-exports.requestHandler = requestHandler;
+export {requestHandler};
 
 // SERVER
 
-const serve = async (protocolModule, options) => {
+const serve = async (protocolModule: typeof http | typeof https, options: {key?: string; cert?: string}) => {
   // Create any missing directories.
   for (const path of [queuePath(), claimedPath(), failedPath(), hiddenReportsPath(), reportsPath()]) {
     await fs.mkdir(path, {recursive: true});
@@ -929,16 +1027,17 @@ const serve = async (protocolModule, options) => {
     ? https.createServer(options, requestHandler)
     : http.createServer(requestHandler);
   const port = process.env.PORT || '3000';
+  const protocol = process.env.PROTOCOL || 'http';
   server.listen(port, () => {
     console.log(`Kilotest server listening at ${protocol}://localhost:${port}.`);
   });
   return server;
 };
 
-exports.serve = serve;
+export {serve};
 
 // Starts the server using the configured protocol and credentials.
-exports.startServer = async () => {
+export const startServer = async () => {
   const startProtocol = process.env.PROTOCOL || 'http';
   if (startProtocol === 'http') {
     console.log('Starting HTTP server');
@@ -946,19 +1045,19 @@ exports.startServer = async () => {
   }
   else if (startProtocol === 'https') {
     console.log('Starting HTTPS server');
-    const key = await fs.readFile(process.env.KEY, 'utf8');
-    const cert = await fs.readFile(process.env.CERT, 'utf8');
+    const key = await fs.readFile(process.env.KEY as string, 'utf8');
+    const cert = await fs.readFile(process.env.CERT as string, 'utf8');
     return serve(https, {key, cert});
   }
 };
 
-// Runs the server if the module was loaded directly (not required by a test).
-exports.runIfMain = (mainModule, currentModule) => {
+// Runs the server if the module was loaded directly (not required by a test). The starter is a parameter so tests can inject a spy, since ESM module exports cannot be monkey-patched.
+export const runIfMain = (mainModule: unknown, currentModule: unknown, starter: () => Promise<unknown> = startServer) => {
   if (mainModule === currentModule) {
-    exports.startServer().catch(error => console.log(error.message));
+    starter().catch(error => console.log(errorMessage(error)));
   }
 };
 
 // EXECUTION
 
-exports.runIfMain(require.main, module);
+runIfMain(import.meta.main, true);